@pixerate/editor-svelte 0.120.0 → 0.122.0

package/dist/canvas/createCanvasExplosion.svelte.d.ts

@@ -17,8 +17,13 @@ export interface CreateCanvasExplosionOptions<TNode extends CanvasNode = CanvasN
     onSave?: () => void;
 }
 /**
- * Headless Svelte 5 rune managing canvas node explosion, spatial layout displacement,
- * coordinated multi-node animation paths, and reversible collapsing.
+ * Imperative explosion coordinator for a mutable graph (whiteboards, diagrams): adds child
+ * nodes and edges, animates them out along a trajectory while surrounding nodes slide aside,
+ * and collapses back exactly. The layout math is `computeCanvasExplosionLayout` from
+ * `@pixerate/editor/canvas`; several nodes can be exploded at once. For a canvas derived from
+ * state (`$derived`), use `createCanvasExplosionState` and the layout functions instead.
+ *
+ * `explodeNode` throws when a child id is already on the canvas or repeated.
  */
 export declare function createCanvasExplosion<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(graph: CanvasGraphTarget<TNode, TEdge>, options?: CreateCanvasExplosionOptions<TNode>): {
     readonly explodedNodeIds: string[];

package/dist/canvas/createCanvasExplosion.svelte.js

@@ -1,9 +1,14 @@
 import { cubicOut } from 'svelte/easing';
-import { calculateDirectionalDisplacement, calculateReflowDisplacement } from './createCanvasDisplacement.js';
+import { computeCanvasExplosionLayout } from '@pixerate/editor/canvas';
 import { createFanOutTrajectory, linearPositionTrajectory, runMultiNodeTransition } from './createCanvasTrajectory.js';
 /**
- * Headless Svelte 5 rune managing canvas node explosion, spatial layout displacement,
- * coordinated multi-node animation paths, and reversible collapsing.
+ * Imperative explosion coordinator for a mutable graph (whiteboards, diagrams): adds child
+ * nodes and edges, animates them out along a trajectory while surrounding nodes slide aside,
+ * and collapses back exactly. The layout math is `computeCanvasExplosionLayout` from
+ * `@pixerate/editor/canvas`; several nodes can be exploded at once. For a canvas derived from
+ * state (`$derived`), use `createCanvasExplosionState` and the layout functions instead.
+ *
+ * `explodeNode` throws when a child id is already on the canvas or repeated.
  */
 export function createCanvasExplosion(graph, options = {}) {
     let explodedNodeIds = $state([]);
@@ -36,98 +41,50 @@ export function createCanvasExplosion(graph, options = {}) {
         return explodedNodeIds.includes(nodeId);
     }
     function explodeNode(parentId, explodeOptions) {
-        if (isExploded(parentId)) {
+        // Already exploded, or its explosion is still animating
+        if (isExploded(parentId) || snapshots.has(parentId)) {
             return false;
         }
         const parentNode = graph.nodes.find((n) => n.id === parentId);
         if (!parentNode) {
             return false;
         }
-        const { childNodes, childEdges = [], connectParentToChildren = 'all', displacementStrategy = 'directional', directionalOptions = {}, reflowOptions = {}, trajectory, duration = 500, staggerDelay = 20, easing = cubicOut, onComplete } = explodeOptions;
-        if (childNodes.length === 0) {
+        const { childNodes: requestedChildren, childEdges = [], connectParentToChildren = 'all', displacementStrategy = 'directional', directionalOptions = {}, reflowOptions = {}, trajectory, duration = 500, staggerDelay = 20, easing = cubicOut, onComplete } = explodeOptions;
+        if (requestedChildren.length === 0) {
             return false;
         }
-        // 1. Calculate displacement for existing nodes
-        let displacementMap;
-        if (displacementStrategy === 'dagre') {
-            displacementMap = calculateReflowDisplacement({
-                existingNodes: graph.nodes,
-                existingEdges: graph.edges,
-                originNode: parentNode,
-                childNodes,
-                childEdges,
-                getNodesBounds: options.getNodesBounds,
-                options: {
-                    ...reflowOptions,
-                    direction: reflowOptions.direction ?? 'LR'
-                }
-            });
-        }
-        else if (displacementStrategy === 'none') {
-            displacementMap = new Map();
-        }
-        else {
-            displacementMap = calculateDirectionalDisplacement({
-                existingNodes: graph.nodes,
-                originNode: parentNode,
-                childNodes,
-                getNodesBounds: options.getNodesBounds,
-                options: directionalOptions
-            });
-        }
-        // 2. Build snapshot of displaced nodes before mutating positions
-        const displacedNodesSnapshot = Array.from(displacementMap.entries()).map(([id]) => {
-            const node = graph.nodes.find((n) => n.id === id);
-            return {
-                id,
-                originalPosition: { ...(node?.position ?? { x: 0, y: 0 }) }
-            };
+        // 1-3. Pure layout: displacement of existing nodes, child copies and the edges to add
+        // Loose type parameter: SvelteFlow `class` is ClassValue, core `CanvasNode.class` is a string (see GOTCHAS).
+        const layout = computeCanvasExplosionLayout({
+            existingNodes: graph.nodes,
+            existingEdges: graph.edges,
+            originNode: parentNode,
+            childNodes: requestedChildren,
+            childEdges,
+            strategy: displacementStrategy,
+            options: directionalOptions,
+            reflowOptions,
+            connectParentToChildren,
+            createEdge: graph.createEdge ? (source, target) => graph.createEdge(source, target) : undefined,
+            getNodesBounds: options.getNodesBounds
         });
-        // 3. Prepare child edges & parent connection edges
-        const edgesToAdd = [...childEdges];
-        const defaultCreateEdge = (sourceId, targetId) => {
-            if (graph.createEdge) {
-                return graph.createEdge(sourceId, targetId);
-            }
-            return {
-                id: crypto.randomUUID(),
-                type: 'default',
-                source: sourceId,
-                target: targetId
-            };
-        };
-        if (connectParentToChildren === 'all' || connectParentToChildren === true) {
-            childNodes.forEach((child) => {
-                const exists = edgesToAdd.some((e) => e.source === parentId && e.target === child.id);
-                if (!exists) {
-                    edgesToAdd.push(defaultCreateEdge(parentId, child.id));
-                }
-            });
-        }
-        else if (connectParentToChildren === 'first' && childNodes.length > 0) {
-            const firstChild = childNodes[0];
-            const exists = edgesToAdd.some((e) => e.source === parentId && e.target === firstChild.id);
-            if (!exists) {
-                edgesToAdd.push(defaultCreateEdge(parentId, firstChild.id));
-            }
-        }
+        const displacementMap = layout.displacedPositions;
+        const childNodes = layout.childNodes;
+        const edgesToAdd = layout.childEdges.map((edge) => ({ ...edge }));
         const snapshot = {
             parentId,
             childNodeIds: childNodes.map((n) => n.id),
             childEdgeIds: edgesToAdd.map((e) => e.id),
-            displacedNodes: displacedNodesSnapshot,
+            displacedNodes: [...layout.originalPositions].map(([id, originalPosition]) => ({ id, originalPosition })),
             timestamp: Date.now()
         };
         snapshots.set(parentId, snapshot);
-        // 4. Position child nodes initially at origin node coordinate
+        // 4. Position child nodes (copies, so the caller's objects stay untouched) at the origin
         const originPos = { ...parentNode.position };
         const targetPositions = childNodes.map((child) => ({ ...child.position }));
         childNodes.forEach((child) => {
             child.position = { ...originPos };
-            if (!child.data)
-                child.data = {};
-            child.data.scale = 0;
-            child.data.opacity = 0;
+            child.data = { ...(child.data ?? {}), scale: 0, opacity: 0 };
             const currentStyle = (child.style || '').replace(/opacity:\s*[^;]+;?/g, '').trim();
             child.style = `${currentStyle ? currentStyle + '; ' : ''}opacity: 0;`;
         });
@@ -330,7 +287,7 @@ export function createCanvasExplosion(graph, options = {}) {
         return true;
     }
     function toggleExplode(parentId, explodeOptions, collapseOptions) {
-        if (isExploded(parentId)) {
+        if (snapshots.has(parentId)) {
             return collapseNode(parentId, collapseOptions);
         }
         return explodeNode(parentId, explodeOptions);

package/dist/canvas/createCanvasExplosionState.svelte.d.ts

@@ -0,0 +1,17 @@
+import { type CanvasExplosionState, type CanvasExplosionStateController, type CanvasExplosionStateOptions } from '@pixerate/editor/canvas';
+export type { CanvasExplosionState, CanvasExplosionStateOptions };
+export interface CanvasExplosionStateRune extends CanvasExplosionState {
+    /** The framework-free controller underneath (for `canvasExplosionToolTarget` and agent tools). */
+    readonly controller: CanvasExplosionStateController;
+}
+/**
+ * Headless, declarative explosion state as a Svelte 5 rune: which node is exploded
+ * (`activeId`), which is still collapsing (`collapsingId`, so its children can play a collapse
+ * animation before unmounting), and the collapse timer. It never touches a graph: derive the
+ * canvas from it with `$derived` and `computeCanvasExplosionLayout` /
+ * `calculateDirectionalDisplacement`.
+ *
+ * Created during component initialisation it cleans up its timer when the component unmounts;
+ * created elsewhere, call `destroy()` yourself.
+ */
+export declare function createCanvasExplosionState(options?: CanvasExplosionStateOptions): CanvasExplosionStateRune;

package/dist/canvas/createCanvasExplosionState.svelte.js

@@ -0,0 +1,44 @@
+import { createCanvasExplosionStateController } from '@pixerate/editor/canvas';
+/**
+ * Headless, declarative explosion state as a Svelte 5 rune: which node is exploded
+ * (`activeId`), which is still collapsing (`collapsingId`, so its children can play a collapse
+ * animation before unmounting), and the collapse timer. It never touches a graph: derive the
+ * canvas from it with `$derived` and `computeCanvasExplosionLayout` /
+ * `calculateDirectionalDisplacement`.
+ *
+ * Created during component initialisation it cleans up its timer when the component unmounts;
+ * created elsewhere, call `destroy()` yourself.
+ */
+export function createCanvasExplosionState(options = {}) {
+    const controller = createCanvasExplosionStateController(options);
+    let snapshot = $state(controller.getSnapshot());
+    controller.subscribe(() => {
+        snapshot = controller.getSnapshot();
+    });
+    try {
+        $effect(() => () => controller.destroy());
+    }
+    catch {
+        // Not inside a component or effect: the caller owns destroy().
+    }
+    return {
+        controller,
+        get activeId() {
+            return snapshot.activeId;
+        },
+        get collapsingId() {
+            return snapshot.collapsingId;
+        },
+        get isExplodingOrCollapsing() {
+            return snapshot.activeId !== null || snapshot.collapsingId !== null;
+        },
+        isExploded: (nodeId) => snapshot.activeId === nodeId,
+        isCollapsing: (nodeId) => snapshot.collapsingId === nodeId,
+        shouldRenderChildren: (nodeId) => snapshot.activeId === nodeId || snapshot.collapsingId === nodeId,
+        explode: (nodeId) => controller.explode(nodeId),
+        collapse: (nodeId) => controller.collapse(nodeId),
+        toggle: (nodeId) => controller.toggle(nodeId),
+        finishCollapse: () => controller.finishCollapse(),
+        destroy: () => controller.destroy()
+    };
+}

package/dist/canvas/index.d.ts

@@ -6,7 +6,8 @@ export { createCanvasDocking, type CreateCanvasDockingOptions, type DockStrategy
 export { createCanvasShortcuts } from './createCanvasShortcuts.js';
 export { createCanvasInteractions, defaultSvelteFlowPreset, miroCompatiblePreset, restorePanelPointerEvents, isolateCanvasGestures, type CreateCanvasInteractionsOptions } from './createCanvasInteractions.svelte.js';
 export { linearTrajectory, linearPositionTrajectory, createFanOutTrajectory, createBezierTrajectory, runMultiNodeTransition } from './createCanvasTrajectory.js';
-export { computeNodesBoundingBox, calculateDirectionalDisplacement, calculateReflowDisplacement } from './createCanvasDisplacement.js';
+export { computeNodesBoundingBox, nodeSizeOf, calculateDirectionalDisplacement, calculateReflowDisplacement, calculateDagreReflowDisplacement, computeCanvasExplosionLayout, explosionEdgeId, createCanvasExplosionStateController, createCanvasExplosionToolProvider, canvasExplosionToolTarget, type ComputeCanvasExplosionLayoutParams, type CanvasExplosionLayoutResult, type CanvasExplosionStateController, type CanvasExplosionStateSnapshot, type CanvasExplosionToolTarget, type CanvasExplosionToolProviderOptions } from '@pixerate/editor/canvas';
+export { createCanvasExplosionState, type CanvasExplosionState, type CanvasExplosionStateOptions, type CanvasExplosionStateRune } from './createCanvasExplosionState.svelte.js';
 export { createCanvasExplosion, type CanvasGraphTarget, type CreateCanvasExplosionOptions } from './createCanvasExplosion.svelte.js';
 export { createCanvasNodeSync, preserveNodeMeasurements, normalizeNodeHandles, snapshotCanvasGraph, type HandleConfig, type NodeMeasurement, type CreateCanvasNodeSyncOptions, type CanvasGraphSnapshotInput } from './createCanvasNodeSync.svelte.js';
 export { createCanvasMultiDrag, type MultiDragState, type MultiDragFollowerOffset, type CreateCanvasMultiDragOptions, type FollowerTransform } from './createCanvasMultiDrag.svelte.js';

package/dist/canvas/index.js

@@ -14,9 +14,11 @@ export { createCanvasShortcuts } from './createCanvasShortcuts.js';
 export { createCanvasInteractions, defaultSvelteFlowPreset, miroCompatiblePreset, restorePanelPointerEvents, isolateCanvasGestures } from './createCanvasInteractions.svelte.js';
 // Trajectory calculation & multi-node transitions
 export { linearTrajectory, linearPositionTrajectory, createFanOutTrajectory, createBezierTrajectory, runMultiNodeTransition } from './createCanvasTrajectory.js';
-// Spatial layout displacement
-export { computeNodesBoundingBox, calculateDirectionalDisplacement, calculateReflowDisplacement } from './createCanvasDisplacement.js';
-// Node explosion & collapse rune
+// Spatial layout displacement & pure explosion layout (core)
+export { computeNodesBoundingBox, nodeSizeOf, calculateDirectionalDisplacement, calculateReflowDisplacement, calculateDagreReflowDisplacement, computeCanvasExplosionLayout, explosionEdgeId, createCanvasExplosionStateController, createCanvasExplosionToolProvider, canvasExplosionToolTarget } from '@pixerate/editor/canvas';
+// Declarative explosion state rune
+export { createCanvasExplosionState } from './createCanvasExplosionState.svelte.js';
+// Imperative explosion coordinator rune
 export { createCanvasExplosion } from './createCanvasExplosion.svelte.js';
 // Node synchronization & handle normalization
 export { createCanvasNodeSync, preserveNodeMeasurements, normalizeNodeHandles, snapshotCanvasGraph } from './createCanvasNodeSync.svelte.js';

package/dist/canvas/types.d.ts

@@ -1,4 +1,5 @@
 import type { Node, Edge, XYPosition, ColorMode } from '@xyflow/svelte';
+import type { DirectionalDisplacementOptions, ExplosionDisplacementStrategy, ReflowDisplacementOptions } from '@pixerate/editor/canvas';
 /**
  * Generic node interface representing an element on the canvas.
  */
@@ -120,26 +121,7 @@ export interface NodeTransition<TNode extends CanvasNode = CanvasNode> {
     index?: number;
     total?: number;
 }
-/**
- * Displacement axis / direction.
- */
-export type DisplacementDirection = 'right' | 'left' | 'down' | 'up' | 'vertical';
-/**
- * Options for directional displacement calculation.
- */
-export interface DirectionalDisplacementOptions {
-    direction?: DisplacementDirection;
-    gap?: number;
-    spreadSiblingLanes?: boolean;
-    siblingTolerance?: number;
-    minY?: number;
-}
-/**
- * Options for Dagre reflow displacement calculation.
- */
-export interface ReflowDisplacementOptions extends CanvasLayoutOptions {
-    anchorNodeId: string;
-}
+export type { DisplacementDirection, DirectionalDisplacementOptions, ReflowDisplacementOptions, ExplosionDisplacementStrategy } from '@pixerate/editor/canvas';
 /**
  * Snapshot of canvas graph state prior to node explosion, enabling exact reversibility.
  */
@@ -160,8 +142,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/ChartDataGrid.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
   import { chartColorInputValue, chartSeriesColor, chartTreeFromSeries, formatChartNumber, type ChartController } from '@pixerate/editor/chart';
   import ChartCommitInput from './ChartCommitInput.svelte';
+  import ChartLinksGrid from './ChartLinksGrid.svelte';
   import ChartTreeGrid from './ChartTreeGrid.svelte';
   import { chartStateOf } from './createChartEditor.svelte.js';
   import { chartButtonClass, chartCellClass, chartIconButtonClass, chartInputClass } from './styles.js';
@@ -32,7 +33,9 @@
   };
 </script>
 
-{#if spec.tree.length}
+{#if spec.links.length || spec.type === 'sankey'}
+  <ChartLinksGrid {controller} {readOnly} class={className} />
+{:else if spec.tree.length}
   <ChartTreeGrid {controller} {readOnly} class={className} />
 {:else}
 <div class="overflow-auto rounded-md border border-border {className}" data-chart-grid="">

package/dist/chart/ChartInspector.svelte

@@ -12,6 +12,7 @@
     CHART_COLOR_SCHEMES,
     CHART_CURVES,
     CHART_RADAR_GRATICULES,
+    CHART_SANKEY_LINK_COLORS,
     CHART_ERROR_BAR_DIRECTIONS,
     CHART_ERROR_BAR_LABELS,
     CHART_ERROR_BAR_TYPES,
@@ -423,6 +424,16 @@
           </div>
         </div>
       {/if}
+      {#if spec.type === 'sankey'}
+        <div class="flex items-center gap-2">
+          <label for="{idPrefix}-sankey-color" class="{chartLabelClass} w-20 shrink-0">Flows</label>
+          <select id="{idPrefix}-sankey-color" class={chartInputClass} value={spec.sankeyLinkColor} data-option="sankeyLinkColor" onchange={(e) => controller.update({ sankeyLinkColor: e.currentTarget.value as (typeof CHART_SANKEY_LINK_COLORS)[number] })}>
+            {#each CHART_SANKEY_LINK_COLORS as c (c)}
+              <option value={c}>{c === 'source' ? 'Coloured by source' : c === 'target' ? 'Coloured by target' : 'Grey'}</option>
+            {/each}
+          </select>
+        </div>
+      {/if}
       {#if spec.type === 'sunburst'}
         <div class="flex items-center gap-2">
           <label for="{idPrefix}-sunburst-label" class="{chartLabelClass} w-20 shrink-0">Caption</label>

package/dist/chart/ChartLinksGrid.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+  import { addChartLink, setChartLinkField, type ChartController } from '@pixerate/editor/chart';
+  import ChartCommitInput from './ChartCommitInput.svelte';
+  import { chartStateOf } from './createChartEditor.svelte.js';
+  import { chartButtonClass, chartCellClass, chartIconButtonClass } from './styles.js';
+
+  interface Props {
+    controller: ChartController;
+    /** Hide the add / delete buttons. */
+    readOnly?: boolean;
+    class?: string;
+  }
+
+  let { controller, readOnly = false, class: className = '' }: Props = $props();
+
+  const view = chartStateOf(() => controller);
+  const links = $derived(view.current.spec.links);
+  const commit = (next: unknown) => controller.setLinks(next).ok;
+  const fields = ['source', 'target'] as const;
+</script>
+
+<!-- Flows as a table: source, target and value per row. Edits are checked as a whole (no loops, no repeated pairs). -->
+<div class="overflow-auto rounded-md border border-border {className}" data-chart-grid="" data-chart-links-grid="">
+  <table class="w-full border-collapse text-xs">
+    <thead class="bg-muted/50">
+      <tr>
+        <th class="border-b border-r border-border px-2 py-1 text-left font-medium text-muted-foreground">Source</th>
+        <th class="border-b border-r border-border px-2 py-1 text-left font-medium text-muted-foreground">Target</th>
+        <th class="border-b border-r border-border px-2 py-1 text-right font-medium text-muted-foreground">Value</th>
+        {#if !readOnly}<th class="w-8 border-b border-border"></th>{/if}
+      </tr>
+    </thead>
+    <tbody>
+      {#each links as link, i (i)}
+        <tr data-link-row={i}>
+          {#each fields as field (field)}
+            <td class="border-b border-r border-border p-0">
+              <ChartCommitInput value={link[field]} aria-label="{field === 'source' ? 'Source' : 'Target'} of flow {i + 1}" data-link-cell="{i}:{field}" readonly={readOnly} oncommit={(text) => commit(setChartLinkField(links, i, field, text))} class="{chartCellClass} text-left" />
+            </td>
+          {/each}
+          <td class="border-b border-r border-border p-0">
+            <ChartCommitInput value={String(link.value)} inputmode="decimal" aria-label="Value of {link.source} → {link.target}" data-link-cell="{i}:value" readonly={readOnly} oncommit={(text) => commit(setChartLinkField(links, i, 'value', text))} class={chartCellClass} />
+          </td>
+          {#if !readOnly}
+            <td class="border-b border-border px-1">
+              <button type="button" class={chartIconButtonClass} title="Delete flow" aria-label="Delete {link.source} → {link.target}" data-action="link-remove" onclick={() => controller.removeLink(i)}>×</button>
+            </td>
+          {/if}
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+  {#if !readOnly}
+    <div class="flex flex-wrap gap-1 p-1">
+      <button type="button" class="{chartButtonClass} h-6 border-dashed" data-action="link-add" onclick={() => commit(addChartLink(links))}>+ Add flow</button>
+      <span class="flex-1"></span>
+      {#if links.length}
+        <button type="button" class="{chartButtonClass} h-6" data-action="links-clear" title="Keep how much passes through each node as plain data" onclick={() => controller.setLinks([])}>Remove flows</button>
+      {/if}
+    </div>
+  {/if}
+</div>

package/dist/chart/ChartLinksGrid.svelte.d.ts

@@ -0,0 +1,10 @@
+import { type ChartController } from '@pixerate/editor/chart';
+interface Props {
+    controller: ChartController;
+    /** Hide the add / delete buttons. */
+    readOnly?: boolean;
+    class?: string;
+}
+declare const ChartLinksGrid: import("svelte").Component<Props, {}, "">;
+type ChartLinksGrid = ReturnType<typeof ChartLinksGrid>;
+export default ChartLinksGrid;

package/dist/chart/index.d.ts

@@ -9,6 +9,7 @@ export { default as ChartEditor } from "./ChartEditor.svelte";
 export { default as ChartCanvas } from "./ChartCanvas.svelte";
 export { default as ChartDataGrid } from "./ChartDataGrid.svelte";
 export { default as ChartTreeGrid } from "./ChartTreeGrid.svelte";
+export { default as ChartLinksGrid } from "./ChartLinksGrid.svelte";
 export { default as ChartInspector } from "./ChartInspector.svelte";
 export { default as ChartCommitInput } from "./ChartCommitInput.svelte";
 export { default as ChartMarks } from "./ChartMarks.svelte";

package/dist/chart/index.js

@@ -2,6 +2,7 @@ export { default as ChartEditor } from "./ChartEditor.svelte";
 export { default as ChartCanvas } from "./ChartCanvas.svelte";
 export { default as ChartDataGrid } from "./ChartDataGrid.svelte";
 export { default as ChartTreeGrid } from "./ChartTreeGrid.svelte";
+export { default as ChartLinksGrid } from "./ChartLinksGrid.svelte";
 export { default as ChartInspector } from "./ChartInspector.svelte";
 export { default as ChartCommitInput } from "./ChartCommitInput.svelte";
 export { default as ChartMarks } from "./ChartMarks.svelte";

package/dist/index.d.ts

@@ -49,3 +49,4 @@ export * from "./generation/index.js";
 export * from "./find-replace/index.js";
 export * from "./tables/index.js";
 export * from "./chart-node/index.js";
+export * from "./style/index.js";

package/dist/index.js

@@ -29,3 +29,4 @@ export * from "./generation/index.js";
 export * from "./find-replace/index.js";
 export * from "./tables/index.js";
 export * from "./chart-node/index.js";
+export * from "./style/index.js";

package/dist/persistence/editorAutosave.svelte.d.ts

@@ -1,8 +1,14 @@
-import { type EditorDocument, type EditorDocumentFile, type LoadReport } from "@pixerate/editor/persistence";
+import { type EditorAssetGarbageOptions, type EditorDocument, type EditorDocumentFile, type LoadReport } from "@pixerate/editor/persistence";
 import { type CreateAutosaveOptions, type SvelteAutosave } from "./autosave.svelte.js";
 export interface CreateEditorAutosaveOptions extends Omit<CreateAutosaveOptions<EditorDocumentFile>, "key" | "getSnapshot" | "serialize" | "deserialize" | "history"> {
     /** Snapshot key (default the document's `kind`). */
     key?: string;
+    /**
+     * For documents with `assets`: after `markClean` or `discard` retire a snapshot, delete the
+     * stored assets nothing refers to any more (`collectEditorAssetGarbage`, best effort, keeping
+     * the assets the document uses now; default `true`). Needs `storage.keys`; `false` turns it off.
+     */
+    collectAssetGarbage?: boolean | Omit<EditorAssetGarbageOptions, "dryRun" | "only">;
 }
 export interface SvelteEditorAutosave extends Omit<SvelteAutosave<EditorDocumentFile>, "restore"> {
     /** Loads the recovered snapshot into the document and starts autosaving. */
@@ -14,4 +20,4 @@ export interface SvelteEditorAutosave extends Omit<SvelteAutosave<EditorDocument
  * `EditorDocumentFile` after each change, and `restore` loads a recovered
  * snapshot straight into the editor. Status and recovery stay reactive.
  */
-export declare function createEditorAutosave(doc: EditorDocument, options: CreateEditorAutosaveOptions): SvelteEditorAutosave;
+export declare function createEditorAutosave(doc: EditorDocument, { collectAssetGarbage, ...options }: CreateEditorAutosaveOptions): SvelteEditorAutosave;

package/dist/persistence/editorAutosave.svelte.js

@@ -1,4 +1,4 @@
-import { parseEditorDocument, toEditorDocumentFile, withEditorAssets, } from "@pixerate/editor/persistence";
+import { collectRetiredEditorAssets, parseEditorDocument, toEditorDocumentFile, withEditorAssets, } from "@pixerate/editor/persistence";
 import { createAutosave } from "./autosave.svelte.js";
 /**
  * `createAutosave` for any editor's `EditorDocument` (e.g.
@@ -6,7 +6,9 @@ import { createAutosave } from "./autosave.svelte.js";
  * `EditorDocumentFile` after each change, and `restore` loads a recovered
  * snapshot straight into the editor. Status and recovery stay reactive.
  */
-export function createEditorAutosave(doc, options) {
+export function createEditorAutosave(doc, { collectAssetGarbage, ...options }) {
+    // Retiring a snapshot can leave assets nothing refers to any more.
+    const collect = () => collectRetiredEditorAssets(options.storage, doc, collectAssetGarbage);
     const autosave = createAutosave({
         ...options,
         // Image and paint documents hold asset references: their bytes are saved and read with them.
@@ -30,10 +32,16 @@ export function createEditorAutosave(doc, options) {
             const snapshot = autosave.restore();
             return snapshot ? doc.loadDocument(snapshot, { history: "reset" }) : undefined;
         },
-        discard: () => autosave.discard(),
+        async discard() {
+            await autosave.discard();
+            await collect();
+        },
         ready: () => autosave.ready(),
         flushNow: () => autosave.flushNow(),
-        markClean: () => autosave.markClean(),
+        async markClean() {
+            await autosave.markClean();
+            await collect();
+        },
         notifyChange: () => autosave.notifyChange(),
         checked: autosave.checked,
         controller: autosave.controller,

package/dist/style/StyleFindings.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+  import type { StyleCheckReport, StyleFinding } from "@pixerate/editor/tools";
+
+  interface Props {
+    /** A check report (`useStyleFindings(...).report`, or a `check_*_style` tool result). Renders nothing while `null`. */
+    report: StyleCheckReport | null | undefined;
+    /** Called when a finding with a `target` is clicked, e.g. to select that series in the chart. */
+    onSelect?: (finding: StyleFinding) => void;
+    /** Heading (default "House style"). */
+    title?: string;
+    class?: string;
+  }
+
+  let { report, onSelect, title = "House style", class: className = "" }: Props = $props();
+
+  const SEVERITY_CLASS: Record<StyleFinding["severity"], string> = {
+    error: "text-destructive",
+    warning: "text-amber-600",
+    info: "text-muted-foreground",
+  };
+</script>
+
+{#snippet body(finding: StyleFinding)}
+  <span data-style-severity={finding.severity} class="shrink-0 font-semibold uppercase text-[10px] {SEVERITY_CLASS[finding.severity]}">
+    {finding.severity}
+  </span>
+  <span class="flex min-w-0 flex-col">
+    <span data-style-message="">{finding.message}</span>
+    <span class="text-[10px] text-muted-foreground"><code>{finding.check}</code>{#if finding.layer} · {finding.layer}{/if}</span>
+  </span>
+{/snippet}
+
+{#if report}
+  <section data-style-findings="" aria-label={title} class="flex flex-col gap-1.5 text-xs text-foreground {className}">
+    <h3 class="text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">{title}</h3>
+    {#if report.findings.length > 0}
+      <ul class="flex flex-col gap-1">
+        {#each report.findings as finding, i (`${finding.check}-${i}`)}
+          <li data-style-finding={finding.check}>
+            {#if finding.target !== undefined && onSelect}
+              <button
+                type="button"
+                class="flex w-full items-start gap-2 rounded border border-border px-2 py-1 text-left hover:bg-muted"
+                onclick={() => onSelect?.(finding)}
+              >
+                {@render body(finding)}
+              </button>
+            {:else}
+              <div class="flex items-start gap-2 rounded border border-border px-2 py-1">{@render body(finding)}</div>
+            {/if}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+    {#if report.findings.length === 0 && report.ran.length > 0}
+      <p data-style-clear="" class="text-emerald-600">
+        All clear: {report.ran.length} {report.ran.length === 1 ? "check" : "checks"} passed.
+      </p>
+    {/if}
+    {#if report.findings.length === 0 && report.ran.length === 0 && report.skipped.length === 0}
+      <p class="text-muted-foreground">No house-style checks apply.</p>
+    {/if}
+    {#if report.skipped.length > 0}
+      <ul data-style-skipped="" aria-label="Skipped checks" class="flex flex-col gap-0.5 text-muted-foreground">
+        {#each report.skipped as s (s.check)}
+          <li data-style-skipped-check={s.check}>Skipped <code>{s.check}</code>: {s.reason}</li>
+        {/each}
+      </ul>
+    {/if}
+  </section>
+{/if}

package/dist/style/StyleFindings.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { StyleCheckReport, StyleFinding } from "@pixerate/editor/tools";
+interface Props {
+    /** A check report (`useStyleFindings(...).report`, or a `check_*_style` tool result). Renders nothing while `null`. */
+    report: StyleCheckReport | null | undefined;
+    /** Called when a finding with a `target` is clicked, e.g. to select that series in the chart. */
+    onSelect?: (finding: StyleFinding) => void;
+    /** Heading (default "House style"). */
+    title?: string;
+    class?: string;
+}
+declare const StyleFindings: import("svelte").Component<Props, {}, "">;
+type StyleFindings = ReturnType<typeof StyleFindings>;
+export default StyleFindings;

package/dist/style/index.d.ts

@@ -0,0 +1,5 @@
+import type { ComponentProps } from "svelte";
+import type StyleFindingsComponent from "./StyleFindings.svelte";
+export { default as StyleFindings } from "./StyleFindings.svelte";
+export * from "./style.svelte.js";
+export type StyleFindingsProps = ComponentProps<typeof StyleFindingsComponent>;

package/dist/style/index.js

@@ -0,0 +1,2 @@
+export { default as StyleFindings } from "./StyleFindings.svelte";
+export * from "./style.svelte.js";

package/dist/style/style.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { ResolvedStyle, StyleCheckReport, StyleResolver } from "@pixerate/editor/tools";
+type MaybeGetter<T> = T | (() => T);
+export interface SvelteStyle {
+    /** The resolved house style for the domain, or `null` before the first resolve (or without a resolver) (reactive). */
+    readonly style: ResolvedStyle | null;
+    /** Why the last resolve failed (e.g. an unknown domain), or `null` (reactive). */
+    readonly error: string | null;
+}
+export interface SvelteStyleFindings extends SvelteStyle {
+    /** The last check report for `state`, or `null` before the first check (or without a resolver) (reactive). */
+    readonly report: StyleCheckReport | null;
+}
+/**
+ * Svelte 5 rune: the house style for one domain (`chart`, `tokens`, ...), merged across the
+ * resolver's layers; re-resolves when a style store or the token source changes. Call it during
+ * component initialisation; pass getters to react to changes. Parity with React's `useStyle`.
+ */
+export declare function useStyle(styles: MaybeGetter<StyleResolver | null | undefined>, domain: MaybeGetter<string>): SvelteStyle;
+/**
+ * Svelte 5 rune: runs the domain's house-style checks against `subject`, the domain's state (e.g. a chart spec),
+ * whenever the value a getter returns changes by reference, the domain or resolver changes, or
+ * the resolver notifies. Results of older runs that settle late are ignored. Feed `report` to
+ * `<StyleFindings>`. Call it during component initialisation. Parity with React's `useStyleFindings`.
+ */
+export declare function useStyleFindings(styles: MaybeGetter<StyleResolver | null | undefined>, domain: MaybeGetter<string>, subject: MaybeGetter<unknown>): SvelteStyleFindings;
+export {};

package/dist/style/style.svelte.js

@@ -0,0 +1,89 @@
+const read = (value) => (typeof value === "function" ? value() : value);
+const message = (error) => (error instanceof Error ? error.message : String(error));
+/**
+ * Runs `run` in an effect (re-run when anything `inputs` reads changes) and whenever the
+ * resolver notifies, delivering only the newest result.
+ */
+function resolverTask(inputs, run, deliver) {
+    $effect(() => {
+        const { styles, input } = inputs();
+        if (!styles) {
+            deliver({ value: null, error: null });
+            return;
+        }
+        let latest = 0;
+        let active = true;
+        const go = () => {
+            const call = ++latest;
+            run(styles, input).then((value) => {
+                if (active && call === latest)
+                    deliver({ value, error: null });
+            }, (error) => {
+                if (active && call === latest)
+                    deliver({ value: null, error: message(error) });
+            });
+        };
+        go();
+        const unsubscribe = styles.subscribe(go);
+        return () => {
+            active = false;
+            unsubscribe();
+        };
+    });
+}
+/**
+ * Svelte 5 rune: the house style for one domain (`chart`, `tokens`, ...), merged across the
+ * resolver's layers; re-resolves when a style store or the token source changes. Call it during
+ * component initialisation; pass getters to react to changes. Parity with React's `useStyle`.
+ */
+export function useStyle(styles, domain) {
+    let style = $state.raw(null);
+    let error = $state.raw(null);
+    resolverTask(() => ({ styles: read(styles), input: read(domain) }), (s, d) => s.resolve(d), (result) => {
+        style = result.value;
+        error = result.error;
+    });
+    return {
+        get style() {
+            return style;
+        },
+        get error() {
+            return error;
+        },
+    };
+}
+/**
+ * Svelte 5 rune: runs the domain's house-style checks against `subject`, the domain's state (e.g. a chart spec),
+ * whenever the value a getter returns changes by reference, the domain or resolver changes, or
+ * the resolver notifies. Results of older runs that settle late are ignored. Feed `report` to
+ * `<StyleFindings>`. Call it during component initialisation. Parity with React's `useStyleFindings`.
+ */
+export function useStyleFindings(styles, domain, subject) {
+    let report = $state.raw(null);
+    let style = $state.raw(null);
+    let error = $state.raw(null);
+    resolverTask(() => ({ styles: read(styles), input: { domain: read(domain), value: read(subject) } }), (s, { domain: d, value }) => s.check(d, value), (result) => {
+        if (!result.value) {
+            report = null;
+            style = null;
+            error = result.error;
+        }
+        else {
+            const { style: resolved, ...rest } = result.value;
+            report = rest;
+            style = resolved;
+            error = null;
+        }
+    });
+    return {
+        get report() {
+            return report;
+        },
+        get style() {
+            return style;
+        },
+        get error() {
+            return error;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor-svelte",
-  "version": "0.120.0",
+  "version": "0.122.0",
   "description": "Svelte bindings and prompt/rich-text components for @pixerate/editor",
   "author": "Pixerate",
   "license": "MIT",
@@ -168,7 +168,7 @@
     "@tiptap/extension-bubble-menu": "^2.27.3",
     "@tiptap/extension-placeholder": "^2.27.3",
     "@tiptap/starter-kit": "^2.27.3",
-    "@pixerate/editor": "0.163.0"
+    "@pixerate/editor": "0.165.0"
   },
   "peerDependencies": {
     "@dagrejs/dagre": "^1.1.4",

package/dist/canvas/createCanvasDisplacement.d.ts

@@ -1,31 +0,0 @@
-import type { Rect, XYPosition } from '@xyflow/svelte';
-import type { CanvasEdge, CanvasLayoutOptions, CanvasNode, DirectionalDisplacementOptions } from './types.js';
-/**
- * Calculates a bounding rectangle for a set of nodes if not provided by getNodesBounds.
- */
-export declare function computeNodesBoundingBox<TNode extends CanvasNode = CanvasNode>(nodes: TNode[], defaultWidth?: number, defaultHeight?: number): Rect;
-/**
- * Pure directional displacement calculation.
- * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
- */
-export declare function calculateDirectionalDisplacement<TNode extends CanvasNode = CanvasNode>(params: {
-    existingNodes: TNode[];
-    originNode: TNode;
-    childNodes: TNode[];
-    getNodesBounds?: (nodes: TNode[]) => Rect;
-    options?: DirectionalDisplacementOptions;
-}): Map<string, XYPosition>;
-/**
- * Pure hierarchical Dagre reflow displacement calculation.
- * Calculates new coordinates for surrounding nodes using Dagre hierarchical layout,
- * anchoring the origin node at its current position to eliminate layout jumping.
- */
-export declare function calculateReflowDisplacement<TNode extends CanvasNode = CanvasNode, TEdge extends CanvasEdge = CanvasEdge>(params: {
-    existingNodes: TNode[];
-    existingEdges: TEdge[];
-    originNode: TNode;
-    childNodes: TNode[];
-    childEdges?: TEdge[];
-    getNodesBounds?: (nodes: TNode[]) => Rect;
-    options?: CanvasLayoutOptions;
-}): Map<string, XYPosition>;

package/dist/canvas/createCanvasDisplacement.js

@@ -1,170 +0,0 @@
-import dagre from '@dagrejs/dagre';
-/**
- * Calculates a bounding rectangle for a set of nodes if not provided by getNodesBounds.
- */
-export function computeNodesBoundingBox(nodes, defaultWidth = 200, defaultHeight = 60) {
-    if (nodes.length === 0) {
-        return { x: 0, y: 0, width: 0, height: 0 };
-    }
-    let minX = Infinity;
-    let minY = Infinity;
-    let maxX = -Infinity;
-    let maxY = -Infinity;
-    for (const node of nodes) {
-        const width = node.measured?.width ?? node.width ?? defaultWidth;
-        const height = node.measured?.height ?? node.height ?? defaultHeight;
-        minX = Math.min(minX, node.position.x);
-        minY = Math.min(minY, node.position.y);
-        maxX = Math.max(maxX, node.position.x + width);
-        maxY = Math.max(maxY, node.position.y + height);
-    }
-    return {
-        x: minX,
-        y: minY,
-        width: maxX - minX,
-        height: maxY - minY
-    };
-}
-/**
- * Pure directional displacement calculation.
- * Shifts downstream or surrounding nodes along an axis to clear space for newly inserted child nodes.
- */
-export function calculateDirectionalDisplacement(params) {
-    const { existingNodes, originNode, childNodes, getNodesBounds, options = {} } = params;
-    const { direction = 'right', gap = 40, spreadSiblingLanes = false, siblingTolerance = 50, minY } = options;
-    const displacedMap = new Map();
-    if (childNodes.length === 0 || existingNodes.length === 0) {
-        return displacedMap;
-    }
-    const childBounds = getNodesBounds
-        ? getNodesBounds(childNodes)
-        : computeNodesBoundingBox(childNodes);
-    const originWidth = originNode.measured?.width ?? originNode.width ?? 200;
-    const originHeight = originNode.measured?.height ?? originNode.height ?? 60;
-    // The delta space required along primary axis
-    const deltaPrimary = (direction === 'right' || direction === 'left')
-        ? childBounds.width + gap
-        : childBounds.height + gap;
-    // Vertical displacement parameters: upward and downward row clearance
-    const deltaUp = Math.max(0, originNode.position.y - childBounds.y + gap);
-    const deltaDown = Math.max(0, childBounds.y + childBounds.height - (originNode.position.y + originHeight) + gap);
-    // Both above and below displace equally so the row expands symmetrically
-    const equalDelta = Math.max(deltaUp, deltaDown);
-    for (const node of existingNodes) {
-        if (node.id === originNode.id)
-            continue;
-        let newX = node.position.x;
-        let newY = node.position.y;
-        let moved = false;
-        if (direction === 'right') {
-            // Downstream nodes strictly to the right of the origin
-            if (node.position.x >= originNode.position.x + originWidth * 0.5) {
-                newX += deltaPrimary;
-                moved = true;
-            }
-            else if (spreadSiblingLanes) {
-                // Sibling nodes occupying the same vertical space as the exploded cluster
-                const isVerticallyOverlapping = node.position.y + (node.height ?? 60) >= childBounds.y - gap &&
-                    node.position.y <= childBounds.y + childBounds.height + gap;
-                if (isVerticallyOverlapping && Math.abs(node.position.x - originNode.position.x) <= siblingTolerance) {
-                    const pushDirection = node.position.y >= originNode.position.y ? 1 : -1;
-                    newY += pushDirection * (childBounds.height * 0.5 + gap);
-                    moved = true;
-                }
-            }
-        }
-        else if (direction === 'left') {
-            if (node.position.x <= originNode.position.x) {
-                newX -= deltaPrimary;
-                moved = true;
-            }
-        }
-        else if (direction === 'down') {
-            if (node.position.y >= originNode.position.y + originHeight * 0.5) {
-                newY += deltaPrimary;
-                moved = true;
-            }
-        }
-        else if (direction === 'up') {
-            if (node.position.y <= originNode.position.y) {
-                newY -= deltaPrimary;
-                moved = true;
-            }
-        }
-        else if (direction === 'vertical') {
-            // Row grows vertically:
-            // Nodes strictly above the origin node move up by equalDelta
-            // Nodes strictly below the origin node move down by equalDelta
-            // Both above and below displace equally; horizontal position (x) is strictly preserved
-            if (node.position.y < originNode.position.y) {
-                if (equalDelta > 0) {
-                    newY -= equalDelta;
-                    moved = true;
-                }
-            }
-            else if (node.position.y >= originNode.position.y + originHeight * 0.5) {
-                if (equalDelta > 0) {
-                    newY += equalDelta;
-                    moved = true;
-                }
-            }
-        }
-        if (moved) {
-            displacedMap.set(node.id, { x: newX, y: newY });
-        }
-    }
-    return displacedMap;
-}
-/**
- * Pure hierarchical Dagre reflow displacement calculation.
- * Calculates new coordinates for surrounding nodes using Dagre hierarchical layout,
- * anchoring the origin node at its current position to eliminate layout jumping.
- */
-export function calculateReflowDisplacement(params) {
-    const { existingNodes, existingEdges, originNode, childNodes, childEdges = [], options = {} } = params;
-    const { direction = 'LR', ranksep = 80, nodesep = 30, defaultNodeWidth = 200, defaultNodeHeight = 60 } = options;
-    const displacedMap = new Map();
-    if (existingNodes.length === 0)
-        return displacedMap;
-    const allNodes = [...existingNodes, ...childNodes];
-    const allEdges = [...existingEdges, ...childEdges];
-    const dagreGraph = new dagre.graphlib.Graph();
-    dagreGraph.setDefaultEdgeLabel(() => ({}));
-    dagreGraph.setGraph({ rankdir: direction, ranksep, nodesep });
-    const allNodeIds = new Set(allNodes.map((n) => n.id));
-    allNodes.forEach((node) => {
-        const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
-        const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
-        dagreGraph.setNode(node.id, { width: nodeWidth, height: nodeHeight });
-    });
-    allEdges.forEach((edge) => {
-        if (allNodeIds.has(edge.source) && allNodeIds.has(edge.target)) {
-            dagreGraph.setEdge(edge.source, edge.target);
-        }
-    });
-    dagre.layout(dagreGraph);
-    const dagreOrigin = dagreGraph.node(originNode.id);
-    if (!dagreOrigin)
-        return displacedMap;
-    const originWidth = originNode.measured?.width ?? originNode.width ?? defaultNodeWidth;
-    const originHeight = originNode.measured?.height ?? originNode.height ?? defaultNodeHeight;
-    // Calculate offset so origin node remains anchored at its exact initial coordinates
-    const anchorOffsetX = originNode.position.x - (dagreOrigin.x - originWidth / 2);
-    const anchorOffsetY = originNode.position.y - (dagreOrigin.y - originHeight / 2);
-    existingNodes.forEach((node) => {
-        if (node.id === originNode.id)
-            return;
-        const dagreNode = dagreGraph.node(node.id);
-        if (!dagreNode)
-            return;
-        const nodeWidth = node.measured?.width ?? node.width ?? defaultNodeWidth;
-        const nodeHeight = node.measured?.height ?? node.height ?? defaultNodeHeight;
-        const targetX = dagreNode.x - nodeWidth / 2 + anchorOffsetX;
-        const targetY = dagreNode.y - nodeHeight / 2 + anchorOffsetY;
-        // Only include if position actually shifted
-        if (Math.abs(targetX - node.position.x) > 0.5 || Math.abs(targetY - node.position.y) > 0.5) {
-            displacedMap.set(node.id, { x: targetX, y: targetY });
-        }
-    });
-    return displacedMap;
-}