@3plate/graph-core 0.1.2 → 0.1.5

package/dist/index.d.cts

@@ -2,132 +2,430 @@ type Side = 'source' | 'target';
 type MergeOrder = Side[];
 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;
-    defaultPortOffset?: 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 EdgeAttributes = {
-    width?: number;
-    style?: string;
-    color?: string;
-    turnRadius?: number;
-    sourceTerminal?: string | null;
-    targetTerminal?: string | null;
+/**
+ * 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 = {
+    /** Canvas background color */
+    bg?: string;
+    /** Shadow color for floating elements */
+    shadow?: string;
 };
-type NodeAttributes = {
-    strokeWidth?: number;
-    strokeStyle?: string;
+/** Node styling properties */
+type NodeTheme = {
+    /** Node background color */
+    bg?: string;
+    /** Node border color */
+    border?: string;
+    /** Node border color on hover */
+    borderHover?: string;
+    /** Node border color when selected */
+    borderSelected?: string;
+    /** Node text color */
+    text?: string;
+    /** Node secondary text color */
+    textMuted?: string;
 };
-type RenderNode<N> = (node: N) => HTMLElement;
-type EdgeStyle = (type: string) => EdgeAttributes;
-type NodeStyle<N> = (node: N) => NodeAttributes;
-type PortStyle = 'inside' | 'outside' | 'custom';
+/** Port styling properties */
+type PortTheme = {
+    /** Port background color */
+    bg?: string;
+    /** Port background color on hover */
+    bgHover?: string;
+};
+/** Edge styling properties */
+type EdgeTheme = {
+    /** Edge stroke color */
+    color?: string;
+};
+/** Combined theme with all customizable properties */
+type ThemeVars = CanvasTheme & NodeTheme & PortTheme & EdgeTheme;
+/** Options for the canvas */
 type CanvasOptions<N> = {
-    renderNode?: RenderNode<N>;
-    nodeStyle?: NodeStyle<N>;
-    edgeStyle?: EdgeStyle;
+    /** Canvas width in pixels or percentage */
     width?: number | string;
+    /** Canvas height in pixels or percentage */
     height?: number | string;
-    portStyle?: PortStyle;
-    classPrefix?: string;
+    /** Padding inside the canvas viewport */
+    padding?: 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;
+};
+/** 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)[];
+    };
+};
+/** 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 StructuredNode<P> = {
+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;
-    ports?: {
-        in?: P[];
-        out?: P[];
+    type?: string;
+    ports: {
+        in?: PortData[];
+        out?: PortData[];
     };
+    render?: RenderNode<any>;
+    dims?: Dims;
 };
-type StructuredEdge = {
+
+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;
 };
-type StructuredPort = {
+
+declare class Updater<N, E> {
+    update: Update<N, E>;
+    constructor();
+    describe(desc: string): Updater<N, E>;
+    addNode(node: any): Updater<N, E>;
+    deleteNode(node: any): Updater<N, E>;
+    updateNode(node: any): Updater<N, E>;
+    addEdge(edge: any): Updater<N, E>;
+    deleteEdge(edge: any): Updater<N, E>;
+    updateEdge(edge: any): Updater<N, E>;
+    static add<N, E>(nodes: N[], edges: E[]): Updater<N, E>;
+}
+
+type EditEdgeProps = {
     id: string;
-    label: string;
-};
-type Nav = 'first' | 'last' | 'prev' | 'next';
-type NodeProps<N, P> = (node: N) => StructuredNode<P>;
-type EdgeProps<E> = (edge: E) => StructuredEdge;
-type PortProps<P> = (port: P) => StructuredPort;
-type APIOptions<N, E, P> = GraphOptions & CanvasOptions<N> & {
-    nodeProps?: NodeProps<N, P>;
-    edgeProps?: EdgeProps<E>;
-    portProps?: PortProps<P>;
-};
-type APIArguments<N, E, P> = APIOptions<N, E, P> & {
-    nodes?: N[];
-    edges?: E[];
+    type?: string;
+    source: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
+    target: {
+        id: string;
+        port?: string;
+        marker?: MarkerType;
+    };
 };
-declare class API<N, E, P> {
+/** Core graph API */
+declare class API<N, E> {
     private state;
     private seq;
     private index;
     private canvas;
-    private _options;
-    options: Required<APIOptions<N, E, P>>;
-    constructor(options: APIOptions<N, E, P>);
-    render(): HTMLElement;
+    private options;
+    private history;
+    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;
+    /** 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(callback: (update: Update<N, E>) => void): 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 getDims;
-    private _updateNode;
-    private _updateEdge;
+    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;
     private _removeNode;
+    private _updateNode;
     private _addEdge;
     private _removeEdge;
-    private _onOptionChange;
-}
-declare class Update<N, E> {
-    addedNodes: N[];
-    removedNodes: N[];
-    updatedNodes: N[];
-    addedEdges: E[];
-    removedEdges: E[];
-    updatedEdges: E[];
-    desc?: string;
-    constructor();
-    describe(desc: string): void;
-    addNode(node: N): void;
-    deleteNode(node: N): void;
-    updateNode(node: N): void;
-    addEdge(edge: E): void;
-    deleteEdge(edge: E): void;
-    updateEdge(edge: E): void;
+    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, P>(args?: APIArguments<N, E, P>): Promise<API<N, E, P>>;
+
+declare function graph<N, E>(args?: APIArguments<N, E>): Promise<API<N, E>>;
 
 export { graph as default, graph };