@pixerate/editor 0.162.1 → 0.164.0

package/dist/canvas/types.d.ts

@@ -149,12 +149,38 @@ export type DisplacementDirection = 'right' | 'left' | 'down' | 'up' | 'vertical
  * Options for directional displacement calculation.
  */
 export interface DirectionalDisplacementOptions {
+    /** Which nodes move and where: `right` / `left` / `up` / `down` push one side; `vertical` opens the row up and down. Default `right`. */
     direction?: DisplacementDirection;
+    /** Clearance between the child cluster and displaced nodes, in canvas units. Default 40. */
     gap?: number;
+    /** With `right`, also push nodes in the origin's column that overlap the cluster up or down. Default false. */
     spreadSiblingLanes?: boolean;
+    /** Distance in canvas units within which a node counts as a sibling (same column for `right`, same row for `row-lane`). Default 50. */
     siblingTolerance?: number;
+    /**
+     * Floor for the top edge of nodes moved upward (e.g. below a pinned header). Rows pushed into it
+     * stack from `minY` down by `rowSpacing` so they never overlap, and never move below where they started.
+     */
     minY?: number;
+    /**
+     * Ceiling for the bottom edge of nodes moved downward. Rows pushed into it stack from `maxY` up by
+     * `rowSpacing`, and never move above where they started.
+     */
+    maxY?: number;
+    /**
+     * `freeform` (default) moves nodes by the exact clearance. `row-lane` treats the canvas as rows
+     * `rowSpacing` apart: nodes are bucketed into lanes relative to the origin row, the origin's lane
+     * stays put, and vertical deltas are rounded up to whole lanes so rows glide apart by exact lane heights.
+     */
+    layoutMode?: 'freeform' | 'row-lane';
+    /**
+     * Lane height in canvas units. Required for `row-lane` (default: the origin's height); also the
+     * spacing between rows stacked against `minY` / `maxY` (default: the tallest node in those rows).
+     */
+    rowSpacing?: number;
 }
+/** How existing nodes make room when a node explodes. */
+export type ExplosionDisplacementStrategy = 'directional' | 'dagre' | 'none';
 /**
  * Options for Dagre reflow displacement calculation.
  */
@@ -181,8 +207,7 @@ export interface ExplodeNodeOptions<TNode extends CanvasNode = CanvasNode, TEdge
     childNodes: TNode[];
     childEdges?: TEdge[];
     connectParentToChildren?: boolean | 'first' | 'all';
-    connectChildrenToDownstream?: boolean;
-    displacementStrategy?: 'directional' | 'dagre' | 'none';
+    displacementStrategy?: ExplosionDisplacementStrategy;
     directionalOptions?: DirectionalDisplacementOptions;
     reflowOptions?: Partial<ReflowDisplacementOptions>;
     trajectory?: TrajectoryFunction;

package/dist/chart/commands.d.cts

@@ -10,7 +10,8 @@ export interface ChartCommandOptions {
 }
 /**
  * Palette and agent commands for a chart: describe, update presentation, replace data, set
- * values, add / remove series, categories and trendlines, apply presets, switch rows and
+ * values, add / remove series, categories, trendlines and reference lines and bands, pin
+ * callouts, highlight, apply presets, switch rows and
  * columns, import CSV or Mermaid, export SVG, Mermaid or Office XML, recommend types and
  * check colours. Register them in a `CommandRegistry` and agents get them through
  * `createCommandToolProvider`; `createChartToolProvider` offers the same operations as

package/dist/chart/commands.d.ts

@@ -10,7 +10,8 @@ export interface ChartCommandOptions {
 }
 /**
  * Palette and agent commands for a chart: describe, update presentation, replace data, set
- * values, add / remove series, categories and trendlines, apply presets, switch rows and
+ * values, add / remove series, categories, trendlines and reference lines and bands, pin
+ * callouts, highlight, apply presets, switch rows and
  * columns, import CSV or Mermaid, export SVG, Mermaid or Office XML, recommend types and
  * check colours. Register them in a `CommandRegistry` and agents get them through
  * `createCommandToolProvider`; `createChartToolProvider` offers the same operations as

package/dist/chart/controller.d.cts

@@ -1,7 +1,8 @@
 import { HistoryManager } from '../history/HistoryManager.cjs';
 import { type ChartTrendFit } from './trend.cjs';
+import { type ChartTreeRow } from './tree.cjs';
 import { type ChartTableOptions } from './spec.cjs';
-import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.cjs';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.cjs';
 export interface ChartControllerOptions {
     /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
     spec?: Partial<ChartSpec> | unknown;
@@ -54,6 +55,7 @@ export interface ChartSeriesInput {
     x?: readonly unknown[];
     sizes?: readonly unknown[];
     pointColors?: readonly (string | null)[];
+    callouts?: readonly (string | null)[];
     marker?: ChartMarker;
     curve?: ChartCurve;
     dataLabels?: boolean;
@@ -74,6 +76,8 @@ export interface ChartSeriesPatch {
     x?: readonly unknown[] | null;
     sizes?: readonly unknown[] | null;
     pointColors?: readonly (string | null)[] | null;
+    /** One label per category (null: none); `null` removes them all. */
+    callouts?: readonly (string | null)[] | null;
     marker?: ChartMarker | null;
     curve?: ChartCurve | null;
     dataLabels?: boolean | null;
@@ -188,6 +192,9 @@ export declare class ChartController {
     }): {
         ok: true;
         index: number;
+    } | {
+        ok: false;
+        message: string;
     };
     removeCategory(index: number): ChartActionResult;
     renameCategory(index: number, label: string): ChartActionResult;
@@ -213,6 +220,107 @@ export declare class ChartController {
     }): ChartActionResult & {
         issues?: ChartIssue[];
     };
+    /** A refusal while the data is a tree (cell edits would be overwritten by its totals), else null. */
+    private treeLocked;
+    /** Replaces the grouped data (an empty list goes back to the table, keeping the totals as values). One undo step. */
+    setTree(tree: unknown, options?: ChartEditOptions): ChartActionResult;
+    /**
+     * Replaces the grouped data from rows of names and a value (group, …, item, value), as the
+     * data grid edits it; colours of nodes whose path is unchanged are kept. All-or-nothing.
+     */
+    setTreeRows(rows: readonly ChartTreeRow[] | readonly {
+        path: readonly unknown[];
+        value: unknown;
+    }[], options?: ChartEditOptions): ChartActionResult;
+    /** Replaces the data with a table of names and values (group, …, item, value); see `chartTreeFromTable`. */
+    importTreeTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private nodeAt;
+    /** Adds a node under the group at `parent` ([] for the top level) at `at` (default: the end). Returns its path. */
+    addTreeNode(parent: readonly string[], input: {
+        name: string;
+        value?: number;
+        color?: string;
+        children?: unknown[];
+    }, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Renames, revalues (items only) or recolours a node; `color: null` goes back to the palette. Returns its path. */
+    updateTreeNode(path: readonly string[], patch: {
+        name?: string;
+        value?: number;
+        color?: string | null;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
+    removeTreeNode(path: readonly string[]): ChartActionResult;
+    /** Sets the note written under the chart ("" removes it). */
+    setNote(note: string): ChartActionResult;
+    /**
+     * Draws the named categories (labels) and series (names or ids) normally and mutes the
+     * rest; an empty list shows everything. Unknown names change nothing. Returns the category
+     * indexes and series ids that matched.
+     */
+    setHighlight(names: readonly string[]): {
+        ok: true;
+        categories: number[];
+        series: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Why a reference on `axis` at `values` cannot be drawn on this chart, or null. */
+    private referenceProblem;
+    private editReferences;
+    /** Adds a reference line (a target, floor or average). Returns its index. */
+    addReferenceLine(input: ChartReferenceLine): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference line (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceLine(index: number, patch: {
+        [K in keyof ChartReferenceLine]?: ChartReferenceLine[K] | null;
+    }): ChartActionResult;
+    removeReferenceLine(index: number): ChartActionResult;
+    /** Adds a reference band (a target range). Returns its index. */
+    addReferenceBand(input: ChartReferenceBand): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference band (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceBand(index: number, patch: {
+        [K in keyof ChartReferenceBand]?: ChartReferenceBand[K] | null;
+    }): ChartActionResult;
+    removeReferenceBand(index: number): ChartActionResult;
+    private noReference;
+    /**
+     * Pins a label to one bar or point (`null` or "" removes it) and selects the point. The
+     * point must have a value, on a bar, line, area, scatter or bubble chart.
+     */
+    setCallout(seriesId: string, index: number, label: string | null): ChartActionResult;
     /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
     addTrendline(seriesId: string, input: ChartTrendline): {
         ok: true;

package/dist/chart/controller.d.ts

@@ -1,7 +1,8 @@
 import { HistoryManager } from '../history/HistoryManager.js';
 import { type ChartTrendFit } from './trend.js';
+import { type ChartTreeRow } from './tree.js';
 import { type ChartTableOptions } from './spec.js';
-import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.js';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartMarker, ChartNumberFormat, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.js';
 export interface ChartControllerOptions {
     /** Starting chart (any partial or saved spec; problems are reported in `state.issues`). */
     spec?: Partial<ChartSpec> | unknown;
@@ -54,6 +55,7 @@ export interface ChartSeriesInput {
     x?: readonly unknown[];
     sizes?: readonly unknown[];
     pointColors?: readonly (string | null)[];
+    callouts?: readonly (string | null)[];
     marker?: ChartMarker;
     curve?: ChartCurve;
     dataLabels?: boolean;
@@ -74,6 +76,8 @@ export interface ChartSeriesPatch {
     x?: readonly unknown[] | null;
     sizes?: readonly unknown[] | null;
     pointColors?: readonly (string | null)[] | null;
+    /** One label per category (null: none); `null` removes them all. */
+    callouts?: readonly (string | null)[] | null;
     marker?: ChartMarker | null;
     curve?: ChartCurve | null;
     dataLabels?: boolean | null;
@@ -188,6 +192,9 @@ export declare class ChartController {
     }): {
         ok: true;
         index: number;
+    } | {
+        ok: false;
+        message: string;
     };
     removeCategory(index: number): ChartActionResult;
     renameCategory(index: number, label: string): ChartActionResult;
@@ -213,6 +220,107 @@ export declare class ChartController {
     }): ChartActionResult & {
         issues?: ChartIssue[];
     };
+    /** A refusal while the data is a tree (cell edits would be overwritten by its totals), else null. */
+    private treeLocked;
+    /** Replaces the grouped data (an empty list goes back to the table, keeping the totals as values). One undo step. */
+    setTree(tree: unknown, options?: ChartEditOptions): ChartActionResult;
+    /**
+     * Replaces the grouped data from rows of names and a value (group, …, item, value), as the
+     * data grid edits it; colours of nodes whose path is unchanged are kept. All-or-nothing.
+     */
+    setTreeRows(rows: readonly ChartTreeRow[] | readonly {
+        path: readonly unknown[];
+        value: unknown;
+    }[], options?: ChartEditOptions): ChartActionResult;
+    /** Replaces the data with a table of names and values (group, …, item, value); see `chartTreeFromTable`. */
+    importTreeTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private nodeAt;
+    /** Adds a node under the group at `parent` ([] for the top level) at `at` (default: the end). Returns its path. */
+    addTreeNode(parent: readonly string[], input: {
+        name: string;
+        value?: number;
+        color?: string;
+        children?: unknown[];
+    }, options?: {
+        at?: number;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Renames, revalues (items only) or recolours a node; `color: null` goes back to the palette. Returns its path. */
+    updateTreeNode(path: readonly string[], patch: {
+        name?: string;
+        value?: number;
+        color?: string | null;
+    }): {
+        ok: true;
+        path: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
+    removeTreeNode(path: readonly string[]): ChartActionResult;
+    /** Sets the note written under the chart ("" removes it). */
+    setNote(note: string): ChartActionResult;
+    /**
+     * Draws the named categories (labels) and series (names or ids) normally and mutes the
+     * rest; an empty list shows everything. Unknown names change nothing. Returns the category
+     * indexes and series ids that matched.
+     */
+    setHighlight(names: readonly string[]): {
+        ok: true;
+        categories: number[];
+        series: string[];
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Why a reference on `axis` at `values` cannot be drawn on this chart, or null. */
+    private referenceProblem;
+    private editReferences;
+    /** Adds a reference line (a target, floor or average). Returns its index. */
+    addReferenceLine(input: ChartReferenceLine): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference line (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceLine(index: number, patch: {
+        [K in keyof ChartReferenceLine]?: ChartReferenceLine[K] | null;
+    }): ChartActionResult;
+    removeReferenceLine(index: number): ChartActionResult;
+    /** Adds a reference band (a target range). Returns its index. */
+    addReferenceBand(input: ChartReferenceBand): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a reference band (all-or-nothing); `null` removes its label, colour or axis. */
+    updateReferenceBand(index: number, patch: {
+        [K in keyof ChartReferenceBand]?: ChartReferenceBand[K] | null;
+    }): ChartActionResult;
+    removeReferenceBand(index: number): ChartActionResult;
+    private noReference;
+    /**
+     * Pins a label to one bar or point (`null` or "" removes it) and selects the point. The
+     * point must have a value, on a bar, line, area, scatter or bubble chart.
+     */
+    setCallout(seriesId: string, index: number, label: string | null): ChartActionResult;
     /** Adds a trendline to a series and selects it. Returns its index (and the fit, when it can be computed). */
     addTrendline(seriesId: string, input: ChartTrendline): {
         ok: true;