@erd-studio/renderer 0.1.0

package/dist/types/store/editorStore.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Zustand store for the canvas: the state the shared canvas components
+ * (model and annotation nodes, FK edges, detail panel, legend) read and write.
+ *
+ * The store is provided through React context rather than imported as a
+ * module singleton, so every canvas instance can have its own:
+ *
+ *   - `createCanvasStore()` makes a standalone store holding just this slice.
+ *   - A host with more state (the VS Code extension) composes its own store
+ *     from `createCanvasSlice(set)` and passes it to `CanvasStoreProvider`.
+ *
+ * Components keep the familiar `useEditorStore((s) => …)` selector call; it
+ * reads whichever store the nearest `CanvasStoreProvider` supplies.
+ */
+import { type ReactNode } from 'react';
+import { type StoreApi } from 'zustand';
+import type { DisplayDomain, ExistingModelPreview } from '@erd-studio/core';
+import type { ModelFlowNode, FkFlowEdge, FkEdgeData, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
+/** Context menu state for edge right-click. */
+export interface EdgeContextMenu {
+    type: 'edge';
+    x: number;
+    y: number;
+    data: FkEdgeData;
+}
+/** Context menu state for node right-click. */
+export interface NodeContextMenu {
+    type: 'node';
+    x: number;
+    y: number;
+    modelName: string;
+}
+/** Context menu state for annotation right-click. */
+export interface AnnotationContextMenu {
+    type: 'annotation';
+    x: number;
+    y: number;
+    annotationId: string;
+}
+/** Union of context menu states. */
+export type ContextMenuState = EdgeContextMenu | NodeContextMenu | AnnotationContextMenu | null;
+/** Active drag line state for creating relationships via column drag. */
+export interface DragLineState {
+    sourceModelName: string;
+    sourceColumnName: string;
+    sourceX: number;
+    sourceY: number;
+    currentX: number;
+    currentY: number;
+}
+/** Active drag line state for linking an annotation to a model via drag. */
+export interface AnnotationLinkDragState {
+    annotationId: string;
+    sourceX: number;
+    sourceY: number;
+    currentX: number;
+    currentY: number;
+}
+export interface CanvasState {
+    /** Current search query for filtering/highlighting nodes. */
+    searchQuery: string;
+    /** Name of the currently selected model node, or null. */
+    selectedNode: string | null;
+    /** IDs of currently selected edges. */
+    selectedEdges: string[];
+    /** Edge ID selected for dimming (highlights endpoints, dims everything else). */
+    selectedEdge: string | null;
+    /** Whether the detail panel is open. */
+    detailPanelOpen: boolean;
+    /** Whether a delete confirmation is pending (triggered by Delete key). */
+    pendingDeleteConfirmation: boolean;
+    /** The loaded domain data from the extension host (already reconciled with manifest). */
+    domain: DisplayDomain | null;
+    /** React Flow nodes (local state for selection/drag). */
+    nodes: (ModelFlowNode | AnnotationFlowNode)[];
+    /** React Flow edges. */
+    edges: (FkFlowEdge | AnnotationFlowEdge)[];
+    /** Annotation currently being edited (auto-focus textarea), or null. */
+    editingAnnotationId: string | null;
+    /** Models available to add from logical-models/ and manifest. */
+    existingModels: ExistingModelPreview[];
+    /** Context menu state (position and target), or null if closed. */
+    contextMenu: ContextMenuState;
+    /** Whether the legend panel is visible. */
+    legendOpen: boolean;
+    /** Active drag line state for creating relationships via column drag. */
+    dragLineState: DragLineState | null;
+    /** Active drag line state for linking an annotation to a model via drag. */
+    annotationLinkDrag: AnnotationLinkDragState | null;
+    /** Set of "modelName:columnName" keys for columns involved in selected edges. */
+    highlightedColumns: Set<string>;
+    /** Set of model IDs with columns expanded. */
+    expandedNodes: Set<string>;
+    /** Whether columns are in global "all expanded" mode. */
+    allExpanded: boolean;
+    /** Selected column names in the DetailPanel (scoped to current model). */
+    selectedColumns: string[];
+    /** Anchor column for Shift+click range selection. */
+    lastSelectedColumn: string | null;
+    /** Column currently in edit mode (name field), or null. */
+    editingColumn: string | null;
+    /** Currently selected annotation ID, or null. */
+    selectedAnnotation: string | null;
+}
+export interface CanvasActions {
+    setSearchQuery: (query: string) => void;
+    selectNode: (nodeName: string | null) => void;
+    setSelectedEdges: (edgeIds: string[]) => void;
+    setSelectedEdge: (edgeId: string | null) => void;
+    setDetailPanelOpen: (open: boolean) => void;
+    /** Set pending delete confirmation state (triggered by Delete key). */
+    setPendingDeleteConfirmation: (pending: boolean) => void;
+    setDomain: (domain: DisplayDomain) => void;
+    setNodes: (nodes: (ModelFlowNode | AnnotationFlowNode)[]) => void;
+    setEdges: (edges: (FkFlowEdge | AnnotationFlowEdge)[]) => void;
+    /** Set the annotation currently being edited (auto-focus). */
+    setEditingAnnotationId: (id: string | null) => void;
+    setExistingModels: (models: ExistingModelPreview[]) => void;
+    /** Open context menu for an edge at the given position. */
+    openEdgeContextMenu: (x: number, y: number, data: FkEdgeData) => void;
+    /** Open context menu for a node at the given position. */
+    openNodeContextMenu: (x: number, y: number, modelName: string) => void;
+    /** Open context menu for an annotation at the given position. */
+    openAnnotationContextMenu: (x: number, y: number, annotationId: string) => void;
+    /** Close the context menu. */
+    closeContextMenu: () => void;
+    /** Toggle the legend panel visibility. */
+    setLegendOpen: (open: boolean) => void;
+    /** Start drag line for column relationship creation. */
+    startDragLine: (modelName: string, columnName: string, sourceX: number, sourceY: number) => void;
+    /** Update drag line endpoint as mouse moves. */
+    updateDragLineMouse: (mouseX: number, mouseY: number) => void;
+    /** End drag line (on drop or cancel). */
+    endDragLine: () => void;
+    /** Start drag line for annotation-to-model linking. */
+    startAnnotationLinkDrag: (annotationId: string, sourceX: number, sourceY: number) => void;
+    /** Update annotation link drag endpoint. */
+    updateAnnotationLinkDrag: (mouseX: number, mouseY: number) => void;
+    /** End annotation link drag. */
+    endAnnotationLinkDrag: () => void;
+    /** Set highlighted columns (for edge click). */
+    setHighlightedColumns: (columns: Set<string>) => void;
+    /** Expand all listed model IDs (sets allExpanded mode). */
+    expandAll: (modelIds: string[]) => void;
+    /** Expand only new model IDs without resetting existing state. */
+    expandNew: (modelIds: string[]) => void;
+    /** Collapse all models. */
+    collapseAll: () => void;
+    /** Toggle expand/collapse for a single model. */
+    toggleExpansion: (modelId: string) => void;
+    /** Restore expansion state from persisted data. */
+    setExpandedNodes: (nodes: string[], allExpanded: boolean) => void;
+    /** Select a single column (replaces selection, sets anchor). */
+    selectColumn: (name: string) => void;
+    /** Toggle a column in/out of the selection (Ctrl+click). */
+    toggleColumnSelection: (name: string) => void;
+    /** Select a range of columns from anchor to target (Shift+click). */
+    selectColumnRange: (name: string, allNames: string[]) => void;
+    /** Clear all column selection. */
+    clearColumnSelection: () => void;
+    /** Set the column currently being edited (F2 / double-click). */
+    setEditingColumn: (name: string | null) => void;
+    /** Select an annotation (clears model selection). */
+    selectAnnotation: (annotationId: string | null) => void;
+}
+export type CanvasStore = CanvasState & CanvasActions;
+export type CanvasStoreApi = StoreApi<CanvasStore>;
+export type CanvasSet = CanvasStoreApi['setState'];
+/**
+ * The canvas state defaults and actions. A host that keeps more state spreads
+ * this into its own zustand initialiser and adds its fields and actions after
+ * it (overriding any action it needs to extend, such as `setDomain`).
+ */
+export declare function createCanvasSlice(set: CanvasSet): CanvasStore;
+/** A standalone store holding just the canvas slice, optionally seeded. */
+export declare function createCanvasStore(initial?: Partial<CanvasState>): CanvasStoreApi;
+/** Supplies the store that canvas components below it read and write. */
+export declare function CanvasStoreProvider({ store, children }: {
+    store: CanvasStoreApi;
+    children: ReactNode;
+}): JSX.Element;
+/** The store supplied by the nearest `CanvasStoreProvider`, for `getState()` in handlers. */
+export declare function useEditorStoreApi(): CanvasStoreApi;
+/** Select a value from the nearest canvas store; re-renders when it changes. */
+export declare function useEditorStore<T>(selector: (s: CanvasStore) => T): T;

package/dist/types/store.d.ts

@@ -0,0 +1,2 @@
+export { createCanvasSlice, createCanvasStore, CanvasStoreProvider, useEditorStoreApi, useEditorStore, } from './store/editorStore.js';
+export type { EdgeContextMenu, NodeContextMenu, AnnotationContextMenu, ContextMenuState, DragLineState, AnnotationLinkDragState, CanvasState, CanvasActions, CanvasStore, CanvasStoreApi, CanvasSet, } from './store/editorStore.js';

package/dist/types/types/graph.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Types for React Flow graph nodes and edges.
+ *
+ * These types define the data payloads for custom React Flow node and edge
+ * components. The graph transformer converts DisplayDomain data into
+ * these shapes.
+ */
+import type { Node, Edge } from '@xyflow/react';
+import type { AnnotationColor, Cardinality, Layer, ModelRole, Stage } from '@erd-studio/core';
+import type { LayerConfig } from '@erd-studio/core';
+import type { ModelDiscrepancy } from '@erd-studio/core';
+import type { PhysicalProvenance } from '@erd-studio/core';
+/** Column data enriched with PK/FK/NK indicators for display in ModelNode. */
+export interface ColumnDisplay {
+    name: string;
+    dataType: string;
+    /** Column description (optional — shown in tooltip on hover). */
+    description?: string;
+    isPrimaryKey: boolean;
+    /** True if this column is the source of an FK relationship. */
+    isForeignKey: boolean;
+    /** True if this column is a natural key (business identifier). */
+    isNaturalKey: boolean;
+    /** SCD type for dimension columns (0 = never changes, 1 = overwrite, 2 = track history). */
+    scdType?: 0 | 1 | 2;
+    /** Additive type for fact measure columns. */
+    additiveType?: 'additive' | 'semi-additive' | 'non-additive';
+}
+/** Data payload for a ModelNode React Flow node. */
+export type ModelNodeData = {
+    /** Model name (unique within a domain). */
+    modelName: string;
+    /** The active design stage. */
+    stage: Stage;
+    /** Data warehouse layer. */
+    layer: Layer;
+    /** Database schema the model materializes in (shown as badge text). */
+    schema?: string;
+    /** Layer configuration for dynamic badge styling (color, abbreviation). */
+    layerConfig?: LayerConfig;
+    /** Columns to display, enriched with PK/FK flags. */
+    columns: ColumnDisplay[];
+    /** Whether the node is dimmed (doesn't match current search query). */
+    dimmed?: boolean;
+    /**
+     * Whether columns are expanded.
+     * When false, only first N columns are shown with node-level handles only.
+     * Ephemeral state — not persisted, resets on domain refresh.
+     */
+    isExpanded?: boolean;
+    /** Callback to toggle expansion state. Receives model name as argument. */
+    onToggleExpansion?: (modelName: string) => void;
+    /** Whether this model has design rationale metadata. */
+    hasRationale?: boolean;
+    /** Grain statement — "One row per ___". Shown as subtitle on node. */
+    grain?: string;
+    /** Model's role in the data warehouse architecture. Shown as badge on node. */
+    modelRole?: ModelRole;
+    /** Whether this stage is read-only (physical). */
+    readOnly?: boolean;
+    /**
+     * Render this node as a ghost. Set from two unrelated places: a physical
+     * model that does not exist in the dbt project, and a model the active
+     * discrepancy report reports 'missing' (which also fires on the logical
+     * canvas). `ghostReason` is what tells them apart.
+     */
+    isGhost?: boolean;
+    /**
+     * Why the node is a ghost — drives the border treatment and the tooltip.
+     * 'not-in-project' / 'disabled' come from the physical stage;
+     * 'missing-in-comparison' from the discrepancy overlay.
+     */
+    ghostReason?: 'not-in-project' | 'disabled' | 'missing-in-comparison';
+    /**
+     * Where the physical model's columns and types came from. Physical stage
+     * only — logical nodes never carry it, which is what keeps the header chip
+     * off the logical canvas without a stage check.
+     */
+    provenance?: PhysicalProvenance;
+    /** Whether this model is in stub display mode (PK/NK columns only). */
+    isStub: boolean;
+    /** Per-model discrepancy data when a cross-stage comparison report is active. */
+    discrepancy?: ModelDiscrepancy;
+    /** The stage currently being viewed (set when discrepancy overlay is active). */
+    discrepancySourceStage?: Stage;
+    /** The stage being compared against (set when discrepancy overlay is active). */
+    discrepancyTargetStage?: Stage;
+    /**
+     * Index signature required by React Flow's Node generic.
+     *
+     * It also means an unknown or misspelled key type-checks, and a field written
+     * here but never destructured in ModelNode ships as dead payload — which is
+     * exactly how `hasRationale` and `modelRole` gained matching dead CSS. Add a
+     * field here only together with the code that reads it.
+     */
+    [key: string]: unknown;
+};
+/** Typed React Flow node for a semantic model. */
+export type ModelFlowNode = Node<ModelNodeData, 'model'>;
+/** Data payload for an FkEdge React Flow edge. */
+export type FkEdgeData = {
+    fromModel: string;
+    fromColumn: string;
+    toModel: string;
+    toColumn: string;
+    cardinality: Cardinality;
+    /** Stage of the owning domain canvas — drives CSS colour class. */
+    stage?: Stage;
+    /** Discrepancy status for ghost/extra/mismatch edges. */
+    discrepancyStatus?: 'extra' | 'missing' | 'cardinality-mismatch';
+    /** Whether the edge is dimmed (not connected to current selection). */
+    dimmed?: boolean;
+    /** Whether the edge is in a read-only context (physical stage). */
+    readOnly?: boolean;
+    /** True when source === target — renders a loop arc over the top-right corner. */
+    isSelfLoop?: boolean;
+    /** Index signature required by React Flow's Edge generic. */
+    [key: string]: unknown;
+};
+/** Typed React Flow edge for a semantic FK relationship. */
+export type FkFlowEdge = Edge<FkEdgeData, 'fk'>;
+/** Data payload for an AnnotationNode React Flow node. */
+export type AnnotationNodeData = {
+    annotationId: string;
+    text: string;
+    color: AnnotationColor;
+    width?: number;
+    height?: number;
+    linkedModel?: string;
+    /** Whether this annotation is in a read-only context (physical stage). */
+    readOnly?: boolean;
+    /** Index signature required by React Flow's Node generic. */
+    [key: string]: unknown;
+};
+/** Typed React Flow node for a canvas annotation. */
+export type AnnotationFlowNode = Node<AnnotationNodeData, 'annotation'>;
+/** Data payload for the dashed edge linking an annotation to a model. */
+export type AnnotationEdgeData = {
+    annotationId: string;
+    targetModel: string;
+    /** Index signature required by React Flow's Edge generic. */
+    [key: string]: unknown;
+};
+/** Typed React Flow edge for an annotation-to-model link. */
+export type AnnotationFlowEdge = Edge<AnnotationEdgeData, 'annotationLink'>;

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@erd-studio/renderer",
+  "version": "0.1.0",
+  "description": "ERD Studio's React Flow canvas: the entity-relationship diagram renderer shared by the VS Code extension, with a read-only viewer mode.",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liam-machine/erd-studio",
+    "directory": "packages/renderer"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./editor": {
+      "types": "./dist/types/editor.d.ts",
+      "default": "./dist/editor.js"
+    },
+    "./store": {
+      "types": "./dist/types/store.d.ts",
+      "default": "./dist/store.js"
+    },
+    "./sizing": {
+      "types": "./dist/types/sizing.d.ts",
+      "default": "./dist/sizing.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node build.mjs && tsc -p tsconfig.build.json && node scripts/dts-extensions.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@erd-studio/core": "0.1.0",
+    "zustand": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@xyflow/react": "^12.4.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@xyflow/react": "^12.4.0",
+    "esbuild": "^0.24.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}