@erd-studio/renderer 0.3.0 → 0.4.0

package/dist/types/lib/edgeRouting/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Edge routing — shared types.
+ *
+ * Every FK line on the canvas is routed in one pass over the whole graph
+ * (`routeAll`), so the router can see every table (obstacles) and every other
+ * line (crossings, shared channels). An `FkEdge` reads its routed path from
+ * the canvas store and falls back to the smooth-step path when there is none.
+ *
+ * Coordinates are React Flow flow coordinates (the same space as node
+ * `positionAbsolute`).
+ */
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A node's box on the canvas. Tables and sticky notes are both obstacles. */
+export interface Rect {
+    id: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** 'model' for a table card, 'annotation' for a sticky note. */
+    kind: 'model' | 'annotation';
+}
+/** Where a line meets a table: the point on the card's border and which side. */
+export interface Anchor extends Point {
+    side: Side;
+}
+/** How far (px) the drawn line stops short of the card, leaving room for the `*` / `1`. */
+export declare const PATH_GAP = 20;
+/** How far (px) from the card border the `*` / `1` label sits. */
+export declare const LABEL_OFFSET = 8;
+/** One FK line to route, as the graph transformer + edge distribution placed it. */
+export interface EdgeSpec {
+    id: string;
+    source: string;
+    target: string;
+    /** The current (smooth-step) anchors: handle side + distributed slot. */
+    sourceAnchor: Anchor;
+    targetAnchor: Anchor;
+    isSelfLoop: boolean;
+    loopIndex: number;
+    /** 'many-to-one' | 'one-to-one' | 'one-to-many' | 'many-to-many'. */
+    cardinality: string;
+}
+export interface RoutingInput {
+    obstacles: Rect[];
+    edges: EdgeSpec[];
+}
+/**
+ * A router's answer for one line. `points` is an orthogonal-or-not polyline
+ * from the source stub to the target stub (each stub is the anchor pushed
+ * out by PATH_GAP along its side); the first and last segments should leave
+ * / enter perpendicular to the side. A router may move the anchors (choose
+ * another side or slot); the `*` / `1` labels follow the anchors.
+ */
+export interface RoutedLine {
+    sourceAnchor: Anchor;
+    targetAnchor: Anchor;
+    points: Point[];
+}
+/** What the canvas draws for one line, after crossings and tunnels are worked out. */
+export interface RoutedEdge extends RoutedLine {
+    /** The SVG path. */
+    d: string;
+    /** Midpoint along the drawn path (role label, swap button, badges). */
+    mid: Point;
+    /** Draw a background-coloured casing under the line (crossings = 'halo'). */
+    halo?: boolean;
+    /**
+     * crossings = 'halo', on a line that passes under another: `d` with the
+     * breaks cut out. FkEdge draws the visible stroke and its casing with it;
+     * `d` stays whole for the moving arrows and the hit area.
+     */
+    strokeD?: string;
+    /**
+     * Stretches of the line that pass under a table card (not its own two
+     * ends): polylines, drawn above the cards as a faint "x-ray" dashed line.
+     */
+    tunnels?: Point[][];
+}
+export type CrossingMode = 'none'
+/** A small semicircle bridge where one line hops over another. */
+ | 'hops'
+/** Every line has a canvas-coloured casing, and the line underneath is cut where it passes under another. */
+ | 'halo';
+export type UnderTablesMode = 
+/** The card hides the line. */
+'hidden'
+/** The hidden stretch is drawn faintly over the card, with portal rings where it enters and leaves. */
+ | 'xray';
+export type CornerMode = 'rounded' | 'curved' | 'sharp';
+/** How the router's polylines are drawn: one line style's settings. */
+export interface LineStyleOptions {
+    crossings: CrossingMode;
+    underTables: UnderTablesMode;
+    corners: CornerMode;
+}
+/** What `routeAll` needs of a router (the route-around router is the one the canvas uses). */
+export interface LineRouter {
+    route(input: RoutingInput): {
+        lines: Map<string, RoutedLine>;
+    };
+    /** Drop anything kept from earlier passes. */
+    reset(): void;
+}
+export interface RouteResult {
+    edges: Map<string, RoutedEdge>;
+    /** How long the pass took (ms), for the performance guard. */
+    millis: number;
+}

package/dist/types/lib/edgeRouting/worker/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Starts a canvas's line-routing worker, or says it cannot (returns null) so
+ * the canvas routes on the main thread with a lower cap instead.
+ *
+ * The worker's code is inlined at build time as `__ERD_EDGE_ROUTING_WORKER__`
+ * (the extension's `esbuild.js` and the package's `build.mjs` both define
+ * it). Where it is not defined (unit tests, a consumer bundling the source
+ * itself), where `Worker` or blob URLs are missing, or where the page's CSP
+ * refuses a blob worker, there is no worker.
+ */
+import type { WorkerRouteRequest, WorkerRouteResult } from './protocol.js';
+export interface RoutingWorkerEvents {
+    onResult: (result: WorkerRouteResult) => void;
+    /** The worker failed to start or crashed: it is terminated and never answers again. */
+    onFailure: (err: unknown) => void;
+}
+export interface RoutingWorkerHandle {
+    post: (request: WorkerRouteRequest) => void;
+    terminate: () => void;
+}
+/** Starts a worker for one canvas. */
+export type RoutingWorkerFactory = (events: RoutingWorkerEvents) => RoutingWorkerHandle | null;
+export declare const createRoutingWorker: RoutingWorkerFactory;

package/dist/types/lib/edgeRouting/worker/entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/lib/edgeRouting/worker/protocol.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Messages between a canvas and its line-routing worker (`worker/entry.ts`).
+ * Everything here is structured-clone safe: plain objects, arrays and Maps.
+ */
+import type { LineStyle } from '../lineStyle.js';
+import type { RoutedEdge, RoutingInput } from '../types.js';
+/** Route `input` in `style`. `seq` comes back on the answer, so a canvas can drop a stale one. */
+export interface WorkerRouteRequest {
+    type: 'route';
+    seq: number;
+    input: RoutingInput;
+    style: LineStyle;
+    zoom: number;
+}
+/** The worker's answer to one request. */
+export interface WorkerRouteResult {
+    seq: number;
+    edges: Map<string, RoutedEdge>;
+    /** How long the pass took in the worker. */
+    millis: number;
+    /** A router or renderer error in this pass (the routes then leave those lines out). */
+    error?: string;
+}

package/dist/types/lib/hoverIntent.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hover intent — decides when a pointer resting on a table becomes a hover
+ * focus, so skimming across the canvas does not flash every table it crosses.
+ *
+ *   - From nothing to a table: wait `HOVER_ENTER_DELAY_MS`.
+ *   - From table A to table B: wait `HOVER_SWITCH_DELAY_MS`, then commit B
+ *     directly (never null in between, so nothing un-dims and re-dims).
+ *   - Leaving: wait `HOVER_LEAVE_GRACE_MS` before clearing; entering again,
+ *     or `hold()` (the pointer is on one of the focus's bright lines), cancels
+ *     the clear.
+ *
+ * `cancelEnter()` drops only a pending enter; a pending clear still runs, so
+ * a pointer that has left a table never leaves its focus behind.
+ *
+ * An enter is ignored while a mouse button is held (`buttons !== 0`), while
+ * `isSuppressed()` says so (it is asked again when the timer fires), or when
+ * the table is already the focus. At most two timers exist at a time.
+ *
+ * Framework-free; timers are injected so tests can use fake ones.
+ */
+export declare const HOVER_ENTER_DELAY_MS = 120;
+export declare const HOVER_SWITCH_DELAY_MS = 60;
+export declare const HOVER_LEAVE_GRACE_MS = 150;
+type TimerId = ReturnType<typeof setTimeout>;
+export interface HoverIntentOptions {
+    /** Make `id` the focus, or clear it with null. */
+    commit: (id: string | null) => void;
+    /** The id currently in focus (read at event time). */
+    current: () => string | null;
+    /** True while hover must not start a focus (drags, menus, pans). */
+    isSuppressed: () => boolean;
+    setTimeout?: (fn: () => void, ms: number) => TimerId;
+    clearTimeout?: (id: TimerId) => void;
+}
+export interface HoverIntent {
+    enter(id: string, buttons: number): void;
+    leave(): void;
+    hold(): void;
+    cancelEnter(): void;
+    cancelPending(): void;
+    dispose(): void;
+}
+export declare function createHoverIntent(options: HoverIntentOptions): HoverIntent;
+export {};

package/dist/types/lib/layerCues.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Layer cues: how the canvas names the layer a table lives in.
+ *
+ * A table's header badge has one meaning, its layer, and the layer is named
+ * the same way wherever the canvas names one (the node badge, the toolbar
+ * chip, the status-bar key): the layer's abbreviation, then its label.
+ *
+ * A project with a single layer has nothing to tell apart, so the per-table
+ * badge, its colour strip, the status-bar key and the toolbar chip are left
+ * off there ({@link isSingleLayerProject}).
+ */
+import type { DisplaySubjectArea, LayerConfig } from '@erd-studio/core';
+/** Abbreviations for the default layers, for when a layer has no config. */
+export declare const LAYER_BADGE_FALLBACK: Readonly<Record<string, string>>;
+/**
+ * A layer's badge text: its configured abbreviation, else the default
+ * layers' abbreviation, else the first three letters of its id.
+ */
+export declare function layerAbbreviation(id: string, config?: Pick<LayerConfig, 'abbreviation'>): string;
+/**
+ * Whether the project has one layer at most, with every table on the diagram
+ * in the diagram's layer: the layer badge, strip, key and chip are then left
+ * off. Needs `layerConfigs`: a domain from an older core (or a host that
+ * sends no layer list) keeps every layer cue, as it did before.
+ */
+export declare function isSingleLayerProject(domain: Pick<DisplaySubjectArea, 'layer' | 'layerConfigs' | 'models'>): boolean;

package/dist/types/lib/nodeOverlays.d.ts

@@ -14,6 +14,12 @@
  * This lets selection / search / expansion changes avoid re-running the full
  * domain transform (which would also drop `measured` and force React Flow to
  * re-measure every node).
+ *
+ * What counts as "connected" is `computeCanvasFocus` (`canvasFocus.ts`), the
+ * same rule the hover preview uses. Hover itself never comes through here:
+ * every `setEdges` re-renders every `FkEdge`, which is fine once per click but
+ * not on every pointer move, so hover dims with a root CSS class instead
+ * (`useHoverFocus`).
  */
 import type { TableFlowNode, FkFlowEdge, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
 export type GraphNode = TableFlowNode | AnnotationFlowNode;

package/dist/types/lib/nodeSizing.d.ts

@@ -47,4 +47,4 @@ export declare function resolveNodeDimensions(node: Pick<TableFlowNode, 'data' |
  * slightly more space than the minimum estimate, preventing overlap
  * when font rendering or badge widths differ from the approximation.
  */
-export declare function estimateNodeWidth(data: Pick<TableNodeData, 'modelName' | 'label' | 'columns' | 'provenance'>): number;
+export declare function estimateNodeWidth(data: Pick<TableNodeData, 'modelName' | 'label' | 'columns' | 'provenance'> & Partial<Pick<TableNodeData, 'tableLayer' | 'shownSchema' | 'alias' | 'singleLayer'>>): number;

package/dist/types/lib/pathGeometry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Path geometry for the relationship flow glyphs: how long a drawn edge path
+ * is, where its straight runs are, and the point and heading at a fraction
+ * of its length.
+ *
+ * Reads the absolute commands the canvas draws: `M`, `L`, `H`, `V` (xyflow's
+ * smooth-step path and the Legend samples), `Q` (smooth-step bends) and `C`
+ * (self-loops). Curves are flattened into a few chords, which is accurate to
+ * well under a pixel for the radii used here. Anything else ends the parse;
+ * what was read so far is kept.
+ *
+ * Pure: no React, no DOM (`SVGPathElement.getTotalLength` would need a
+ * mounted element and a layout).
+ */
+export interface PathPoint {
+    x: number;
+    y: number;
+}
+export interface PathPose extends PathPoint {
+    /** Heading in degrees, along increasing path length (SVG `rotate="auto"`). */
+    angle: number;
+}
+export interface PathGeometry {
+    /** The flattened path. */
+    readonly points: readonly PathPoint[];
+    /** Cumulative length at each point (`cumulative[0] === 0`). */
+    readonly cumulative: readonly number[];
+    readonly length: number;
+    /** Straight runs (`L` / `H` / `V`) as fractions of the length, in path order. */
+    readonly straights: readonly {
+        start: number;
+        end: number;
+    }[];
+}
+/** Flatten and measure a path. An unreadable path has length 0. */
+export declare function measurePath(d: string): PathGeometry;
+/** The point and heading at `fraction` (0..1) of the path's length. */
+export declare function poseAt(geom: PathGeometry, fraction: number): PathPose;
+/**
+ * Where two still glyphs sit so that neither lands on a bend: the middle of
+ * the first and of the last usable straight run, or a third and two thirds
+ * of the only one. Null when the path has no usable straight run (a
+ * self-loop's curve): the planner's defaults then apply.
+ */
+export declare function stillPositions(geom: PathGeometry): readonly [number, number] | null;

package/dist/types/lib/reuseUnchanged.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Structural sharing for a rebuilt graph: every rebuilt node or edge that is
+ * structurally equal to the one already in the store is replaced by that
+ * same object.
+ *
+ * The canvas rebuilds every node and edge whenever the domain changes —
+ * including the optimistic update after a drag, where only the moved
+ * tables' positions (and the sides of their edges) differ. React Flow reuses
+ * its internal node for a user node that is the same object as last time,
+ * and memoised node and edge components skip rendering when their props keep
+ * their identity, so handing back the old objects for everything that did
+ * not change turns a 500-table re-render into a handful.
+ *
+ * Correct by construction: the result is equal, field for field, to what the
+ * rebuild produced; only identities change. Transient React Flow fields that
+ * the rebuild never sets (`dragging`, `resizing`) are ignored, and an absent
+ * `selected` equals `false`.
+ */
+/** Structural equality of plain data: functions, Maps, Sets and class instances compare by identity. */
+export declare function sameData(a: unknown, b: unknown): boolean;
+/**
+ * `next` with each element replaced by the element of `prev` with the same
+ * id when the two are structurally equal. Returns `prev` itself when every
+ * element was reused in the same order (nothing to set at all).
+ */
+export declare function reuseUnchanged<T extends {
+    id: string;
+}>(prev: readonly T[], next: T[]): T[];

package/dist/types/lib/roleOptions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The words the canvas shows for each table role. The stored keys
+ * (`gold-fact`, …) never change; only the labels are for people. The order is
+ * core's `TABLE_ROLE_VALUES` (the role field's choices).
+ */
+import type { TableRole } from '@erd-studio/core';
+/** Human-readable labels for each role (the stored key stays as it is). */
+export declare const ROLE_OPTIONS: ReadonlyArray<{
+    value: TableRole;
+    label: string;
+}>;
+/** The label for a role key, or the key itself for a role this renderer does not know. */
+export declare function roleLabel(role: string): string;

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

@@ -14,8 +14,11 @@
  */
 import { type ReactNode } from 'react';
 import { type StoreApi } from 'zustand';
-import type { DisplaySubjectArea, ExistingTablePreview } from '@erd-studio/core';
+import type { CanvasContext, DisplaySubjectArea, ExistingTablePreview } from '@erd-studio/core';
 import type { TableFlowNode, FkFlowEdge, FkEdgeData, AnnotationFlowNode, AnnotationFlowEdge } from '../types/graph.js';
+import { type CanvasFocus } from '../lib/canvasFocus.js';
+import type { RoutedEdge } from '../lib/edgeRouting/types.js';
+import { type LineStyle } from '../lib/edgeRouting/lineStyle.js';
 /** Context menu state for edge right-click. */
 export interface EdgeContextMenu {
     type: 'edge';
@@ -101,6 +104,44 @@ export interface CanvasState {
     editingColumn: string | null;
     /** Currently selected annotation ID, or null. */
     selectedAnnotation: string | null;
+    /**
+     * Hover preview focus: the table the pointer rests on, its related tables
+     * and lines (`useHoverFocus`). Ephemeral UI state: never persisted, never
+     * posted to the host, never written to a file.
+     */
+    hoverFocus: CanvasFocus | null;
+    /**
+     * What carries the moving relationship arrows: `hoverFocus`, else the
+     * focus of the clicked table or line. Ephemeral, like `hoverFocus`.
+     */
+    flowFocus: CanvasFocus | null;
+    /**
+     * The project has no dbt project, so there is one stage only: the canvas
+     * drops the stage colours (`editor-canvas--neutral`) and the legend its
+     * Physical, ghost and comparison entries. Default false, today's look. The
+     * extension's store sets it from the host's `logicalOnly` flag; ErdCanvas
+     * from its `logicalOnly` prop.
+     */
+    logicalOnly: boolean;
+    /**
+     * What the editing host knows beyond the diagram (`CanvasContext`): each
+     * table's file, its relationships to tables not on the diagram, who reviews
+     * it. Logical stage only. Null by default and in the viewer, which never
+     * gets one: then the detail panel has no File line or "Not on this
+     * diagram" list and no node shows a "+n" chip.
+     */
+    canvasContext: CanvasContext | null;
+    /**
+     * How FK lines are drawn (`curved` or `hops`), a reader's view preference.
+     * The extension's store sets it from the host's `lineStyle` message (the
+     * `erdStudio.canvas.lineStyle` setting); ErdCanvas from its `lineStyle` prop.
+     */
+    lineStyle: LineStyle;
+    /**
+     * The routed FK lines by edge id, from `EdgeRouter`'s last pass. Null (or
+     * a line missing from it) means `FkEdge` draws its smooth-step fallback.
+     */
+    edgeRoutes: Map<string, RoutedEdge> | null;
 }
 export interface CanvasActions {
     setSearchQuery: (query: string) => void;
@@ -162,6 +203,16 @@ export interface CanvasActions {
     setEditingColumn: (name: string | null) => void;
     /** Select an annotation (clears model selection). */
     selectAnnotation: (annotationId: string | null) => void;
+    /** Set the hover preview focus; a focus equal by value is not written. */
+    setHoverFocus: (focus: CanvasFocus | null) => void;
+    /** Set the flowing focus; a focus equal by value is not written. */
+    setFlowFocus: (focus: CanvasFocus | null) => void;
+    /** Store the host's canvas context, or clear it (null). */
+    setCanvasContext: (context: CanvasContext | null) => void;
+    /** Change how FK lines are drawn. */
+    setLineStyle: (lineStyle: LineStyle) => void;
+    /** Store the router's latest routes (null: every line on the fallback). */
+    setEdgeRoutes: (routes: Map<string, RoutedEdge> | null) => void;
 }
 export type CanvasStore = CanvasState & CanvasActions;
 export type CanvasStoreApi = StoreApi<CanvasStore>;
@@ -183,3 +234,9 @@ export declare function CanvasStoreProvider({ store, children }: {
 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;
+/**
+ * Like `useEditorStore`, but returns `fallback` instead of throwing when no
+ * `CanvasStoreProvider` is above. For presentation-only reads in components
+ * that are also rendered on their own (an `FkEdge` in a unit test).
+ */
+export declare function useEditorStoreOr<T>(selector: (s: CanvasStore) => T, fallback: T): T;

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

@@ -44,10 +44,29 @@ export type TableNodeData = {
     stage: Stage;
     /** Data warehouse layer. */
     layer: Layer;
-    /** Database schema the model materializes in (shown as badge text). */
+    /** Database schema the model materializes in (named in the badge's hover card). */
     schema?: string;
     /** Layer configuration for dynamic badge styling (color, abbreviation). */
     layerConfig?: LayerConfig;
+    /**
+     * The layer the table itself belongs to (`DisplayTable.layer`), when known.
+     * The header's badge always names the layer the table lives in: this one,
+     * else the diagram's `layer`. A known layer also draws the colour strip.
+     */
+    tableLayer?: Layer;
+    /** {@link tableLayer}'s config (its colour and abbreviation). */
+    tableLayerConfig?: LayerConfig;
+    /** Set when {@link tableLayer} is not the diagram's layer: a table this diagram borrows. */
+    otherLayer?: true;
+    /** The schema as a prefix of the name (`sales.fct_order`): set only when it is not the badge's layer id. */
+    shownSchema?: string;
+    /**
+     * Set when the project has one layer and every table is in it
+     * (`isSingleLayerProject`): the layer badge and colour strip are left off.
+     */
+    singleLayer?: true;
+    /** The warehouse name when it differs from the model name (`alias`), shown after it: `gold_orders  as orders`. */
+    alias?: string;
     /** Columns to display, enriched with PK/FK flags. */
     columns: ColumnDisplay[];
     /** Whether the node is dimmed (doesn't match current search query). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erd-studio/renderer",
-  "version": "0.3.0",
+  "version": "0.4.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": {
@@ -47,7 +47,7 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@erd-studio/core": "0.3.0",
+    "@erd-studio/core": "0.4.0",
     "zustand": "^5.0.0"
   },
   "peerDependencies": {