@filekit-studio/diagram 0.0.0-stage → 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,597 @@
+import React from 'react';
+import { GridStyle, SketchUIConfig, ThemeMode, PanelVariant, SketchDocument, SketchController } from '@filekit-studio/sketch';
+export { GridStyle, PanelVariant, SketchBoardElement, SketchController, SketchDocument, SketchUIConfig, ThemeMode } from '@filekit-studio/sketch';
+
+/**
+ * @filekit-studio/diagram
+ * Declarative diagram schemas, types, and configuration options.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Diagram flow direction for automatic DAG / hierarchical layout.
+ * - 'TB': Top-to-Bottom (vertical waterfall / tree)
+ * - 'BT': Bottom-to-Top (bottom-up hierarchy)
+ * - 'LR': Left-to-Right (horizontal pipeline / sequence)
+ * - 'RL': Right-to-Left (reverse horizontal pipeline)
+ */
+type DiagramDirection = 'TB' | 'BT' | 'LR' | 'RL';
+/**
+ * Supported geometric shapes for diagram nodes.
+ */
+type DiagramNodeShape = 'rectangle' | 'rounded' | 'diamond' | 'ellipse' | 'circle' | 'cylinder' | 'database' | 'cloud' | 'sticky' | 'table';
+/**
+ * Semantic preset color themes for diagram nodes and clusters.
+ */
+type DiagramNodeTheme = 'indigo' | 'blue' | 'emerald' | 'green' | 'amber' | 'yellow' | 'rose' | 'red' | 'purple' | 'violet' | 'slate' | 'neutral' | 'sky' | 'cyan' | 'teal' | 'orange';
+/**
+ * Fill pattern styles applied to rough-sketch nodes.
+ */
+type DiagramFillStyle = 'solid' | 'hachure' | 'cross-hatch' | 'dots' | 'none';
+/**
+ * Connector line dash styles.
+ */
+type DiagramLineStyle = 'solid' | 'dashed' | 'dotted';
+/**
+ * Declarative node specification inside a diagram graph.
+ */
+interface DiagramNode {
+    /**
+     * Unique identifier for the node.
+     * Edges reference this identifier via `from` and `to`.
+     */
+    id: string;
+    /**
+     * Primary text label displayed on the node.
+     * Supports multi-line strings separated by newline characters (`\n`).
+     */
+    label: string;
+    /**
+     * Secondary description or subtitle rendered below the main label.
+     */
+    description?: string;
+    /**
+     * Visual geometric shape. Default: 'rounded'.
+     */
+    shape?: DiagramNodeShape;
+    /**
+     * Semantic theme palette or hex color string (e.g. 'indigo', 'emerald', '#6366f1').
+     */
+    color?: DiagramNodeTheme | string;
+    /**
+     * Custom border stroke color hex override.
+     */
+    strokeColor?: string;
+    /**
+     * Custom background fill color hex override.
+     */
+    fillColor?: string;
+    /**
+     * Custom text color hex override.
+     */
+    textColor?: string;
+    /**
+     * Rough-sketch shading fill pattern. Default: 'hachure'.
+     */
+    fillStyle?: DiagramFillStyle;
+    /**
+     * Border stroke line thickness in pixels. Default: 2.
+     */
+    strokeWidth?: number;
+    /**
+     * Border stroke dash style: 'solid' | 'dashed' | 'dotted'. Default: 'solid'.
+     */
+    strokeStyle?: DiagramLineStyle;
+    /**
+     * Hand-drawn roughness intensity (0 = crisp geometric, 2 = rough sketchy). Default: 1.
+     */
+    roughness?: number;
+    /**
+     * Node opacity between 0 and 1. Default: 1.
+     */
+    opacity?: number;
+    /**
+     * Optional tech stencil or brand icon name (e.g. 'aws', 'docker', 'k8s', 'postgres', 'react', 'redis').
+     */
+    icon?: string;
+    /**
+     * Fixed node width in pixels. If omitted, automatically sized based on label content.
+     */
+    width?: number;
+    /**
+     * Fixed node height in pixels. If omitted, automatically sized based on label content.
+     */
+    height?: number;
+    /**
+     * Explicit X canvas coordinate override. Bypasses auto-layout if provided.
+     */
+    x?: number;
+    /**
+     * Explicit Y canvas coordinate override. Bypasses auto-layout if provided.
+     */
+    y?: number;
+    /**
+     * Typography font size in pixels. Default: 16.
+     */
+    fontSize?: number;
+    /**
+     * Typography font family: 'sans' | 'serif' | 'mono' | 'comic'. Default: 'sans'.
+     */
+    fontFamily?: 'sans' | 'serif' | 'mono' | 'comic';
+    /**
+     * Text alignment: 'left' | 'center' | 'right'. Default: 'center'.
+     */
+    textAlign?: 'left' | 'center' | 'right';
+    /**
+     * Optional badge pill displayed in the top-right corner of the node (e.g. 'v2', 'PROD', 'REST').
+     */
+    badge?: string;
+    /**
+     * Arbitrary custom user metadata attached to the node.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Declarative directional edge connecting two nodes.
+ */
+interface DiagramEdge {
+    /**
+     * Optional unique edge identifier.
+     */
+    id?: string;
+    /**
+     * Identifier of the source node where the connector originates.
+     */
+    from: string;
+    /**
+     * Identifier of the destination node where the connector terminates.
+     */
+    to: string;
+    /**
+     * Optional label text rendered along the connector line.
+     */
+    label?: string;
+    /**
+     * Connector line dash style: 'solid' | 'dashed' | 'dotted'. Default: 'solid'.
+     */
+    style?: DiagramLineStyle;
+    /**
+     * Line stroke color hex. Default: '#475569'.
+     */
+    color?: string;
+    /**
+     * Line thickness in pixels. Default: 2.
+     */
+    strokeWidth?: number;
+    /**
+     * Render arrowhead at the destination node. Default: true.
+     */
+    arrowEnd?: boolean;
+    /**
+     * Render arrowhead at the source node. Default: false.
+     */
+    arrowStart?: boolean;
+    /**
+     * Hand-drawn roughness for the connector line. Default: 1.
+     */
+    roughness?: number;
+    /**
+     * Connector routing algorithm style: 'straight' | 'curved' | 'elbow'. Default inherits layoutOptions.edgeRouting.
+     */
+    routing?: 'straight' | 'curved' | 'elbow';
+    /**
+     * Explicit anchor attachment position on the source node.
+     */
+    startAnchor?: 'top' | 'bottom' | 'left' | 'right';
+    /**
+     * Explicit anchor attachment position on the destination node.
+     */
+    endAnchor?: 'top' | 'bottom' | 'left' | 'right';
+    /**
+     * Enable/disable submerged tunneling through intermediate shapes for this edge.
+     */
+    tunneling?: boolean;
+}
+/**
+ * Declarative bounding group container wrapping multiple nodes.
+ */
+interface DiagramGroup {
+    /**
+     * Unique group identifier.
+     */
+    id: string;
+    /**
+     * Label title displayed on the group frame badge (e.g. 'VPC Subnet', 'Auth Service Cluster').
+     */
+    label: string;
+    /**
+     * List of node IDs contained inside this group container.
+     */
+    nodeIds: string[];
+    /**
+     * Semantic theme palette or border color hex.
+     */
+    color?: DiagramNodeTheme | string;
+    /**
+     * Background fill color hex tint for the container area.
+     */
+    backgroundColor?: string;
+    /**
+     * Border outline style: 'solid' | 'dashed'. Default: 'dashed'.
+     */
+    borderStyle?: 'solid' | 'dashed';
+}
+/**
+ * Complete declarative diagram graph specification.
+ */
+interface DiagramData {
+    /**
+     * Diagram title / document name. Default: 'System Architecture'.
+     */
+    title?: string;
+    /**
+     * Flow layout direction: 'TB' | 'BT' | 'LR' | 'RL'. Default: 'LR'.
+     */
+    direction?: DiagramDirection;
+    /**
+     * Fine-tuning layout configuration and spacing options embedded directly in JSON.
+     */
+    layout?: DiagramLayoutOptions;
+    /**
+     * Collection of graph nodes.
+     */
+    nodes: DiagramNode[];
+    /**
+     * Collection of directional connector edges.
+     */
+    edges?: DiagramEdge[];
+    /**
+     * Optional cluster/group container frames wrapping subsets of nodes.
+     */
+    groups?: DiagramGroup[];
+    /**
+     * Canvas background color hex. Default: '#f0f4f8'.
+     */
+    canvasBackground?: string;
+    /**
+     * Canvas grid pattern style: 'grid' | 'dots' | 'cross' | 'none'. Default: 'dots'.
+     */
+    gridStyle?: GridStyle;
+}
+/**
+ * Fine-tuning configuration options for the automatic layout engine.
+ */
+interface DiagramLayoutOptions {
+    /**
+     * Flow layout direction override.
+     */
+    direction?: DiagramDirection;
+    /**
+     * Perpendicular spacing between parallel sibling nodes on the same rank. Default: 60.
+     */
+    nodeSpacing?: number;
+    /**
+     * Longitudinal spacing between successive ranks / layers. Default: 120.
+     */
+    rankSpacing?: number;
+    /**
+     * Outer margin padding in pixels around the entire diagram. Default: 60.
+     */
+    padding?: number;
+    /**
+     * Internal padding in pixels around nodes inside group container frames. Default: 48.
+     */
+    groupPadding?: number;
+    /**
+     * Spacing between group clusters and compound frames. Default: 180.
+     */
+    clusterSpacing?: number;
+    /**
+     * Spacing between columns/ranks inside group container frames. Default: 120.
+     */
+    intraRankSpacing?: number;
+    /**
+     * Global default edge routing algorithm: 'straight' | 'curved' | 'elbow'. Default: 'straight'.
+     */
+    edgeRouting?: 'straight' | 'curved' | 'elbow';
+    /**
+     * Submerged passthrough tunneling: automatically dims to 35% opacity and dots connector segments passing through shapes. Default: true.
+     */
+    tunneling?: boolean;
+    /**
+     * Opacity of connector segments passing through intermediate shapes (0.1 - 0.6). Default: 0.35.
+     */
+    passthroughOpacity?: number;
+    /**
+     * Stroke style of connector segments passing through intermediate shapes: 'dotted' | 'dashed'. Default: 'dotted'.
+     */
+    passthroughStyle?: 'dotted' | 'dashed';
+    /**
+     * Default node width in pixels if not explicitly specified on the node. Default: 180.
+     */
+    defaultNodeWidth?: number;
+    /**
+     * Default node height in pixels if not explicitly specified on the node. Default: 80.
+     */
+    defaultNodeHeight?: number;
+}
+/**
+ * Result of executing the automatic layout engine on a diagram graph.
+ */
+interface DiagramLayoutResult {
+    /**
+     * Positioned nodes with calculated x, y, width, and height.
+     */
+    nodes: (DiagramNode & {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    })[];
+    /**
+     * Connecting edges with calculated start, control, and end points.
+     */
+    edges: DiagramEdge[];
+    /**
+     * Positioned groups with calculated bounding boxes (x, y, width, height).
+     */
+    groups: (DiagramGroup & {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    })[];
+    /**
+     * Overall bounding box encompassing all positioned elements.
+     */
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Props accepted by the `<Diagram />` and `<SketchDiagram />` React components.
+ */
+interface DiagramProps {
+    /**
+     * Declarative diagram specification (JSON object, parsed DiagramData, or JSON string).
+     */
+    data: DiagramData | string;
+    /**
+     * Rendering display mode:
+     * - 'viewer': Clean, embeddable documentation viewer with zero editing chrome (uses `<SketchViewer />`).
+     * - 'editor': Full interactive studio whiteboard with editing palettes and canvas tools (uses `<SketchEditor />`).
+     * Default: 'viewer'.
+     */
+    mode?: 'viewer' | 'editor';
+    /**
+     * Fine-tuning layout configuration options (spacing, padding, direction).
+     */
+    layoutOptions?: DiagramLayoutOptions;
+    /**
+     * Granular visibility configuration for all 54 UI controls and menus.
+     */
+    uiConfig?: SketchUIConfig;
+    /**
+     * Theme mode: 'light', 'dark', or 'system'. Default: 'system'.
+     */
+    theme?: ThemeMode;
+    /**
+     * Canvas background color hex override (e.g. '#ffffff', '#121316', '#f0f4f8').
+     */
+    canvasBackground?: string;
+    /**
+     * Canvas grid pattern style: 'grid' | 'dots' | 'cross' | 'none'. Default: 'dots'.
+     */
+    gridStyle?: GridStyle;
+    /**
+     * Enable mouse wheel zooming and click-and-drag panning in viewer mode. Default: true.
+     */
+    interactive?: boolean;
+    /**
+     * Automatically scale and center the diagram to comfortably fit within its container. Default: true.
+     */
+    autoFit?: boolean;
+    /**
+     * Display 1-click clipboard PNG image copy button in the top-right corner of viewer mode. Default: true.
+     */
+    showCopyButton?: boolean;
+    /**
+     * Display minimal zoom level percentage and +/- controls in the bottom-left corner of viewer mode. Default: false.
+     */
+    showZoomControls?: boolean;
+    /**
+     * Title badge displayed on the diagram. Overrides `data.title` if provided.
+     */
+    title?: string;
+    /**
+     * Panel aesthetic variant in editor mode: 'classic' | 'neumorphic'. Default: 'classic'.
+     */
+    panelVariant?: PanelVariant;
+    /**
+     * Local storage key used for auto-saving modifications in editor mode.
+     */
+    storageKey?: string | null;
+    /**
+     * Callback invoked when user clicks the Exit button.
+     */
+    onExit?: () => void;
+    /**
+     * Target URL opened when clicking the Guide button.
+     */
+    guideHref?: string;
+    /**
+     * Callback invoked when user clicks the Guide button.
+     */
+    onOpenGuide?: () => void;
+    /**
+     * Callback invoked whenever diagram elements change in editor mode.
+     */
+    onChange?: (document: SketchDocument) => void;
+    /**
+     * Ref to receive imperative SketchController controls (zoomToFit, exportToPng, etc.).
+     */
+    controllerRef?: React.Ref<SketchController>;
+    /**
+     * Custom CSS class name for the root container.
+     */
+    className?: string;
+    /**
+     * Custom inline styles for the root container.
+     */
+    style?: React.CSSProperties;
+}
+
+/**
+ * @filekit-studio/diagram
+ * Declarative <Diagram /> and <SketchDiagram /> React components.
+ *
+ * Automatically compiles graph JSON specifications into Sketch documents
+ * and renders them via <SketchViewer /> (viewer mode) or <SketchEditor /> (studio mode).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * <Diagram />
+ *
+ * Declarative Diagram-as-Code React component. Accepts a graph JSON specification
+ * or JSON string, runs automatic DAG layout, and renders it in browser.
+ */
+declare const Diagram: React.ForwardRefExoticComponent<DiagramProps & React.RefAttributes<SketchController>>;
+/**
+ * Alias for <Diagram /> with explicit Sketch prefix.
+ */
+declare const SketchDiagram: React.ForwardRefExoticComponent<DiagramProps & React.RefAttributes<SketchController>>;
+
+/**
+ * @filekit-studio/diagram
+ * Declarative Graph JSON to SketchDocument compiler.
+ *
+ * Compiles high-level graph specifications (nodes, edges, groups, directions)
+ * into fully-formed SketchBoardElement arrays ready for rendering.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Safely parses input data which may be a raw JSON string or structured DiagramData object.
+ */
+declare function parseDiagramData(input: DiagramData | string): DiagramData;
+/**
+ * Converts a declarative DiagramData graph into a full SketchDocument.
+ */
+declare function diagramToSketch(input: DiagramData | string, options?: DiagramLayoutOptions): SketchDocument;
+
+/**
+ * @filekit-studio/diagram
+ * Excalidraw JSON to SketchDocument converter.
+ *
+ * Imports .excalidraw schema files and element arrays into SketchDocument format.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Shape of an individual element in Excalidraw JSON schemas.
+ */
+interface ExcalidrawRawElement {
+    id: string;
+    type: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    angle?: number;
+    strokeColor?: string;
+    backgroundColor?: string;
+    fillStyle?: string;
+    strokeWidth?: number;
+    strokeStyle?: string;
+    roughness?: number;
+    opacity?: number;
+    text?: string;
+    fontSize?: number;
+    fontFamily?: number;
+    textAlign?: string;
+    startBinding?: {
+        elementId: string;
+        focus?: number;
+        gap?: number;
+    } | null;
+    endBinding?: {
+        elementId: string;
+        focus?: number;
+        gap?: number;
+    } | null;
+    startArrowhead?: string | null;
+    endArrowhead?: string | null;
+    points?: [number, number][];
+    groupIds?: string[];
+    isDeleted?: boolean;
+}
+/**
+ * Shape of an Excalidraw file JSON document.
+ */
+interface ExcalidrawDocument {
+    type?: string;
+    version?: number;
+    source?: string;
+    elements?: ExcalidrawRawElement[];
+    appState?: {
+        viewBackgroundColor?: string;
+        gridSize?: number | null;
+    };
+}
+/**
+ * Converts Excalidraw JSON document or element array into a native SketchDocument.
+ */
+declare function excalidrawToSketch(input: ExcalidrawDocument | ExcalidrawRawElement[] | string, documentName?: string): SketchDocument;
+
+/**
+ * @filekit-studio/diagram
+ * Preset theme color palettes for diagram nodes and group frames.
+ *
+ * @packageDocumentation
+ */
+
+interface ColorPalette {
+    stroke: string;
+    fill: string;
+    text: string;
+    borderStyle?: 'solid' | 'dashed';
+}
+declare const THEME_PALETTES: Record<string, ColorPalette>;
+/**
+ * Resolves color palette tokens or hex strings into stroke, fill, and text colors.
+ */
+declare function resolveNodeColors(color?: DiagramNodeTheme | string, customStroke?: string, customFill?: string): ColorPalette;
+
+/**
+ * @filekit-studio/diagram
+ * Deterministic Hierarchical DAG & Compound Group Layout Engine.
+ *
+ * Implements shape-aware node measurement, intra-cluster DAG ranking,
+ * and inter-cluster clearance so groups never collide or overlap.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Estimates optimal node width and height based on label length, lines, and shape.
+ */
+declare function estimateNodeDimensions(node: DiagramNode, defaultWidth?: number, defaultHeight?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Computes deterministic coordinates with Compound Cluster layout.
+ */
+declare function layoutDiagram(data: DiagramData, options?: DiagramLayoutOptions): DiagramLayoutResult;
+
+export { type ColorPalette, Diagram, type DiagramData, type DiagramDirection, type DiagramEdge, type DiagramFillStyle, type DiagramGroup, type DiagramLayoutOptions, type DiagramLayoutResult, type DiagramLineStyle, type DiagramNode, type DiagramNodeShape, type DiagramNodeTheme, type DiagramProps, type ExcalidrawDocument, type ExcalidrawRawElement, SketchDiagram, THEME_PALETTES, diagramToSketch, estimateNodeDimensions, excalidrawToSketch, layoutDiagram, parseDiagramData, resolveNodeColors };