@squeed/flow-sdk 0.1.16 → 2.0.1

package/dist/index.d.cts

@@ -0,0 +1,551 @@
+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;
+};
+
+export declare function addConnection(json: SqueedJson, sourceAddress: string, connection: SqueedConnection): SqueedJson;
+
+/** "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;
+    zoomOut: () => void;
+    resetZoom: () => void;
+    direction: FlowDirection;
+    isZoomMode: boolean;
+    setIsZoomMode: (v: boolean) => void;
+    isMultiSelectMode: boolean;
+    setIsMultiSelectMode: (v: boolean) => void;
+    isDragMode: boolean;
+    setIsDragMode: (v: boolean) => void;
+    isEdgeHandlesEnabled: boolean;
+    setIsEdgeHandlesEnabled: (v: boolean) => void;
+    isArrayNodeMode: boolean;
+    setIsArrayNodeMode: (v: boolean) => void;
+    selectedNodeIds: string[];
+    selectedNodeData: any[];
+    selectedEdgeId: string | null;
+    selectedEdgeData: any;
+    onNodeDeselect: () => void;
+    onEdgeDeselect: () => void;
+    callbacks: FlowDiagramCallbacks;
+}
+
+/** Centre + size, model units (matches cytoscape's node position/width/height) */
+declare interface Box {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+
+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;
+    border: string;
+    property: string;
+    boolean: string;
+    string: string;
+    number: string;
+};
+
+export declare function createFlowDiagram(jsnObjct: any, path?: string, nodes?: any[], edges?: any[], activeLabel?: string, flowConfig?: any, nodeConfig?: any): {
+    nodes: any[];
+    edges: any[];
+};
+
+export declare const DynamicIcon: ({ name, ...props }: {
+    [x: string]: any;
+    name: any;
+}) => JSX_2.Element;
+
+export declare type EdgeMode = "workflow" | "properties";
+
+export declare function FlowDiagram({ title, json, nodes, edges, config, callbacks, className, style, showBottomBar, }: FlowDiagramProps): JSX_2.Element;
+
+/** Event callbacks for the flow diagram */
+export declare interface FlowDiagramCallbacks {
+    /** Fires when a node is clicked/selected */
+    onNodeSelect?: (nodeId: string, nodeData: any) => void;
+    /** Fires when selection is cleared */
+    onNodeDeselect?: () => void;
+    /** Fires on double-click of a node */
+    onNodeDoubleClick?: (nodeId: string, nodeData: any) => void;
+    /** Fires when a node is created via edge drawing into empty space */
+    onNodeCreate?: (params: {
+        type: string;
+        position: any;
+        sourceNodeId?: string;
+        isArrayMode?: boolean;
+    }) => void;
+    /** Fires when a node is deleted */
+    onNodeDelete?: (nodeId: string, nodeData: any) => void;
+    /** Fires when a node label is edited inline */
+    onNodeLabelChange?: (nodeId: string, newLabel: string) => void;
+    /** Fires when a node's collapse toggle is clicked */
+    onNodeCollapse?: (nodeId: string, collapsed: boolean) => void;
+    /** Fires when a node's color is changed via the toolbar */
+    onNodeColorChange?: (nodeId: string, colorType: "text" | "bg", color: string) => void;
+    /** Fires when a node's icon is changed via the toolbar */
+    onNodeIconChange?: (nodeId: string, iconName: string) => void;
+    /** Fires when a hover overlay action is clicked */
+    onNodeHoverAction?: (actionId: string, nodeId: string, nodeData: any) => void;
+    /** Fires when a new edge is drawn between two nodes */
+    onEdgeCreate?: (sourceId: string, targetId: string, properties?: FlowEdgeProperties) => void;
+    /** Fires when an edge is clicked/selected */
+    onEdgeSelect?: (edgeId: string, edgeData: any) => void;
+    /** Fires when edge selection is cleared */
+    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 */
+    onEdgeLabelChange?: (edgeId: string, newLabel: string) => void;
+    /** Fires when an edge's style is changed (solid, dashed, animated) */
+    onEdgeStyleChange?: (edgeId: string, style: "solid" | "dashed" | "animated") => void;
+    /** Fires when the viewport (pan/zoom) changes */
+    onViewportChange?: (viewport: {
+        pan: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    }) => void;
+    /** Fires when the flow direction changes via bottom bar */
+    onDirectionChange?: (direction: FlowDirection) => void;
+    /** Fires when array/set mode toggles in bottom bar */
+    onArrayModeChange?: (isArrayMode: boolean) => void;
+    /** Fires once the renderer is ready with the engine handle (zoom/pan/fit/coordinate helpers) */
+    onInit?: (engine: FlowEngine) => 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 */
+export declare interface FlowDiagramConfig {
+    /** Layout direction: "LR", "RL", "TB", "BT" */
+    direction?: FlowDirection;
+    nodeAlignment?: NodeAlignment;
+    edgeMode?: EdgeMode;
+    /** Layout algorithm */
+    layout?: LayoutAlgorithm;
+    /** Theme accent color (Chakra token e.g. "blue.500") */
+    themeColor?: string;
+    /** Light or dark mode */
+    colorMode?: "light" | "dark";
+    /** Background pattern style */
+    backgroundPattern?: BackgroundPattern;
+    /** Background color override */
+    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) */
+    maxZoom?: number;
+    /** Initial viewport position and zoom */
+    initialViewport?: {
+        pan: {
+            x: number;
+            y: number;
+        };
+        zoom: number;
+    };
+    /** Enable edge drawing handles (default: true) */
+    edgeHandles?: boolean;
+    /** Disable all interactions */
+    readOnly?: boolean;
+    /** Enable inline node label editing */
+    editable?: boolean;
+    /** Actions rendered in the node hover overlay */
+    nodeOverlayActions?: NodeOverlayAction[];
+    /** Custom render function for node hover overlay */
+    renderNodeOverlay?: (props: NodeOverlayProps) => React.ReactNode;
+    /** Custom render function for multi-select toolbar */
+    renderSelectedNodeToolbar?: (props: SelectedNodeToolbarProps) => React.ReactNode;
+    /** Custom render function for edge selection toolbar */
+    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 */
+    disableKeyboardShortcuts?: boolean;
+    /** Externally controlled zoom mode (overrides internal state when provided) */
+    isZoomMode?: boolean;
+    /** Externally controlled multi-select mode (overrides internal state when provided) */
+    isMultiSelectMode?: boolean;
+    /** Externally controlled edge draw mode (overrides internal state when provided) */
+    isEdgeHandlesEnabled?: boolean;
+    /** Externally controlled drag/pan mode (overrides internal state when provided) */
+    isDragMode?: boolean;
+}
+
+export declare interface FlowDiagramEdge {
+    data: {
+        id: string;
+        source: string;
+        target: string;
+        sourceProperty?: string;
+        targetProperty?: string;
+        connection?: SqueedConnectionRef;
+        label?: string;
+        /** Chakra token or hex; overrides the theme/edgeColor line color for this edge */
+        color?: string;
+        isInverted?: boolean;
+        isEdgeAnimated?: boolean;
+        isEdgeDashed?: boolean;
+    };
+}
+
+export declare interface FlowDiagramNode {
+    data: {
+        id: string;
+        label?: string;
+        text?: string;
+        code?: string;
+        type: string;
+        parent?: string;
+        headerTitle?: string;
+        description?: Record<string, any>;
+        viewProps?: any;
+        config?: Record<string, any>;
+    };
+}
+
+/** Top-level props for the FlowDiagram component */
+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 */
+    edges?: FlowDiagramEdge[];
+    /** Diagram configuration */
+    config?: FlowDiagramConfig;
+    /** Event callbacks */
+    callbacks?: FlowDiagramCallbacks;
+    showBottomBar?: boolean;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+}
+
+/** "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 interface FlowEdgeProperties {
+    sourceProperty?: string;
+    targetProperty?: string;
+}
+
+/** Handle passed to `callbacks.onInit`. */
+export declare interface FlowEngine {
+    zoom(): number;
+    /** Set zoom keeping the current pan (like cytoscape `cy.zoom(level)`) */
+    zoom(level: number): void;
+    pan(): Point;
+    pan(p: Point): void;
+    /** Zoom keeping the model point under `renderedPoint` (container px) fixed */
+    zoomAt(level: number, renderedPoint: Point): void;
+    /** Fit all elements into the container with `padding` rendered px */
+    fit(padding?: number): void;
+    /** Centre all elements at the current zoom */
+    center(): void;
+    clientToModel(clientX: number, clientY: number): Point;
+    modelToClient(p: Point): Point;
+    getNodeBox(id: string): Box | undefined;
+    onViewportChange(fn: (vp: ViewportState) => void): () => void;
+}
+
+export declare const getChakraColorHex: (color?: any, opacity?: any) => any;
+
+export declare const getColorVariant: (color: string) => {
+    secondary: string;
+    primary?: undefined;
+    light?: undefined;
+} | {
+    primary: string;
+    secondary: string;
+    light: 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";
+
+export declare type NodeAlignment = "leading" | "center" | "trailing";
+
+/** Actions shown in the hover overlay above nodes */
+export declare interface NodeOverlayAction {
+    id: string;
+    icon: any;
+    label: string;
+}
+
+/** Props passed to custom node overlay renderer */
+export declare interface NodeOverlayProps {
+    nodeId: string;
+    nodeData: any;
+    isRoot: boolean;
+    isParent: boolean;
+    isHovered: boolean;
+    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";
+}
+
+declare interface Point {
+    x: number;
+    y: number;
+}
+
+/** 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 extends FlowEdgeProperties {
+    source: string;
+    target: string;
+    isInverted?: boolean | null;
+    connection?: SqueedConnectionRef;
+}
+
+/**
+ * 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" | "connection";
+};
+
+/** Props passed to custom edge selection toolbar renderer */
+export declare interface SelectedEdgeToolbarProps {
+    edgeId: string;
+    edgeData: any;
+    onDeselect: () => void;
+}
+
+/** Props passed to custom node selection toolbar renderer */
+export declare interface SelectedNodeToolbarProps {
+    selectedNodeIds: string[];
+    selectedNodeData: any[];
+    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?: FlowEdgeProperties & {
+        source: string;
+        target: string;
+        isInverted?: boolean | null;
+        connection?: SqueedConnectionRef;
+    };
+    key?: string;
+    value?: unknown;
+}
+
+export declare interface SqueedConnection extends FlowEdgeProperties {
+    target: string;
+    id?: string;
+    label?: string;
+    color?: string;
+    style?: "solid" | "dashed" | "animated";
+}
+
+export declare interface SqueedConnectionRef {
+    address: string;
+    key: string;
+}
+
+/** 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" | "$connections";
+
+/** 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;
+    border: string;
+    darkColor: string;
+    backgroundWhiteColor: string;
+    borderSecondary: string;
+    colorActive: string;
+    colorInactive: string;
+    iconColor: string;
+    moreIconColor: string;
+    colorText: string;
+    themedColorText: string;
+    logoColor: any;
+    logoColorSecondary: any;
+    darkColorActive: string;
+    greenColor: string;
+};
+
+/**
+ * Hook that stops all event propagation on a DOM element.
+ * Use this on any interactive element inside a node (inputs, textareas, forms)
+ * to prevent cytoscape from intercepting mouse/keyboard events.
+ *
+ * @param active - Only attach listeners when true (e.g. when editing)
+ * @returns ref to attach to the wrapper element
+ *
+ * @example
+ * const inputRef = useStopPropagation<HTMLDivElement>(isEditing);
+ * return <div ref={inputRef}><input /></div>;
+ */
+export declare function useStopPropagation<T extends HTMLElement>(active?: boolean): MutableRefObject<T>;
+
+export declare function useThemeContentColors(color: any): {
+    bgColor: any;
+    highlightColor: string;
+    borderColor: string;
+    textColor: string;
+    propertyColor: string;
+    secondary: string;
+    bgColorFaint: any;
+    highlightColorFaint: string;
+};
+
+declare interface ViewportState {
+    pan: Point;
+    zoom: number;
+}
+
+export { }