@pixerate/editor 0.163.0 → 0.165.0

package/dist/canvas/types.d.cts

@@ -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/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/controller.d.cts

@@ -2,7 +2,7 @@ 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, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.cjs';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartLink, 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;
@@ -220,7 +220,7 @@ 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. */
+    /** A refusal while the data is a tree or flows (cell edits would be overwritten by their 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;
@@ -268,6 +268,35 @@ export declare class ChartController {
     };
     /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
     removeTreeNode(path: readonly string[]): ChartActionResult;
+    /**
+     * Replaces the flows (and, when given, the node order). An empty list goes back to the
+     * table, keeping how much passed through each node as values. One undo step, all-or-nothing.
+     */
+    setLinks(links: unknown, options?: ChartEditOptions & {
+        nodes?: readonly string[];
+    }): ChartActionResult;
+    /** Replaces the data with flows from a table of source, target and value columns. */
+    importLinksTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private badLink;
+    /** Adds a flow and returns its index. */
+    addLink(link: ChartLink): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a flow's source, target, value or colour (`color: null` goes back to the default). */
+    updateLink(index: number, patch: {
+        source?: string;
+        target?: string;
+        value?: number;
+        color?: string | null;
+    }): ChartActionResult;
+    removeLink(index: number): ChartActionResult;
     /** Sets the note written under the chart ("" removes it). */
     setNote(note: string): ChartActionResult;
     /**

package/dist/chart/controller.d.ts

@@ -2,7 +2,7 @@ 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, ChartReferenceBand, ChartReferenceLine, ChartSelection, ChartSeries, ChartSeriesType, ChartSpec, ChartTrendline, ChartType } from './types.js';
+import type { ChartAxis, ChartIssue, ChartCurve, ChartErrorBars, ChartLegend, ChartLink, 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;
@@ -220,7 +220,7 @@ 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. */
+    /** A refusal while the data is a tree or flows (cell edits would be overwritten by their 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;
@@ -268,6 +268,35 @@ export declare class ChartController {
     };
     /** Removes a node (with everything under it). A group left empty becomes an item with value 0. */
     removeTreeNode(path: readonly string[]): ChartActionResult;
+    /**
+     * Replaces the flows (and, when given, the node order). An empty list goes back to the
+     * table, keeping how much passed through each node as values. One undo step, all-or-nothing.
+     */
+    setLinks(links: unknown, options?: ChartEditOptions & {
+        nodes?: readonly string[];
+    }): ChartActionResult;
+    /** Replaces the data with flows from a table of source, target and value columns. */
+    importLinksTable(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: {
+        header?: boolean | 'auto';
+    }): ChartActionResult;
+    private badLink;
+    /** Adds a flow and returns its index. */
+    addLink(link: ChartLink): {
+        ok: true;
+        index: number;
+    } | {
+        ok: false;
+        message: string;
+        issues?: ChartIssue[];
+    };
+    /** Changes a flow's source, target, value or colour (`color: null` goes back to the default). */
+    updateLink(index: number, patch: {
+        source?: string;
+        target?: string;
+        value?: number;
+        color?: string | null;
+    }): ChartActionResult;
+    removeLink(index: number): ChartActionResult;
     /** Sets the note written under the chart ("" removes it). */
     setNote(note: string): ChartActionResult;
     /**