@3plate/graph-core 0.1.4 → 0.1.5

package/dist/index.d.cts

@@ -4,37 +4,105 @@ type NodeAlign = 'natural' | 'top' | 'bottom' | 'left' | 'right';
 type Orientation = 'TB' | 'BT' | 'LR' | 'RL';
 type Nav = 'first' | 'last' | 'prev' | 'next';
 type LayoutStep = 'alignChildren' | 'alignParents' | 'compact';
+type Dims = {
+    w: number;
+    h: number;
+};
 
 type MarkerType = 'arrow' | 'circle' | 'diamond' | 'bar' | 'none';
 
+/**
+ * Arguments to the API constructor.
+ *
+ * The caller can specify nodes and edges, or history,
+ * but not both.
+ *
+ * The root element ID is required.
+ */
 type APIArguments<N, E> = {
+    /** Options for the API */
     options?: APIOptions<N, E>;
+    /** Initial nodes */
     nodes?: N[];
+    /** Initial edges */
     edges?: E[];
+    /** Initial history */
     history?: Update<N, E>[];
+    /** Events */
+    events?: EventsOptions<N, E>;
+    /** Root element ID */
     root: string;
 };
+/** Options for the API */
 type APIOptions<N, E> = {
+    /** Options for the graph */
     graph?: GraphOptions;
+    /** Options for the canvas */
     canvas?: CanvasOptions<N>;
+    /** Options for node and edge properties */
     props?: PropsOptions<N, E>;
 };
+/** Options for the graph */
 type GraphOptions = {
+    /** Order in which edges are merged; see `MergeOrder` */
     mergeOrder?: MergeOrder;
+    /** Margin between nodes */
     nodeMargin?: number;
+    /** Size of dummy nodes */
     dummyNodeSize?: number;
+    /** Alignment of nodes */
     nodeAlign?: NodeAlign;
+    /** Spacing between edges */
     edgeSpacing?: number;
+    /** Turn radius */
     turnRadius?: number;
+    /** Orientation of the graph */
     orientation?: Orientation;
+    /** Margin between layers */
     layerMargin?: number;
+    /** Number of iterations for alignment */
     alignIterations?: number;
+    /** Alignment threshold */
     alignThreshold?: number;
+    /** Whether to separate track sets */
     separateTrackSets?: boolean;
+    /** Marker size */
     markerSize?: number;
+    /** Layout steps */
     layoutSteps?: LayoutStep[] | null;
 };
-type RenderNode<N> = (node: N) => HTMLElement;
+/**
+ * Events that can be handled by the user.
+ */
+type EventsOptions<N, E> = {
+    /** Called when a node is clicked */
+    nodeClick?: (node: N) => void;
+    /** Called when an edge is clicked */
+    edgeClick?: (edge: E) => void;
+    /** Called when a node is double-clicked */
+    editNode?: (node: N, callback: (node: N) => void) => void;
+    /** Called when a node should be added */
+    newNode?: (callback: (node: N) => void) => void;
+    /** Called when an edge is double-clicked */
+    editEdge?: (edge: E, callback: (edge: E) => void) => void;
+    /** Called when a node should be added */
+    addNode?: (node: NewNode, callback: (node: N) => void) => void;
+    /** Called when an edge should be added */
+    addEdge?: (edge: NewEdge<N>, callback: (edge: E) => void) => void;
+    /** Called when an edge should be removed */
+    removeEdge?: (edge: E, callback: (remove: boolean) => void) => void;
+    /** Called when a node should be removed */
+    removeNode?: (node: N, callback: (remove: boolean) => void) => void;
+    /** Called when a node should be updated */
+    updateNode?: (node: N, update: Record<string, any>, callback: (node: N) => void) => void;
+    /** Called when an edge should be updated */
+    updateEdge?: (edge: E, update: Record<string, any>, callback: (edge: E) => void) => void;
+    /** Called when history index/length changes */
+    historyChange?: (index: number, length: number) => void;
+};
+/** Function to render a node */
+type RenderNode<N> = (node: N, props?: NodeProps<N>) => HTMLElement;
+/** Color mode */
 type ColorMode = 'light' | 'dark' | 'system';
 /** Canvas background and general colors */
 type CanvasTheme = {
@@ -72,68 +140,184 @@ type EdgeTheme = {
 };
 /** Combined theme with all customizable properties */
 type ThemeVars = CanvasTheme & NodeTheme & PortTheme & EdgeTheme;
+/** Options for the canvas */
 type CanvasOptions<N> = {
+    /** Canvas width in pixels or percentage */
     width?: number | string;
+    /** Canvas height in pixels or percentage */
     height?: number | string;
-    /** Padding inside the canvas viewport (default: 20) */
+    /** Padding inside the canvas viewport */
     padding?: number;
-    classPrefix?: string;
-    markerSize?: number;
+    /** Whether the canvas is editable */
     editable?: boolean;
+    /** Whether to enable pan and zoom */
     panZoom?: boolean;
+    /** Function to render a node */
     renderNode?: RenderNode<N>;
+    /** Color mode */
     colorMode?: ColorMode;
+    /** Theme */
     theme?: ThemeVars;
+    /** Node type themes */
     nodeTypes?: Record<string, ThemeVars>;
+    /** Edge type themes */
     edgeTypes?: Record<string, ThemeVars>;
+    /** Marker size in pixels */
+    markerSize?: number;
 };
+/** Options for node and edge properties */
 type PropsOptions<N, E> = {
+    /** Function to get node properties */
     node?: GetNodeProps<N>;
+    /** Function to get edge properties */
     edge?: GetEdgeProps<N, E>;
 };
+/** Update to apply to the graph */
 type Update<N, E> = {
+    /** Nodes to add */
     addNodes?: N[];
+    /** Nodes to remove */
     removeNodes?: N[];
+    /** Nodes to update */
     updateNodes?: N[];
+    /** Edges to add */
     addEdges?: E[];
+    /** Edges to remove */
     removeEdges?: E[];
+    /** Edges to update */
     updateEdges?: E[];
+    /** Description of the update */
     description?: string;
 };
-type NodeProps<N> = {
+/** Node properties */
+type NodeProps<N> = NewNode & {
+    /** Node ID */
     id?: string;
+    /** Function to render a node */
+    render?: RenderNode<N>;
+};
+/** New node properties */
+type NewNode = {
+    /** Node title */
     title?: string;
+    /** Node text */
     text?: string;
+    /** Node type */
     type?: string;
+    /** Node ports */
     ports?: {
+        /** Input ports */
         in?: (string | PortProps)[];
+        /** Output ports */
         out?: (string | PortProps)[];
     };
-    render?: RenderNode<N>;
 };
-type EdgeEnd<N> = string | N | {
+/** New edge properties */
+type NewEdge<N> = {
+    /** Source node */
+    source: {
+        node: N;
+        port?: string;
+        marker?: MarkerType;
+    };
+    target: {
+        node: N;
+        port?: string;
+        marker?: MarkerType;
+    };
+    type?: string;
+};
+/** Edge end properties */
+type EdgeEnd<N> = 
+/** Edge end node ID */
+string | 
+/** Edge end node */
+N | 
+/** Structured edge end with id */
+{
+    /** Edge end node ID */
     id: string;
+    /** Edge end port ID */
     port?: string;
+    /** Edge end marker type */
     marker?: MarkerType;
-} | {
+} | 
+/** Structured edge end with node object */
+{
+    /** Edge end node object */
     node: N;
+    /** Edge end port ID */
     port?: string;
+    /** Edge end marker type */
     marker?: MarkerType;
 };
+/** Edge properties */
 type EdgeProps<N> = {
+    /** Edge ID */
     id?: string;
+    /** Edge label */
     label?: string;
+    /** Edge source */
     source: EdgeEnd<N>;
+    /** Edge target */
     target: EdgeEnd<N>;
+    /** Edge type */
     type?: string;
 };
+/** Port properties */
 type PortProps = {
+    /** Port ID */
     id: string;
+    /** Port label */
     label?: string;
 };
+/** Function to get node properties */
 type GetNodeProps<N> = (node: N) => NodeProps<N>;
+/** Function to get edge properties */
 type GetEdgeProps<N, E> = (edge: E) => EdgeProps<N>;
 
+type SegId = string;
+
+type NodeId = string;
+type PortData = {
+    id: string;
+    label?: string;
+    offset?: number;
+    size?: number;
+};
+type PublicNodeData = {
+    id: NodeId;
+    data: any;
+    version: number;
+    title?: string;
+    text?: string;
+    type?: string;
+    ports: {
+        in?: PortData[];
+        out?: PortData[];
+    };
+    render?: RenderNode<any>;
+    dims?: Dims;
+};
+
+type EdgeId = string;
+type PublicEdgeData = {
+    id: string;
+    data: any;
+    label?: string;
+    source: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
+    target: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
+    type?: string;
+};
+
 declare class Updater<N, E> {
     update: Update<N, E>;
     constructor();
@@ -147,6 +331,21 @@ declare class Updater<N, E> {
     static add<N, E>(nodes: N[], edges: E[]): Updater<N, E>;
 }
 
+type EditEdgeProps = {
+    id: string;
+    type?: string;
+    source: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
+    target: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
+};
+/** Core graph API */
 declare class API<N, E> {
     private state;
     private seq;
@@ -157,27 +356,54 @@ declare class API<N, E> {
     private nodeIds;
     private edgeIds;
     private nodeVersions;
+    private nodeOverrides;
+    private edgeOverrides;
+    private nodeFields;
     private nextNodeId;
     private nextEdgeId;
+    private events;
     private root;
     constructor(args: APIArguments<N, E>);
+    /** Current history index (0-based) */
+    getHistoryIndex(): number;
+    /** Current history length */
+    getHistoryLength(): number;
+    /** Toggle canvas editable mode without re-creating the graph */
+    setEditable(editable: boolean): void;
+    private get graph();
+    /** Initialize the API */
     init(): Promise<void>;
+    /** Navigate to a different state */
     nav(nav: Nav): void;
     private applyDiff;
-    addNode(node: any): Promise<void>;
-    deleteNode(node: any): Promise<void>;
-    updateNode(node: any): Promise<void>;
-    addEdge(edge: any): Promise<void>;
-    deleteEdge(edge: any): Promise<void>;
-    applyUpdate(update: Update<N, E>): Promise<void>;
-    private setNodePositions;
+    /** Add a node */
+    addNode(node: N): Promise<void>;
+    /** Delete a node */
+    deleteNode(node: N): Promise<void>;
+    /** Update a node */
+    updateNode(node: N): Promise<void>;
+    /** Add an edge */
+    addEdge(edge: E): Promise<void>;
+    /** Delete an edge */
+    deleteEdge(edge: E): Promise<void>;
+    /** Update an edge */
+    updateEdge(edge: E): Promise<void>;
+    /** Perform a batch of updates */
     update(callback: (updater: Updater<N, E>) => void): Promise<void>;
+    /** Rebuild the graph from scratch (removes all then re-adds all nodes/edges) */
+    rebuild(): Promise<void>;
+    private applyUpdate;
+    private setNodePositions;
     private measureNodes;
     private parseNode;
+    private detectNodeFields;
+    getNodeFields(): Map<string, 'string' | 'number' | 'boolean'>;
     private parseEdge;
     private parseEdgeEnd;
     private parseStringEdge;
     private parsePorts;
+    getNode(id: NodeId): PublicNodeData;
+    getEdge(id: EdgeId): PublicEdgeData;
     private getNodeId;
     private getEdgeId;
     private _addNode;
@@ -186,6 +412,18 @@ declare class API<N, E> {
     private _addEdge;
     private _removeEdge;
     private _updateEdge;
+    handleClickNode(id: NodeId): void;
+    handleClickEdge(id: SegId): void;
+    handleNewNode(): Promise<void>;
+    handleNewNodeFrom(source: {
+        id: string;
+        port?: string;
+    }): Promise<void>;
+    handleEditNode(id: NodeId): Promise<void>;
+    handleEditEdge(id: SegId): Promise<void>;
+    handleAddEdge(data: EditEdgeProps): Promise<void>;
+    handleDeleteNode(id: NodeId): Promise<void>;
+    handleDeleteEdge(id: EdgeId): Promise<void>;
 }
 
 declare function graph<N, E>(args?: APIArguments<N, E>): Promise<API<N, E>>;