@3plate/graph-core 0.1.4 → 0.1.6

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,81 +140,218 @@ 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();
     describe(desc: string): Updater<N, E>;
     addNode(node: any): Updater<N, E>;
+    addNodes(...nodes: any[]): Updater<N, E>;
     deleteNode(node: any): Updater<N, E>;
+    deleteNodes(...nodes: any[]): Updater<N, E>;
     updateNode(node: any): Updater<N, E>;
+    updateNodes(...nodes: any[]): Updater<N, E>;
     addEdge(edge: any): Updater<N, E>;
+    addEdges(...edges: any[]): Updater<N, E>;
     deleteEdge(edge: any): Updater<N, E>;
+    deleteEdges(...edges: any[]): Updater<N, E>;
     updateEdge(edge: any): Updater<N, E>;
+    updateEdges(...edges: any[]): 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 +362,60 @@ 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>);
+    reset(): void;
+    /** Initialize the API */
     init(): Promise<void>;
+    private applyHistory;
+    /** 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;
+    /** Replace entire history (clears prior) */
+    replaceHistory(frames: Update<N, E>[]): Promise<void>;
+    /** Rebuild from snapshot (nodes/edges) */
+    replaceSnapshot(nodes: N[], edges: E[], description?: string): Promise<void>;
+    private get graph();
+    /** 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,8 +424,203 @@ 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>;
+}
+
+type SnapshotMessage<N, E> = {
+    type: 'snapshot';
+    nodes: N[];
+    edges: E[];
+    description?: string;
+};
+type UpdateMessage<N, E> = {
+    type: 'update';
+    description?: string;
+} & Update<N, E>;
+type HistoryMessage<N, E> = {
+    type: 'history';
+    frames: Update<N, E>[];
+};
+type IngestMessage<N, E> = SnapshotMessage<N, E> | UpdateMessage<N, E> | HistoryMessage<N, E>;
+/**
+ * Ingest class handles applying ingest messages to an API instance.
+ * This is the core ingestion functionality, separate from UI concerns.
+ */
+declare class Ingest<N, E> {
+    api: API<N, E>;
+    constructor(api: API<N, E>);
+    /**
+     * Apply an incoming ingest message to the API.
+     * - snapshot: rebuild state from nodes/edges (clears prior history)
+     * - update: apply incremental update
+     * - history: initialize from a set of frames (clears prior history)
+     */
+    apply(msg: IngestMessage<N, E>): Promise<void>;
+}
+
+type StatusListener$2 = (status: 'connecting' | 'connected' | 'reconnecting' | 'closed' | 'error', detail?: any) => void;
+declare class WebSocketSource<N, E> {
+    private url;
+    private ws;
+    private onMessage;
+    private onStatus?;
+    private reconnectMs;
+    private closedByUser;
+    private connectStartTime;
+    private totalTimeoutMs;
+    private totalTimeoutTimer;
+    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$2, reconnectMs?: number);
+    connect(): void;
+    disconnect(): void;
+    private startTotalTimeout;
+    private clearTotalTimeout;
+    private open;
+}
+
+type StatusListener$1 = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+declare class FileSystemSource<N, E> {
+    private handle;
+    private onMessage;
+    private onStatus?;
+    private timer;
+    private lastSize;
+    private filename;
+    private intervalMs;
+    constructor(onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener$1, filename?: string, intervalMs?: number);
+    openDirectory(): Promise<void>;
+    close(): void;
+    private startPolling;
+    private readNewLines;
+}
+
+type StatusListener = (status: 'idle' | 'opened' | 'reading' | 'error' | 'closed', detail?: any) => void;
+declare class FileSource<N, E> {
+    private url;
+    private onMessage;
+    private onStatus?;
+    private timer;
+    private lastETag;
+    private lastContent;
+    private intervalMs;
+    private closed;
+    constructor(url: string, onMessage: (msg: IngestMessage<N, E>) => void, onStatus?: StatusListener, intervalMs?: number);
+    connect(): Promise<void>;
+    close(): void;
+    private startPolling;
+    private poll;
+}
+
+/**
+ * Types for the Playground component
+ */
+type ExampleNode = string | {
+    id: string;
+    title?: string;
+    type?: string;
+    ports?: {
+        in?: string[];
+        out?: string[];
+    };
+};
+type ExampleEdgeEnd = string | {
+    id: string;
+    port?: string;
+    marker?: 'arrow' | 'circle' | 'diamond' | 'bar';
+};
+type ExampleEdge = string | {
+    source: ExampleEdgeEnd;
+    target: ExampleEdgeEnd;
+    type?: string;
+};
+type ExampleOptions = {
+    canvas?: {
+        colorMode?: 'light' | 'dark' | 'system';
+        nodeTypes?: Record<string, Record<string, string>>;
+        edgeTypes?: Record<string, Record<string, string>>;
+    };
+};
+type ExampleSource = {
+    type: 'file';
+    path: string;
+} | {
+    type: 'websocket';
+    url: string;
+};
+type Example = {
+    name: string;
+    description?: string;
+    nodes: ExampleNode[];
+    edges: ExampleEdge[];
+    options?: ExampleOptions;
+    source?: ExampleSource;
+};
+type PlaygroundOptions = {
+    root: string | HTMLElement;
+    examples: Record<string, Example>;
+    defaultExample?: string;
+};
+
+declare class Playground {
+    private options;
+    private rootElement;
+    private currentExample;
+    private currentGraph;
+    private ingest;
+    private isEditable;
+    private wsSource;
+    private fsSource;
+    private fileSource;
+    private wsStatus;
+    private fsStatus;
+    private fileStatus;
+    private activeSourceType;
+    private wsUrl;
+    private sourceModal;
+    private helpOverlay;
+    private exampleList;
+    private graphContainerId;
+    constructor(options: PlaygroundOptions);
+    init(): Promise<void>;
+    private injectStyles;
+    private createDOM;
+    private setupEventListeners;
+    private getResolvedColorMode;
+    private getOptions;
+    private renderGraph;
+    private updateHistoryLabel;
+    private connectExampleSource;
+    private disconnectAllSources;
+    private openHelp;
+    private closeHelp;
+    private handleIngestMessage;
+    private updateSourceIcon;
+    private updateWsStatus;
+    private updateFsStatus;
+    private updateFileStatus;
+    private createSourceModal;
+    private selectSourceType;
+    private updateSourceModalContent;
+    private updateSourceModal;
+    private openSourceModal;
+    private closeSourceModal;
+    private handleConnect;
+    private handleDisconnect;
+    private handleChangeConnection;
+    private handleOpenFolder;
+    private handleCloseFolder;
 }
 
 declare function graph<N, E>(args?: APIArguments<N, E>): Promise<API<N, E>>;
 
-export { graph as default, graph };
+export { type Example, type ExampleEdge, type ExampleNode, type ExampleOptions, FileSource, FileSystemSource, type HistoryMessage, Ingest, type IngestMessage, Playground, type PlaygroundOptions, type SnapshotMessage, type UpdateMessage, WebSocketSource, graph as default, graph };