@grafloria/element 0.3.19 → 0.3.21

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

@@ -1,385 +0,0 @@
-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;