fix(types): Accept attribute paths in plotly_relayout, relayout, restyle, and update

.github/workflows/ci.yml

@@ -586,6 +586,16 @@ jobs:
       - name: Type-check TypeScript sources
         run: npm run typecheck
 
+  test-types:
+    needs: install-and-cibuild
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: ./.github/actions/setup-workspace
+
+      - name: Test the public TypeScript types
+        run: npm run test-types
+
   generated-types-drift:
     needs: install-and-cibuild
     runs-on: ubuntu-latest

draftlogs/8126_fix.md

@@ -0,0 +1,3 @@
+- Update TypeScript types so that `Plotly.relayout`, `Plotly.restyle`, `Plotly.update`, and the `plotly_relayout` event accept attribute paths such as `'xaxis.autorange'` [[#8126](https://github.com/plotly/plotly.js/pull/8126)]
+  - Add the `LayoutUpdate` and `DataUpdate` types for these update objects
+  - Add the `(root, attribute, value)` call form to the types of `Plotly.relayout` and `Plotly.restyle`

lib/index.d.ts

@@ -55,7 +55,9 @@ export type * from '../src/types/generated/schema';
 
 export type {
     ButtonClickEvent,
+    DataUpdate,
     Icon,
+    LayoutUpdate,
     ModeBarButton,
     ModeBarButtonAny,
     ModeBarDefaultButtons,

package.json

@@ -65,6 +65,7 @@
     "test-mock": "node tasks/test_mock.mjs",
     "test-image": "node test/image/compare_pixels_test.mjs",
     "test-export": "node test/image/export_test.js",
+    "test-types": "tsc --noEmit -p test/types",
     "test-syntax": "tsx tasks/test_syntax.js && npm run find-strings -- --no-output",
     "test-bundle": "node tasks/test_bundle.js",
     "test-plain-obj": "node tasks/test_plain_obj.mjs",

src/types/core/api.d.ts

@@ -5,7 +5,7 @@
 import type { AnimationOpts, Data, Frame, Layout } from '../generated/schema';
 import type { Config, DownloadImgopts, ToImgopts } from './config';
 import type { PlotlyHTMLElement } from './events';
-import type { Icon, Template } from './layout';
+import type { DataUpdate, Icon, LayoutUpdate, Template } from './layout';
 
 // ---------------------------------------------------------------------------
 // Roots and request shapes
@@ -208,19 +208,57 @@ export function newPlot(
     figure: PlotlyDataLayoutConfig
 ): Promise<PlotlyHTMLElement>;
 
-/** Update layout properties on an existing plot. */
-export function relayout(root: Root, layout: Partial<Layout>): Promise<PlotlyHTMLElement>;
+/**
+ * Update layout properties on an existing plot with an update object.
+ *
+ * @param layout - Update object whose keys are layout properties or attribute paths
+ */
+export function relayout(root: Root, layout: LayoutUpdate): Promise<PlotlyHTMLElement>;
+/**
+ * Update one layout property on an existing plot with an attribute path.
+ *
+ * @param astr - Attribute path, for example `'xaxis.autorange'`
+ * @param val - New value of the attribute
+ */
+export function relayout(root: Root, astr: string, val: any): Promise<PlotlyHTMLElement>;
+/**
+ * Update layout properties on an existing plot with either call form.
+ *
+ * This signature lets a wrapper read the parameter types with `Parameters<typeof relayout>`.
+ * It does not check that the value matches the form.
+ */
+export function relayout(root: Root, astr: string | LayoutUpdate, val?: any): Promise<PlotlyHTMLElement>;
 /** Re-render the plot at `root` from its current data/layout. */
 export function redraw(root: Root): Promise<PlotlyHTMLElement>;
 /** Remove a plot and its event listeners from the DOM. */
 export function purge(root: Root): void;
 /**
- * Update trace properties (style) on the existing plot.
+ * Update trace properties (style) on the existing plot with an update object.
  *
- * @param aobj - Update object whose keys are attribute paths
+ * @param aobj - Update object whose keys are trace properties or attribute paths
  * @param traces - Trace index/indices to update (defaults to all)
  */
-export function restyle(root: Root, aobj: Data, traces?: number[] | number): Promise<PlotlyHTMLElement>;
+export function restyle(root: Root, aobj: DataUpdate, traces?: number[] | number): Promise<PlotlyHTMLElement>;
+/**
+ * Update one trace property on the existing plot with an attribute path.
+ *
+ * @param astr - Attribute path, for example `'marker.color'`
+ * @param val - New value of the attribute, or an array with one value for each trace
+ * @param traces - Trace index/indices to update (defaults to all)
+ */
+export function restyle(root: Root, astr: string, val: any, traces?: number[] | number): Promise<PlotlyHTMLElement>;
+/**
+ * Update trace properties (style) on the existing plot with either call form.
+ *
+ * This signature lets a wrapper read the parameter types with `Parameters<typeof restyle>`.
+ * It does not check that the arguments match the form.
+ */
+export function restyle(
+    root: Root,
+    astr: string | DataUpdate,
+    val?: any,
+    traces?: number[] | number
+): Promise<PlotlyHTMLElement>;
 
 /**
  * Update both trace and layout properties in a single call.
@@ -231,8 +269,8 @@ export function restyle(root: Root, aobj: Data, traces?: number[] | number): Pro
  */
 export function update(
     root: Root,
-    traceUpdate: Data,
-    layoutUpdate: Partial<Layout>,
+    traceUpdate: DataUpdate,
+    layoutUpdate: LayoutUpdate,
     traces?: number[] | number
 ): Promise<PlotlyHTMLElement>;
 

src/types/core/events.d.ts

@@ -17,6 +17,7 @@ import type {
 } from '../generated/schema';
 import type { Datum } from '../lib/common';
 import type { Config } from './config';
+import type { LayoutUpdate } from './layout';
 
 // ---------------------------------------------------------------------------
 // Point / datum types in events
@@ -149,23 +150,12 @@ export interface PlotRestyleEventUpdate {
 export type PlotRestyleEvent = [PlotRestyleEventUpdate, number[]];
 
 /**
- * Payload for `plotly_relayout`. Carries a `Partial<Layout>` plus a few
- * common bracketed axis-range/autorange keys that flatten nested updates.
+ * Payload for `plotly_relayout`. The keys are layout properties or attribute
+ * paths of the changed values, for example `'xaxis.range[0]'`. A value behind an
+ * attribute path has the type `any`, because a range value can be a number or a
+ * date string.
  */
-export interface PlotRelayoutEvent extends Partial<Layout> {
-    /** New x-axis range minimum, when the user changed the range. */
-    'xaxis.range[0]'?: number;
-    /** New x-axis range maximum, when the user changed the range. */
-    'xaxis.range[1]'?: number;
-    /** New y-axis range minimum, when the user changed the range. */
-    'yaxis.range[0]'?: number;
-    /** New y-axis range maximum, when the user changed the range. */
-    'yaxis.range[1]'?: number;
-    /** True when the user toggled x-axis autoranging on. */
-    'xaxis.autorange'?: boolean;
-    /** True when the user toggled y-axis autoranging on. */
-    'yaxis.autorange'?: boolean;
-}
+export type PlotRelayoutEvent = LayoutUpdate;
 
 // ---------------------------------------------------------------------------
 // 3D scene / annotation / animation / legend events

src/types/core/layout.d.ts

@@ -157,3 +157,30 @@ export interface Template {
     /** Template layout defaults. */
     layout?: Partial<Layout> | undefined;
 }
+
+// ---------------------------------------------------------------------------
+// Update objects (relayout / restyle / update)
+// ---------------------------------------------------------------------------
+
+/** Keys that hold an attribute path such as `'xaxis.range[0]'` or `'annotations[0].text'`. */
+interface AttributePathKeys {
+    [key: `${string}.${string}`]: any;
+    [key: `${string}[${string}`]: any;
+}
+
+/**
+ * Layout update for `Plotly.relayout` and `Plotly.update`.
+ *
+ * A key is a layout property or an attribute path, for example `'xaxis.range[0]'` or `'annotations[0].text'`.
+ * An attribute path changes one property and keeps its siblings. A nested object replaces the whole container.
+ * A value behind an attribute path has the type `any`.
+ */
+export type LayoutUpdate = Partial<Layout> & AttributePathKeys;
+
+/**
+ * Trace update for `Plotly.restyle` and `Plotly.update`.
+ *
+ * A key is a trace property or an attribute path, for example `'marker.color'`.
+ * A value behind an attribute path has the type `any`.
+ */
+export type DataUpdate = Partial<Data> & AttributePathKeys;

test/types/relayout_event.ts

@@ -0,0 +1,23 @@
+/**
+ * Consumer-side checks for the `plotly_relayout` event payload.
+ *
+ * Nothing here runs. See `update_api.ts`.
+ */
+
+import type { PlotRelayoutEvent } from '../../lib/index';
+
+declare const event: PlotRelayoutEvent;
+
+// A range value can be a number or a date string
+const numberRangeStart: number | undefined = event['xaxis.range[0]'];
+const dateRangeStart: string | undefined = event['xaxis.range[0]'];
+
+// Any other attribute path is readable
+const secondAxisStart = event['xaxis2.range[0]'];
+const shapeStart = event['shapes[0].x0'];
+
+// Layout properties are still typed
+const autosize: boolean | undefined = event.autosize;
+
+// @ts-expect-error unknown top-level key
+const typo = event.titl;

test/types/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["./**/*.ts"],
+  "exclude": []
+}

test/types/update_api.ts

@@ -0,0 +1,83 @@
+/**
+ * Consumer-side checks for the `relayout`, `restyle` and `update` types.
+ *
+ * Nothing here runs. `npm run test-types` compiles this file against the public entry point.
+ * A line marked `@ts-expect-error` must fail to compile, so the build breaks if a type becomes too permissive.
+ */
+
+import * as Plotly from '../../lib/index';
+
+declare const gd: HTMLElement;
+
+// ---------------------------------------------------------------------------
+// relayout
+// ---------------------------------------------------------------------------
+
+Plotly.relayout(gd, { 'xaxis.autorange': true });
+Plotly.relayout(gd, { 'xaxis.range[0]': 0, 'xaxis.range[1]': 5 });
+Plotly.relayout(gd, { 'xaxis.title.font.size': 14 });
+Plotly.relayout(gd, { 'annotations[0].text': 'hello' });
+Plotly.relayout(gd, { 'updatemenus[0].buttons[1].label': 'hello' });
+Plotly.relayout(gd, { xaxis: { autorange: true } });
+Plotly.relayout(gd, { autosize: true });
+Plotly.relayout(gd, 'xaxis.autorange', true);
+Plotly.relayout(gd, 'annotations[0].text', 'hello');
+
+// @ts-expect-error top-level typo
+Plotly.relayout(gd, { titl: 'abc' });
+// @ts-expect-error wrong value type on a known top-level key
+Plotly.relayout(gd, { autosize: 'yes' });
+
+// A wrapper that reads the parameter types must see both call forms
+type RelayoutArg = Parameters<typeof Plotly.relayout>[1];
+export const relayoutObject: RelayoutArg = { autosize: true };
+export const relayoutPath: RelayoutArg = 'xaxis.autorange';
+
+// ---------------------------------------------------------------------------
+// restyle
+// ---------------------------------------------------------------------------
+
+Plotly.restyle(gd, { 'marker.color': 'red' });
+Plotly.restyle(gd, { 'marker.color': 'red' }, [0]);
+Plotly.restyle(gd, { 'line.width': 2, 'marker.size[0]': 10 }, 1);
+Plotly.restyle(gd, { visible: false });
+Plotly.restyle(gd, 'marker.color', 'red');
+Plotly.restyle(gd, 'marker.color', ['red', 'blue'], [0, 1]);
+
+// @ts-expect-error top-level typo
+Plotly.restyle(gd, { colr: 'red' });
+// @ts-expect-error wrong value type on a known top-level key
+Plotly.restyle(gd, { visible: 'maybe' });
+
+type RestyleArg = Parameters<typeof Plotly.restyle>[1];
+export const restyleObject: RestyleArg = { visible: false };
+export const restylePath: RestyleArg = 'marker.color';
+
+// ---------------------------------------------------------------------------
+// update
+// ---------------------------------------------------------------------------
+
+Plotly.update(gd, { 'marker.color': 'red' }, { 'xaxis.range[0]': 0 });
+Plotly.update(gd, { 'marker.color': 'red' }, { 'xaxis.range[0]': 0 }, [0]);
+Plotly.update(gd, { visible: false }, { autosize: true });
+
+// @ts-expect-error top-level typo in the trace update
+Plotly.update(gd, { colr: 'red' }, { autosize: true });
+// @ts-expect-error top-level typo in the layout update
+Plotly.update(gd, { visible: false }, { titl: 'abc' });
+
+// ---------------------------------------------------------------------------
+// APIs that take a full figure must stay strict about unknown keys
+// ---------------------------------------------------------------------------
+
+Plotly.newPlot(gd, [], { autosize: true });
+Plotly.validate([], { autosize: true });
+
+// @ts-expect-error a dotted path is not a valid key in a full layout
+Plotly.newPlot(gd, [], { 'xaxis.autorange': true });
+// @ts-expect-error a dotted typo must not pass in a full layout
+Plotly.newPlot(gd, [], { 'xaxis.autrange': true });
+// @ts-expect-error a dotted path is not a valid key when validating a layout
+Plotly.validate([], { 'xaxis.autorange': true });
+// @ts-expect-error a dotted path is not a valid key in a template layout
+const template: Plotly.Template = { layout: { 'xaxis.autorange': true } };