@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/instance/create-diagram.d.ts

@@ -0,0 +1,385 @@
+import { DiagramEngine, CommentStore } from '@grafloria/engine';
+import type { DiagramModel, LinkModel, LODLevel, NodeModel, ExportTextOptions, ImportTextOptions, ImportTextResult } from '@grafloria/engine';
+import type { Theme } from '../types/theme.types';
+import type { SVGRendererConfig } from '../types/renderer.interface';
+import type { Rectangle } from '../types/geometry.types';
+import type { ExportFormat, ExportOptions } from '../types/renderer.interface';
+import type { ColorMode, ThemeSet } from '../themes/color-mode';
+import type { TokenBridge } from '../themes/token-bridge';
+import type { GovernorState } from '../perf/quality-governor';
+import type { AnimationService } from '../services/animation.service';
+import type { SvgExportResult } from '../export/svg-export';
+import type { PdfExportResult } from '../export/pdf/pdf-export';
+import type { DiagramRegistry } from '../ext/diagram-registry';
+import { VNodePatcher } from '../vnode/patch';
+import { InteractionController } from '../interaction/interaction-controller';
+import { ViewportController } from '../viewport/viewport-controller';
+import type { Unsubscribe } from '../viewport/viewport-controller';
+import { RenderScheduler } from './render-scheduler';
+import type { DomEventBinderOptions } from './dom-event-binder';
+import type { EdgeSpec, NodeSpec } from './model-input';
+import type { HydrationSnapshot } from '../ssr/render-to-static';
+import type { HostCullOptions } from '../lazy/host-culling';
+import type { ViewLifecycle } from '../lazy/view-lifecycle';
+/**
+ * `createDiagram()` — the headless instance factory.
+ *
+ * Wave 3 fixed the CONTRACT (./diagram-instance.ts) and listed four blockers.
+ * All four are now closed and this is the factory they were building towards:
+ *
+ *   1. VNode → DOM materializer  → `VNodePatcher`      (wave 3)
+ *   2. DOM event binding         → `DomEventBinder`    (wave 4, this card)
+ *   3. Render scheduling         → `RenderScheduler`   (wave 4, this card)
+ *   4. Custom-node host callback → `renderCustomNode`  (wave 4, this card)
+ *
+ * Every framework wrapper in the workspace is now a thin shell over this: the
+ * React `<GrafloriaFlow>` and the `<grafloria-flow>` custom element both do nothing but
+ * (a) forward props into `setNodes`/`setEdges` and (b) turn `on(...)` events
+ * into their own render signal. There is ZERO diagram logic in either.
+ */
+/** Nodes/edges may be handed in as plain specs or as live engine models. */
+export type NodeInput = NodeSpec | NodeModel;
+export type EdgeInput = EdgeSpec | LinkModel;
+export interface DiagramEventMap {
+    'nodes:change': {
+        nodes: NodeModel[];
+    };
+    'edges:change': {
+        edges: LinkModel[];
+    };
+    'selection:change': {
+        nodes: NodeModel[];
+        edges: LinkModel[];
+    };
+    connect: {
+        link: LinkModel;
+    };
+    reconnect: {
+        link: LinkModel;
+        endpoint: 'source' | 'target';
+    };
+    'node:click': {
+        node: NodeModel;
+        world: {
+            x: number;
+            y: number;
+        };
+    };
+    'node:doubleclick': {
+        node: NodeModel;
+        world: {
+            x: number;
+            y: number;
+        };
+    };
+    'edge:click': {
+        edge: LinkModel;
+        world: {
+            x: number;
+            y: number;
+        };
+    };
+    'viewport:change': {
+        viewport: Rectangle;
+        zoom: number;
+    };
+    ready: void;
+}
+export type DiagramEventName = keyof DiagramEventMap;
+export type DiagramEventHandler<K extends DiagramEventName> = (payload: DiagramEventMap[K]) => void;
+export interface CreateDiagramOptions extends DomEventBinderOptions {
+    nodes?: NodeInput[];
+    edges?: EdgeInput[];
+    theme?: Theme;
+    /**
+     * Follow the OS colour scheme instead of pinning `theme`.
+     *
+     * `'system'` upgrades to the high-contrast theme under `prefers-contrast: more`
+     * or forced-colors, rather than flashing a light canvas at someone who asked
+     * the operating system for neither.
+     */
+    colorMode?: ColorMode;
+    /** The themes `colorMode` switches between. Defaults to `DEFAULT_THEME_SET`. */
+    themes?: ThemeSet;
+    /** Drive Grafloria's variables from the host's design tokens (shadcn/MUI/Tailwind). */
+    tokenBridge?: TokenBridge;
+    /**
+     * The full renderer config, for every knob the ergonomic fields above do not
+     * name: `connectionPoint` / `smartConnectionPoints` (floating edges),
+     * `parallelLinks` + `parallelSpacing`, `channelNudging`, `jumpOwnership`,
+     * `globalRouting`, `linkHitAreaWidth`. Every field was documented, consumed by
+     * the renderer, and settable by NOBODY — the one factory that builds a renderer
+     * for a host never passed the config on. The named fields above win over
+     * anything set here, and `instanceId` is omitted because hydration owns it.
+     */
+    renderer?: Omit<SVGRendererConfig, 'instanceId'>;
+    zoom?: number;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Camera origin in world coordinates. */
+    viewport?: {
+        x: number;
+        y: number;
+    };
+    /** Attach to an existing engine instead of creating one. */
+    engine?: DiagramEngine;
+    /** Passed through to `new DiagramEngine({ interaction })`. */
+    interaction?: Record<string, unknown>;
+    /** Force the renderer's CSS scope (hydration does this for you). */
+    instanceId?: string;
+    /** Fit the camera to the content on mount. */
+    fitView?: boolean;
+    /**
+     * Blocker #4: host hook for nodes that render as framework components rather
+     * than SVG (`custom: true` / `metadata.useHTMLLayer`). The instance creates and
+     * positions an absolutely-placed host element inside the HTML layer and hands
+     * it to you; you own what goes inside it.
+     *
+     * RETURN A PROMISE IF YOU DRAW LATER. A painter that defers — to a
+     * `requestAnimationFrame`, a `fetch`, a framework's async render, a web font — has
+     * drawn nothing by the time a synchronous export reads the host, and its widget used
+     * to come out as a marked box. Returning the promise is the SIGNAL that closes that:
+     * `await diagram.export(…)` waits for exactly the painters that said they were not
+     * done, and for nothing else — no polling and no fixed sleep. It is bounded by
+     * {@link ExportOptions.customNodeTimeout} (default 5s) so a painter that never settles
+     * cannot hang a print job, and a miss is WARNED about rather than silently blank.
+     *
+     * ```ts
+     * renderCustomNode: async (node, el) => {
+     *   const data = await fetch(`/api/widget/${node.id}`).then(r => r.json());
+     *   el.append(chartFor(data));
+     * }
+     * ```
+     *
+     * Nothing else changes: the promise is ignored by the frame loop (a widget still
+     * appears when it appears) and by `exportSvgString()` / `exportPdf()`, which are
+     * synchronous by contract and report an unfinished painter instead of waiting. A
+     * rejection is caught, reported, and never reaches the host as an unhandled rejection.
+     */
+    renderCustomNode?: (node: NodeModel, element: HTMLElement) => void | Promise<void>;
+    /** Called before a custom node's host element is removed — unmount your component. */
+    removeCustomNode?: (nodeId: string, element: HTMLElement) => void;
+    /**
+     * VIEWPORT-CULL the custom-node hosts: keep only the ones near the viewport in the
+     * document. `true` for the defaults, or an options object (`margin`, `hysteresis`,
+     * `mode` — see {@link HostCullOptions}).
+     *
+     * OFF by default, and that is not timidity. Every custom host has been permanently in
+     * the document since custom nodes existed, and embedders are entitled to have built on
+     * that: this workspace's own dashboard kit resolves a tile with
+     * `container.querySelector('.grafloria-node-host[data-node-id=…]')`, and outside it there
+     * are IntersectionObservers, React portal containers, third-party widget libraries that
+     * cache a DOM reference at mount, and analytics that count nodes. Culling removes
+     * elements from the document with no error and no visible diff, so switching it on by
+     * default would break working apps on a version bump, silently, in exchange for a
+     * performance win they did not ask for. A host with hundreds of widgets knows it has
+     * hundreds of widgets and can say so.
+     *
+     * The default MODE, once you are in, is the safe one: `'detach'` keeps the element and
+     * re-appends it on re-entry, so `renderCustomNode` still mounts exactly once and
+     * `removeCustomNode` does NOT fire on a cull.
+     *
+     * INTERACTION WITH ANYTHING THAT READS WIDGET CONTENT, stated because it is not obvious.
+     * Culling never removes a host from `nodeHosts` in `'detach'` mode, only from the
+     * document, so a consumer that walks the map (rather than querying the DOM) still sees
+     * every widget it ever saw.
+     *
+     * EXPORT IS UNAFFECTED, in either mode, and this used to be untrue. A widget the camera
+     * has never reached has never been painted and a detached one has no layout box, so an
+     * export found nothing to capture for exactly the tiles a user had not scrolled to — and
+     * this comment used to tell you to "pan or `fitView()` first", which is no answer at all
+     * for a headless print job or a server-side thumbnailer. `export()` / `exportSvgString()`
+     * / `exportPdf()` now FORCE-MATERIALIZE the hosts they need, read them, and put the
+     * document back exactly as they found it (see `materializeCustomNodes` below for what
+     * "put back" means per mode). Turning culling on cannot change what comes out of a file:
+     * it is a performance knob, and a performance knob that lost data would not be one.
+     *
+     * An ASYNC painter materialized this way is waited for by `await export(…)` — and the
+     * hosts an in-flight capture is holding are exempt from culling for exactly that long,
+     * so a frame (or an animated pan) mid-export cannot empty the widget being read.
+     */
+    cullCustomNodes?: boolean | HostCullOptions;
+    /**
+     * Install a {@link ViewLifecycle} — freeze/unfreeze, `autoFreeze`, and the admission set
+     * a {@link ProgressiveMounter} drives.
+     *
+     * The lazy subsystem has been fully built and fully tested since wave 8 and was
+     * reachable only by constructing an `SVGRenderer` by hand — which `createDiagram()`
+     * exists to stop you doing. Undefined keeps today's behaviour exactly: no gate, every
+     * entity culling admits gets a view on the frame it is admitted.
+     *
+     * Custom-node culling honours it too: an explicitly frozen node releases its HTML host.
+     */
+    viewLifecycle?: ViewLifecycle;
+    /**
+     * Adopt a server-rendered snapshot instead of mounting fresh (Card 6).
+     * Pass the `snapshot` returned by `renderToStaticSVG()`. The instance rebuilds
+     * the identical model, renders the identical VNode tree, and ADOPTS the DOM
+     * already in the container — no re-creation, no flash, no re-layout.
+     */
+    hydrate?: HydrationSnapshot;
+    /**
+     * Anchored comment threads. `true` creates a store (viewer `'local'`);
+     * pass a `CommentStore` to share one (collab). Pins render into the VNode
+     * tree via the comment overlay; read them back with `getCommentStore()`.
+     */
+    comments?: boolean | CommentStore;
+    /** Viewer id for a `comments: true`-created store (default `'local'`). */
+    commentsViewer?: string;
+}
+export interface DiagramInstance {
+    setNodes(nodes: NodeInput[]): void;
+    setEdges(edges: EdgeInput[]): void;
+    getModel(): DiagramModel;
+    getEngine(): DiagramEngine;
+    /** The comment store, when `comments` was enabled; `null` otherwise. */
+    getCommentStore(): CommentStore | null;
+    on<K extends DiagramEventName>(event: K, handler: DiagramEventHandler<K>): Unsubscribe;
+    off<K extends DiagramEventName>(event: K, handler: DiagramEventHandler<K>): void;
+    readonly viewport: ViewportController;
+    readonly interaction: InteractionController;
+    /** Theme swap (re-injects this instance's CSS variable block only). */
+    setTheme(theme: Theme): void;
+    /**
+     * Follow the OS colour scheme (`'system'`), or pin light/dark.
+     *
+     * `'system'` also honours `prefers-contrast: more` and forced-colors by
+     * upgrading to the high-contrast theme — an accessibility preference outranks
+     * an aesthetic one.
+     */
+    setColorMode(mode: ColorMode, themes?: ThemeSet): void;
+    getColorMode(): ColorMode | undefined;
+    /** Re-point Grafloria's CSS variables at the host design system's tokens. */
+    setTokenBridge(bridge: TokenBridge | null | undefined): void;
+    /**
+     * Export the CURRENT view. `'svg'` returns SVG source; `'png' | 'jpeg' |
+     * 'webp' | 'pdf'` return a `data:` URL.
+     *
+     * Pass `{ embedModel: true }` (PNG and SVG) and the diagram model rides inside
+     * the artifact — the exported file re-opens as an editable diagram.
+     *
+     * THE ASYNC ONE, and the only one. If a custom node's `renderCustomNode` returned a
+     * promise — "I draw later: a rAF, a fetch, a framework's render, a web font" — this
+     * waits for it before reading the host, bounded by
+     * {@link ExportOptions.customNodeTimeout}. The synchronous entry points below cannot,
+     * and say so in their `warnings`. Read the fidelity report through
+     * {@link ExportOptions.onWarnings}, which fires on every format.
+     */
+    export(format?: ExportFormat, options?: ExportOptions): Promise<string>;
+    /**
+     * Synchronous, DOM-free, deterministic. Carries `warnings`.
+     *
+     * Synchronous means a widget whose painter is still running is captured as it stands
+     * and REPORTED, not waited for — `await export('svg')` is the entry point that waits.
+     */
+    exportSvgString(options?: ExportOptions): SvgExportResult;
+    /** A real vector PDF: paths stay paths, text stays selectable text. */
+    exportPdf(options?: ExportOptions): PdfExportResult;
+    /** The LOD tier actually rendered, and the adaptive governor's last verdict. */
+    getQualityState(): {
+        tier: LODLevel;
+        governor?: GovernorState;
+    };
+    /** Frame all content. */
+    fitView(padding?: number): void;
+    /** Queue a repaint (coalesced into one frame). */
+    render(): void;
+    /** Repaint synchronously — use when you must measure right after a change. */
+    renderNow(): void;
+    /**
+     * wave8/dirty — Card 1: apply many mutations as ONE frame.
+     *
+     * ```ts
+     * diagram.batchUpdate((model) => {
+     *   for (const n of model.getNodes()) n.setPosition(n.position.x + 10, n.position.y);
+     * });
+     * ```
+     *
+     * Two distinct things are coalesced, and they are coalesced in two different
+     * places, which is worth being precise about:
+     *
+     *   - **Events.** `DiagramModel.beginBatch()` QUEUES its change events instead
+     *     of firing them, so a thousand `setPosition()` calls do not walk a
+     *     thousand listener chains on their way to the same rAF.
+     *   - **Frames.** `RenderScheduler` folds every `schedule()` in a tick into one
+     *     rAF callback, so the thousand mutations produce exactly one `render()`
+     *     and one `reconcile()` — one patch, not a thousand.
+     *
+     * Nesting is depth-counted (it bottoms out in `DiagramEntity`), so a batch
+     * inside a batch is still one frame. `mutate` throwing does not strand the
+     * model in batch mode.
+     *
+     * It never paints synchronously — that is the point. If you need the DOM to be
+     * correct before you measure it, follow with `renderNow()`.
+     */
+    batchUpdate(mutate: (model: DiagramModel) => void): void;
+    /**
+     * The renderer's animation service. Host policy lives here: global
+     * enable/speed, reduced-motion overrides, and the battery-saver auto-toggle
+     * (`updateConfig({ respectBatteryStatus: false })` to opt out — on by
+     * default, and on a low unplugged battery it disables edge animations).
+     */
+    animations: AnimationService;
+    /**
+     * Mermaid-compatible text export (with the lossless sidecar by default) —
+     * feed the result back to `loadText` for a full round-trip.
+     */
+    exportText(options?: ExportTextOptions): string;
+    /**
+     * Parse Mermaid-compatible text (sidecar-aware) and reconcile it INTO the
+     * live diagram through the same spec reconciler `setNodes`/`setEdges` use —
+     * listeners, plugins, and the renderer all stay attached.
+     */
+    loadText(text: string, options?: ImportTextOptions): ImportTextResult;
+    dispose(): void;
+    /**
+     * Wave 6 — Card 3: the nodes currently being dragged (past the movement
+     * threshold). Custom node components receive this as the `dragging` prop.
+     */
+    getDraggingNodeIds(): string[];
+    /**
+     * visio-depth — open the in-place label editor programmatically: a node's
+     * label (`{ type: 'node', nodeId }`) or a link label
+     * (`{ type: 'link-label', linkId, labelIndex }`). The seam a host's
+     * context-menu Rename / F2 binding uses; the same editor + undoable commit
+     * that double-click opens. `seed` replaces the text the editor opens with
+     * (type-to-replace). Returns false when the target is missing, not editable,
+     * or the instance is readonly.
+     */
+    beginLabelEdit(target: {
+        type: 'node' | 'link-label';
+        nodeId?: string;
+        linkId?: string;
+        labelIndex?: number;
+    }, opts?: {
+        seed?: string;
+    }): boolean;
+    /**
+     * THIS diagram's contribution registry — shapes, named styles, link/label
+     * templates, markers, anchors, connection points, connectors, animations.
+     *
+     * The module-level `registerShape()` / `defineStyle()` / … remain the
+     * PROCESS-WIDE registry and still work exactly as before; this one shadows it
+     * for this diagram only. That distinction is the whole reason it exists: the
+     * registries used to be module-scope `Map`s, so two diagrams on one page could
+     * not have different vocabularies, and unloading one diagram's extension
+     * restored the registry to its pre-registration state — silently stripping the
+     * shape out from under the diagram beside it.
+     *
+     * ```ts
+     * editor.registry.registerShape('badge', badgeGeometry);   // editor only
+     * preview.registry.registerShape('badge', otherGeometry);  // preview only
+     * ```
+     *
+     * Pass it to `createExtensionHost({ …, registry: diagram.registry })` and every
+     * extension that host loads contributes to this diagram alone.
+     */
+    readonly registry: DiagramRegistry;
+    /** Escape hatches for hosts and tests. */
+    readonly container: HTMLElement;
+    readonly scheduler: RenderScheduler;
+    readonly patcher: VNodePatcher;
+}
+export declare function createDiagram(container: HTMLElement, options?: CreateDiagramOptions): DiagramInstance;
+/** World bounding box of every visible node, or null when there is nothing to fit. */
+export declare function contentBounds(model: DiagramModel): Rectangle | null;