@squeed/flow-sdk 0.1.14 → 0.1.16

package/dist/index.d.ts

@@ -1,8 +1,36 @@
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { MutableRefObject } from 'react';
 
+/** Add a child under `parentAddress`. Returns the new node's address. */
+export declare function addChild(json: SqueedJson, parentAddress: string, child: any, key?: string): {
+    json: SqueedJson;
+    address: string;
+};
+
+/** "root.a.b.#" → ["a", "b"] */
+export declare function addressToPath(address: string): string[];
+
+/** `$target` cross-link (the compiler supports one per node; an existing one is replaced) */
+export declare const addTargetEdge: (json: SqueedJson, sourceAddress: string, targetAddress: string, label?: string) => SqueedJson;
+
+/**
+ * For hand-built graphs (no Squeed JSON): hide everything downstream of a node whose
+ * `data.config.collapsed` is true, plus the edges touching hidden nodes.
+ */
+export declare function applyCollapsed(nodes: FlowDiagramNode[], edges: FlowDiagramEdge[]): {
+    nodes: FlowDiagramNode[];
+    edges: FlowDiagramEdge[];
+};
+
 export declare type BackgroundPattern = "dot" | "steel" | "grid" | "none";
 
+/**
+ * Wrap consumer callbacks so every toolbar/edit event is applied to `json`
+ * with Squeed `$` keys and delivered via `onJsonChange`. Granular callbacks
+ * still fire first (for logging/analytics) — consumers must not also mutate.
+ */
+export declare function bindSqueedCallbacks(json: SqueedJson, compiledEdges: FlowDiagramEdge[], callbacks: FlowDiagramCallbacks, onJsonChange?: (json: SqueedJson, change: SqueedChange) => void): FlowDiagramCallbacks;
+
 /** Props passed to custom bottom bar renderer */
 export declare interface BottomBarRenderProps {
     zoomIn: () => void;
@@ -28,6 +56,25 @@ export declare interface BottomBarRenderProps {
     callbacks: FlowDiagramCallbacks;
 }
 
+export declare interface CompileOptions {
+    title?: string;
+    /** Root in the middle, children fan out both ways (direction "C") */
+    isCenter?: boolean;
+    hideDefaultObject?: boolean;
+    separateObjectKeys?: boolean;
+}
+
+/**
+ * `createFlowDiagram` + post-pass:
+ * - deterministic edge ids (`source->target[#n]`) so selection survives regeneration
+ * - honors `$isEdgeDashed` / `$edgeColor`, which the compiler doesn't read
+ * - `$label` wins over the compiler's shared-config `headerTitle` (it leaks the previous node's title)
+ */
+export declare function compileSqueed(json: SqueedJson, opts?: CompileOptions): {
+    nodes: FlowDiagramNode[];
+    edges: FlowDiagramEdge[];
+};
+
 export declare const contentObjTheme: (color: any) => {
     background: any;
     highlight: string;
@@ -48,7 +95,7 @@ export declare const DynamicIcon: ({ name, ...props }: {
     name: any;
 }) => JSX_2.Element;
 
-export declare function FlowDiagram({ title, nodes, edges, config, callbacks, className, style, showBottomBar, }: FlowDiagramProps & {
+export declare function FlowDiagram({ title, json, nodes, edges, config, callbacks, className, style, showBottomBar, }: FlowDiagramProps & {
     showBottomBar?: boolean;
 }): JSX_2.Element;
 
@@ -87,6 +134,8 @@ export declare interface FlowDiagramCallbacks {
     onEdgeDeselect?: () => void;
     /** Fires when an edge is removed */
     onEdgeRemove?: (edgeId: string, edgeData: any) => void;
+    /** Fires when the user deletes an edge from the selection toolbar */
+    onEdgeDelete?: (edgeId: string, edgeData: any) => void;
     /** Fires when an edge's color is changed */
     onEdgeColorChange?: (edgeId: string, color: string) => void;
     /** Fires when an edge's label is changed */
@@ -107,6 +156,11 @@ export declare interface FlowDiagramCallbacks {
     onArrayModeChange?: (isArrayMode: boolean) => void;
     /** Fires when Cytoscape instance is initialized (for advanced use) */
     onCyInit?: (cy: any) => void;
+    /**
+     * Fires with the updated Squeed JSON after any toolbar/inline edit. The SDK applies the
+     * edit with `$` schema keys; store the result and pass it back as `json`.
+     */
+    onJsonChange?: (json: Record<string, any> | any[], change: SqueedChangeInfo) => void;
 }
 
 /** Configuration for the flow diagram appearance and behavior */
@@ -125,6 +179,8 @@ export declare interface FlowDiagramConfig {
     backgroundColor?: string;
     /** Edge/line color override */
     edgeColor?: string;
+    /** Default style for all compound/container nodes (per-node `viewProps` override it) */
+    parentNodeStyle?: ParentNodeStyle;
     /** Min zoom level (default: 0.01) */
     minZoom?: number;
     /** Max zoom level (default: 1.5) */
@@ -153,6 +209,8 @@ export declare interface FlowDiagramConfig {
     renderSelectedEdgeToolbar?: (props: SelectedEdgeToolbarProps) => React.ReactNode;
     /** Custom render function to replace the entire built-in bottom bar */
     renderBottomBar?: (props: BottomBarRenderProps) => React.ReactNode;
+    /** Built-in node/edge selection toolbars (bottom bar swaps to them on select). `false` disables. */
+    selectionToolbar?: SelectionToolbarConfig | false;
     /** Custom node view components to override SDK defaults. Keys: objectView, arrayView, text, parentContainer */
     customViews?: Record<string, React.ComponentType<any>>;
     /** Disable built-in keyboard shortcuts (Z/M/D) when the consumer handles its own */
@@ -173,6 +231,8 @@ export declare interface FlowDiagramEdge {
         source: string;
         target: string;
         label?: string;
+        /** Chakra token or hex; overrides the theme/edgeColor line color for this edge */
+        color?: string;
         isInverted?: boolean;
         isEdgeAnimated?: boolean;
         isEdgeDashed?: boolean;
@@ -198,6 +258,11 @@ export declare interface FlowDiagramNode {
 export declare interface FlowDiagramProps {
     /** Title shown on the root node */
     title?: string;
+    /**
+     * Squeed JSON document. When provided, nodes/edges are compiled from it and every
+     * edit is reported through `callbacks.onJsonChange`. Takes precedence over nodes/edges.
+     */
+    json?: Record<string, any> | any[];
     /** Pre-computed nodes */
     nodes?: FlowDiagramNode[];
     /** Pre-computed edges */
@@ -212,7 +277,8 @@ export declare interface FlowDiagramProps {
     style?: React.CSSProperties;
 }
 
-export declare type FlowDirection = "LR" | "RL" | "TB" | "BT";
+/** "C" = center: root in the middle, children fan out both ways (generate with `isCntr: true`); laid out as LR */
+export declare type FlowDirection = "LR" | "RL" | "TB" | "BT" | "C";
 
 export declare const getChakraColorHex: (color?: any, opacity?: any) => any;
 
@@ -228,6 +294,8 @@ export declare const getColorVariant: (color: string) => {
 
 export declare function getDarkerHexColor(hex: string, factor?: number): string;
 
+export declare function getNode(json: SqueedJson, address: string): any;
+
 export declare type LayoutAlgorithm = "dagre" | "elk" | "tidytree" | "concentric" | "cose";
 
 /** Actions shown in the hover overlay above nodes */
@@ -247,6 +315,56 @@ export declare interface NodeOverlayProps {
     setIsHovered: (v: boolean) => void;
 }
 
+/**
+ * Style for compound (container) nodes. Set per node via `data.viewProps`,
+ * or for all containers via `config.parentNodeStyle` (per-node wins).
+ * Colors accept Chakra tokens ("purple.500") or hex.
+ */
+export declare interface ParentNodeStyle {
+    /** Fill color; also the default border/label color (default: themeColor) */
+    bgColor?: string;
+    /** Fill opacity 0–1 (default 0.4) */
+    bgOpacity?: number;
+    borderColor?: string;
+    /** px (default 6) */
+    borderWidth?: number;
+    borderStyle?: "solid" | "dashed" | "dotted" | "double";
+    /** Corner radius px (default 50) */
+    borderRadius?: number;
+    /** Label color (default: bgColor) */
+    textColor?: string;
+    /** Label size px (default 70) */
+    fontSize?: number;
+    /** Inner padding px (default 120) */
+    padding?: number;
+    /** Label placement (default "top") */
+    labelPosition?: "top" | "center" | "bottom";
+}
+
+/** Removes a `$target` edge; hierarchy edges cannot be removed without removing the child (returns json unchanged). */
+export declare function removeEdge(json: SqueedJson, edge: RenderedEdgeRef): {
+    json: SqueedJson;
+    removed: boolean;
+};
+
+export declare function removeNode(json: SqueedJson, address: string): SqueedJson;
+
+export declare interface RenderedEdgeRef {
+    source: string;
+    target: string;
+    isInverted?: boolean | null;
+}
+
+/**
+ * Resolve which JSON node carries an edge's keys.
+ * parent→child edges (implicit hierarchy) are configured on the child;
+ * `$target` cross-links are configured on the source node.
+ */
+export declare function resolveEdgeOwner(edge: RenderedEdgeRef): {
+    address: string;
+    kind: "hierarchy" | "target";
+};
+
 /** Props passed to custom edge selection toolbar renderer */
 export declare interface SelectedEdgeToolbarProps {
     edgeId: string;
@@ -261,7 +379,64 @@ export declare interface SelectedNodeToolbarProps {
     onDeselect: () => void;
 }
 
+/** Built-in selection toolbars (shown in the bottom bar when a node/edge is selected) */
+export declare interface SelectionToolbarConfig {
+    /** Swatches offered for node/edge colors (Chakra tokens or hex). Default: 9 Chakra 500s */
+    palette?: string[];
+    /** Hide individual controls */
+    hide?: Array<"label" | "color" | "textColor" | "style" | "icon" | "collapse" | "delete">;
+}
+
+export declare const setCollapsed: (json: SqueedJson, address: string, collapsed: boolean) => SqueedJson;
+
+export declare function setEdgeProp(json: SqueedJson, edge: RenderedEdgeRef, key: SqueedEdgeKey, value: any): SqueedJson;
+
+export declare const setEdgeStyle: (json: SqueedJson, edge: RenderedEdgeRef, style: "solid" | "dashed" | "animated") => SqueedJson;
+
+export declare function setNodeProp(json: SqueedJson, address: string, key: SqueedNodeKey, value: any): SqueedJson;
+
+/** What changed in the Squeed document (delivered alongside the new JSON) */
+export declare interface SqueedChange {
+    type: "nodeLabel" | "nodeColor" | "nodeIcon" | "nodeCollapse" | "nodeCreate" | "nodeDelete" | "edgeLabel" | "edgeStyle" | "edgeColor" | "edgeCreate" | "edgeDelete";
+    /** Node address affected (new node's address for nodeCreate) */
+    address?: string;
+    edge?: RenderedEdgeRef;
+    /** `$` key written, when a single key changed */
+    key?: string;
+    value?: unknown;
+}
+
+/** Describes the edit behind an `onJsonChange` */
+export declare interface SqueedChangeInfo {
+    type: "nodeLabel" | "nodeColor" | "nodeIcon" | "nodeCollapse" | "nodeCreate" | "nodeDelete" | "edgeLabel" | "edgeStyle" | "edgeColor" | "edgeCreate" | "edgeDelete";
+    address?: string;
+    edge?: {
+        source: string;
+        target: string;
+        isInverted?: boolean | null;
+    };
+    key?: string;
+    value?: unknown;
+}
+
+/** Schema keys that describe the edge *into* a node (parent → child) */
+export declare type SqueedEdgeKey = "$sourceLabel" | "$isEdgeAnimated" | "$isEdgeDashed" | "$edgeColor";
+
+/**
+ * Squeed JSON = the source document `createFlowDiagram` compiles into nodes/edges.
+ * Node ids are JSON addresses ("root.a.b"); these helpers translate toolbar edits
+ * back into `$`-prefixed schema keys at that address. All functions are immutable.
+ */
+export declare type SqueedJson = Record<string, any> | any[];
+
+/** Schema keys that live on a node */
+export declare type SqueedNodeKey = "$label" | "$bgColor" | "$textColor" | "$borderColor" | "$borderRadius" | "$fontSize" | "$icon" | "$content" | "$media" | "$collapsed" | "$parent";
+
+/** Immutable update of the node at `address` (root address updates the document itself) */
+export declare function updateNode(json: SqueedJson, address: string, fn: (node: any) => any): SqueedJson;
+
 export declare function useCustomColors(theme?: any): {
+    canvas: string;
     background: string;
     backgroundSecondary: string;
     darkBackgroundSecondary: string;