fix(types): support nested attribute path strings in relayout, restyle, and update

draftlogs/8050_fix.md

@@ -0,0 +1 @@
+- Support nested attribute path strings in `relayout`, `restyle`, and `update` TypeScript definitions [[#8050](https://github.com/plotly/plotly.js/pull/8050)], with thanks to @CAOShurong for the contribution!

lib/index.d.ts

@@ -59,6 +59,7 @@ export type {
     ModeBarButton,
     ModeBarButtonAny,
     ModeBarDefaultButtons,
+    LayoutUpdate,
     Template
 } from '../src/types/core/layout';
 

src/types/core/api.d.ts

@@ -208,30 +208,64 @@ export function newPlot(
     figure: PlotlyDataLayoutConfig
 ): Promise<PlotlyHTMLElement>;
 
-/** Update layout properties on an existing plot. */
+/**
+ * Update layout properties on an existing plot using an update object.
+ *
+ * @param root - Graph div id or element
+ * @param layout - Partial layout object or attribute path mapping (e.g. `{'xaxis.autorange': true}`)
+ */
 export function relayout(root: Root, layout: Partial<Layout>): Promise<PlotlyHTMLElement>;
+/**
+ * Update a single layout property on an existing plot using an attribute path string.
+ *
+ * @param root - Graph div id or element
+ * @param astr - Attribute path string (e.g. `'xaxis.autorange'`, `'title.text'`)
+ * @param val - Value to assign to the attribute
+ */
+export function relayout(root: Root, astr: string, 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 using an update object.
+ *
+ * @param root - Graph div id or element
+ * @param aobj - Update object with trace properties or attribute paths
+ * @param traces - Trace index/indices to update (defaults to all)
+ */
+export function restyle(
+    root: Root,
+    aobj: Partial<Data> | Record<string, any>,
+    traces?: number[] | number
+): Promise<PlotlyHTMLElement>;
+/**
+ * Update a single trace property on an existing plot using an attribute path string.
  *
- * @param aobj - Update object whose keys are attribute paths
+ * @param root - Graph div id or element
+ * @param astr - Attribute path string (e.g. `'marker.color'`)
+ * @param val - Value or array of values to assign to the attribute
  * @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,
+    astr: string,
+    val: any,
+    traces?: number[] | number
+): Promise<PlotlyHTMLElement>;
 
 /**
  * Update both trace and layout properties in a single call.
  *
- * @param traceUpdate - Per-trace updates
- * @param layoutUpdate - Layout updates
+ * @param root - Graph div id or element
+ * @param traceUpdate - Per-trace updates or attribute paths
+ * @param layoutUpdate - Layout updates or attribute paths
  * @param traces - Trace index/indices `traceUpdate` applies to
  */
 export function update(
     root: Root,
-    traceUpdate: Data,
+    traceUpdate: Partial<Data> | Record<string, any>,
     layoutUpdate: Partial<Layout>,
     traces?: number[] | number
 ): Promise<PlotlyHTMLElement>;

src/types/core/layout.d.ts

@@ -157,3 +157,16 @@ export interface Template {
     /** Template layout defaults. */
     layout?: Partial<Layout> | undefined;
 }
+
+// ---------------------------------------------------------------------------
+// Relayout & update types
+// ---------------------------------------------------------------------------
+
+/**
+ * Layout update object accepted by `Plotly.relayout` and `Plotly.update`.
+ *
+ * An alias for `Partial<Layout>`, which supports both standard nested layout
+ * properties and dotted/indexed attribute paths (e.g. `'xaxis.autorange'`).
+ */
+export type LayoutUpdate = Partial<Layout>;
+

src/types/generated/schema.d.ts

@@ -16606,6 +16606,27 @@ export interface Layout {
     [key: `ternary${number}`]: TernaryLayout;
     [key: `xaxis${number}`]: LayoutAxis;
     [key: `yaxis${number}`]: LayoutAxis;
+
+    // Nested property updates for relayout and update
+    'xaxis.autorange'?: LayoutAxis['autorange'];
+    'yaxis.autorange'?: LayoutAxis['autorange'];
+    'xaxis.range'?: LayoutAxis['range'];
+    'xaxis.range[0]'?: any;
+    'xaxis.range[1]'?: any;
+    'yaxis.range'?: LayoutAxis['range'];
+    'yaxis.range[0]'?: any;
+    'yaxis.range[1]'?: any;
+    'xaxis.type'?: LayoutAxis['type'];
+    'yaxis.type'?: LayoutAxis['type'];
+    'xaxis.title'?: string | LayoutAxis['title'];
+    'yaxis.title'?: string | LayoutAxis['title'];
+    'xaxis.title.text'?: string;
+    'yaxis.title.text'?: string;
+    'title.text'?: string;
+
+    // Dotted and indexed attribute path index signatures
+    [key: `${string}.${string}`]: any;
+    [key: `${string}[${string}`]: any;
 }
 
 // ---------------------------------------------------------------------------

tasks/generate_schema_types.mjs

@@ -1112,6 +1112,29 @@ function generateLayoutProperties(layoutAttrs, sharedTypes, subplotGroups, array
         }
     }
 
+    // Nested property updates for relayout and update (common axis/title properties)
+    lines.push('');
+    lines.push('    // Nested property updates for relayout and update');
+    lines.push("    'xaxis.autorange'?: LayoutAxis['autorange'];");
+    lines.push("    'yaxis.autorange'?: LayoutAxis['autorange'];");
+    lines.push("    'xaxis.range'?: LayoutAxis['range'];");
+    lines.push("    'xaxis.range[0]'?: any;");
+    lines.push("    'xaxis.range[1]'?: any;");
+    lines.push("    'yaxis.range'?: LayoutAxis['range'];");
+    lines.push("    'yaxis.range[0]'?: any;");
+    lines.push("    'yaxis.range[1]'?: any;");
+    lines.push("    'xaxis.type'?: LayoutAxis['type'];");
+    lines.push("    'yaxis.type'?: LayoutAxis['type'];");
+    lines.push("    'xaxis.title'?: string | LayoutAxis['title'];");
+    lines.push("    'yaxis.title'?: string | LayoutAxis['title'];");
+    lines.push("    'xaxis.title.text'?: string;");
+    lines.push("    'yaxis.title.text'?: string;");
+    lines.push("    'title.text'?: string;");
+    lines.push('');
+    lines.push('    // Dotted and indexed attribute path index signatures');
+    lines.push('    [key: `${string}.${string}`]: any;');
+    lines.push('    [key: `${string}[${string}`]: any;');
+
     return lines;
 }