@grafloria/element 0.3.18 → 0.3.20

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

@@ -0,0 +1,48 @@
+/**
+ * ============================================================================
+ * The headless instance contract — NOW IMPLEMENTED
+ * ============================================================================
+ *
+ * Wave 3 declared this contract as types-only and listed four blockers before a
+ * real `createDiagram()` could ship. Wave 4 (framework-integration card) closed
+ * all four, so the contract and its implementation are the same thing and live
+ * together in `./create-diagram.ts`. This file is kept as the map:
+ *
+ *   1. **VNode → DOM materializer.** ✅ `VNodePatcher` (`../vnode/patch.ts`) —
+ *      keyed reconciler, `foreignObject` subtrees opaque. *(wave 3)*
+ *      Wave 4 added `hydrate()`: adopt server DOM without touching it.
+ *
+ *   2. **DOM event binding + handler orchestration.** ✅ `DomEventBinder`
+ *      (`./dom-event-binder.ts`) — the mousedown priority ladder (port →
+ *      control-point → waypoint → endpoint → label → link → node → empty),
+ *      pan/zoom, threshold-gated node dragging, keyboard. It was the largest
+ *      remaining piece and it is now framework-free.
+ *
+ *   3. **Render scheduling.** ✅ `RenderScheduler` (`./render-scheduler.ts`) —
+ *      rAF coalescing + the idle-skip keyed on dirty entities + viewport/zoom.
+ *
+ *   4. **Custom / HTML-layer nodes.** ✅ `renderCustomNode(node, element)` on
+ *      `CreateDiagramOptions`. The instance owns an absolutely-positioned host
+ *      element per custom node inside the HTML layer; the framework owns what
+ *      goes inside it (a React portal, a slotted `<template>`, an Angular
+ *      component). Custom nodes are no longer Angular-only.
+ *
+ * Usage — identical from React, Vue, Svelte, a web component or a `<script>` tag:
+ *
+ * ```ts
+ * const diagram = createDiagram(document.getElementById('canvas')!, {
+ *   nodes, edges, theme: LIGHT_THEME,
+ * });
+ * const off = diagram.on('selection:change', ({ nodes }) => console.log(nodes));
+ * diagram.setNodes(nextNodes);
+ * diagram.dispose();
+ * ```
+ *
+ * SSR (Card 6): call `renderToStaticSVG()` on the server and pass the returned
+ * `snapshot` to `createDiagram(el, { hydrate: snapshot })` on the client — the
+ * server DOM is adopted, not rebuilt.
+ */
+export { createDiagram, contentBounds } from './create-diagram';
+export type { DiagramInstance, CreateDiagramOptions, DiagramEventMap, DiagramEventName, DiagramEventHandler, NodeInput, EdgeInput, } from './create-diagram';
+/** The factory's own signature, for hosts that store it. */
+export type CreateDiagram = typeof import('./create-diagram').createDiagram;

package/src/libs/renderer/src/instance/diagram-instance.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * ============================================================================
+ * The headless instance contract — NOW IMPLEMENTED
+ * ============================================================================
+ *
+ * Wave 3 declared this contract as types-only and listed four blockers before a
+ * real `createDiagram()` could ship. Wave 4 (framework-integration card) closed
+ * all four, so the contract and its implementation are the same thing and live
+ * together in `./create-diagram.ts`. This file is kept as the map:
+ *
+ *   1. **VNode → DOM materializer.** ✅ `VNodePatcher` (`../vnode/patch.ts`) —
+ *      keyed reconciler, `foreignObject` subtrees opaque. *(wave 3)*
+ *      Wave 4 added `hydrate()`: adopt server DOM without touching it.
+ *
+ *   2. **DOM event binding + handler orchestration.** ✅ `DomEventBinder`
+ *      (`./dom-event-binder.ts`) — the mousedown priority ladder (port →
+ *      control-point → waypoint → endpoint → label → link → node → empty),
+ *      pan/zoom, threshold-gated node dragging, keyboard. It was the largest
+ *      remaining piece and it is now framework-free.
+ *
+ *   3. **Render scheduling.** ✅ `RenderScheduler` (`./render-scheduler.ts`) —
+ *      rAF coalescing + the idle-skip keyed on dirty entities + viewport/zoom.
+ *
+ *   4. **Custom / HTML-layer nodes.** ✅ `renderCustomNode(node, element)` on
+ *      `CreateDiagramOptions`. The instance owns an absolutely-positioned host
+ *      element per custom node inside the HTML layer; the framework owns what
+ *      goes inside it (a React portal, a slotted `<template>`, an Angular
+ *      component). Custom nodes are no longer Angular-only.
+ *
+ * Usage — identical from React, Vue, Svelte, a web component or a `<script>` tag:
+ *
+ * ```ts
+ * const diagram = createDiagram(document.getElementById('canvas')!, {
+ *   nodes, edges, theme: LIGHT_THEME,
+ * });
+ * const off = diagram.on('selection:change', ({ nodes }) => console.log(nodes));
+ * diagram.setNodes(nextNodes);
+ * diagram.dispose();
+ * ```
+ *
+ * SSR (Card 6): call `renderToStaticSVG()` on the server and pass the returned
+ * `snapshot` to `createDiagram(el, { hydrate: snapshot })` on the client — the
+ * server DOM is adopted, not rebuilt.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contentBounds = exports.createDiagram = void 0;
+var create_diagram_1 = require("./create-diagram");
+Object.defineProperty(exports, "createDiagram", { enumerable: true, get: function () { return create_diagram_1.createDiagram; } });
+Object.defineProperty(exports, "contentBounds", { enumerable: true, get: function () { return create_diagram_1.contentBounds; } });
+//# sourceMappingURL=diagram-instance.js.map

package/src/libs/renderer/src/instance/dom-event-binder.d.ts

@@ -0,0 +1,394 @@
+import type { DiagramEngine } from '@grafloria/engine';
+import type { InteractionController } from '../interaction/interaction-controller';
+import type { CanvasRect, ViewportController } from '../viewport/viewport-controller';
+import { type TextEditTarget } from '../interaction/in-place-editor';
+/**
+ * DomEventBinder — the framework-agnostic DOM ⇄ interaction seam.
+ *
+ * Blocker #2 of the headless-instance contract (see ./diagram-instance.ts) and,
+ * per that note, "the single largest remaining piece". The listeners used to be
+ * Angular `@HostListener`s on the 2900-line `DiagramCanvasComponent`, and the
+ * ORDER in which a `mousedown` is dispatched across
+ *
+ *   port → control-point → waypoint → link endpoint → link label → link body →
+ *   node → empty canvas
+ *
+ * lived inline in that component. Nothing outside Angular could interact with a
+ * diagram. This class owns exactly that decision tree, with no framework and no
+ * engine-mutation logic of its own:
+ *
+ *      addEventListener  →  ViewportController.clientToWorld  →  InteractionController
+ *
+ * It never decides who re-renders. Like every other Wave-3 controller it answers
+ * "what happened?" and calls {@link DomEventBinderHost.requestRender} when a
+ * repaint is warranted; the host turns that into its own render trigger.
+ *
+ * ## What it owns beyond delegation
+ *
+ * - **Panning** (middle-drag, space+drag, wheel-scroll) — pure camera work, so it
+ *   goes straight to the {@link ViewportController}.
+ * - **Node dragging with a movement threshold.** A drag is ARMED on mousedown but
+ *   does not move anything until the pointer travels farther than `dragThreshold`
+ *   CSS px, so a plain click never micro-jitters a node's position. In DELIBERATE
+ *   mode a node is only draggable if it was ALREADY selected before the press.
+ *   (Same two rules the Angular `ToolManager` enforces — reimplemented here in 60
+ *   lines because that class lives in the Angular library and a core module must
+ *   not depend on a framework wrapper.)
+ * - **Keyboard**: Delete/Backspace, Escape, Ctrl/⌘+A, Space (pan modifier).
+ *
+ * Marquee selection is deliberately NOT here: it needs an overlay rectangle in
+ * the host's own layer, so it stays with the hosts that already draw one.
+ */
+/** Everything the binder needs from its host. Keeps this class DI-free. */
+export interface DomEventBinderHost {
+    /** The engine, or null before a diagram is attached. */
+    getEngine(): DiagramEngine | null;
+    readonly viewport: ViewportController;
+    readonly interaction: InteractionController;
+    /** The canvas' client rect (for screen→world). */
+    getRect(): CanvasRect;
+    /** "Something visible changed" — the host coalesces this into a frame. */
+    requestRender(): void;
+    /** Emit a public diagram event (`node:click`, `connect`, …). */
+    emit(event: string, payload: unknown): void;
+}
+export interface DomEventBinderOptions {
+    /** Middle-drag / space-drag / wheel-scroll panning. Default true. */
+    enablePan?: boolean;
+    /** Ctrl/⌘ + wheel zoom. Default true. */
+    enableZoom?: boolean;
+    /** Relative zoom step per wheel notch. Default 0.1 (a notch is ×1.1). */
+    zoomSensitivity?: number;
+    /** CSS px the pointer must travel before a node drag commits. Default 4. */
+    dragThreshold?: number;
+    /** Ignore every mutation-causing gesture (still pans/zooms). Default false. */
+    readonly?: boolean;
+}
+export declare class DomEventBinder {
+    private readonly container;
+    private readonly host;
+    private readonly options;
+    private attached;
+    private spaceKeyPressed;
+    private isPanning;
+    /** Armed by an empty-canvas left press; becomes a real pan past the drag threshold. */
+    private pendingEmptyPan;
+    /**
+     * The screen point where a PORT press started a connection. A press on a
+     * port claims the gesture immediately — but a press that never travels past
+     * the drag threshold is a CLICK, and a click on a shape must select it.
+     * Without this, the port hit zones (top-centre, side-mid — a card's whole
+     * header band) were dead for selection: connect swallowed the press,
+     * completion at the same spot failed validation, and the release fell out
+     * as a silent no-op. Found by live audit, on every node type.
+     */
+    private pendingPortClick;
+    /**
+     * Same click-vs-gesture layering for POSITIONED EDGE LABELS: a press on a
+     * label arms a label DRAG, so a motionless press-release ended as a silent
+     * no-op and the label was a selection dead zone — a query-builder join pill
+     * you could not click (live audit finding, the port dead-band's twin).
+     */
+    private pendingLabelClick;
+    private lastPanX;
+    private lastPanY;
+    private nodeDrag;
+    private groupDrag;
+    /**
+     * wave12/connect-ergonomics (gap 2): the proximity-connect engine, lazily
+     * built the first time `enableProximityConnect` is used. Reused across drags so
+     * a highlight it painted can always be cleared by the same instance.
+     */
+    private snap?;
+    /** T10 — the in-place label editor + its live DOM widget (lazy). */
+    private textEditor?;
+    private keyboardNav?;
+    private activeTextInput?;
+    /** T8 — lazily built per diagram; rebuilt when the diagram identity changes. */
+    private membership?;
+    /** The proximity candidate currently highlighted mid-drag (for commit on drop). */
+    private proximityCandidate;
+    private readonly boundWheel;
+    /**
+     * Wave 9 — Card 2. The touch pipeline.
+     *
+     * The binder used to listen for `mousedown`/`mousemove`/`mouseup` — MouseEvent,
+     * mouse only. A touch reached it only as a browser-synthesized "compatibility"
+     * mouse event: no pinch, no two-finger pan, no long-press, a 300ms delay, and
+     * nothing at all once the browser decided the gesture was a scroll.
+     *
+     * Now the binder listens for POINTER events and forks on `pointerType`:
+     *   - touch  → TouchGestureController (multi-touch, gesture-aware)
+     *   - mouse/pen → the existing ladder below, unchanged (PointerEvent IS a
+     *     MouseEvent, so onMouseDown/Move/Up take it as-is)
+     */
+    private readonly touch;
+    /**
+     * wave12/node-resize. The floating-tool controller, configured to expose ONLY
+     * the 8 resize handles (halo / rotate / remove / link tools stay off — those
+     * belong to the richer host renderers, not the framework-free default path).
+     *
+     * ONE instance is shared with {@link TouchGestureController} so a resize can be
+     * driven by a mouse OR a finger without two controllers ever fighting over the
+     * same gesture (they never run at once, and single-active-gesture is the rule).
+     */
+    private readonly selectionTools;
+    /**
+     * Have we ever seen a real PointerEvent?
+     *
+     * The mouse listeners are kept as a LEGACY FALLBACK and auto-disable the instant
+     * a pointer event arrives. Why: every real browser fires `pointerdown` before the
+     * compatibility `mousedown`, so in a browser the pointer path wins and the mouse
+     * path goes dead — no double-handling. But jsdom implements NO PointerEvent at
+     * all, and this renderer's unit suites drive the binder by dispatching real
+     * `MouseEvent`s at the container. Feature-detecting instead of hard-switching
+     * keeps those suites (and any host that synthesizes mouse events) working exactly
+     * as before, while real hardware gets the pointer pipeline.
+     */
+    private sawPointerEvent;
+    /** The container's own touch-action, restored on detach. */
+    private previousTouchAction;
+    private readonly boundPointerDown;
+    private readonly boundPointerMove;
+    private readonly boundPointerUp;
+    private readonly boundPointerCancel;
+    private readonly boundContextMenu;
+    /**
+     * Wave 6 — Card 5. The registered tool that CLAIMED the current gesture, if
+     * any. Exactly one tool owns a gesture end-to-end (the same single-active-tool
+     * rule the Angular ToolManager enforces).
+     */
+    private activeTool?;
+    private activeToolHit?;
+    /**
+     * Wave 6 — Card 3. The nodes currently being DRAGGED (past the movement
+     * threshold — an armed-but-uncommitted press is a click, not a drag).
+     *
+     * Node-drag state lives here, not on the InteractionController, so a custom
+     * node component had no way to know it was being dragged — and `dragging` is
+     * one of the props the component contract promises. This is the read-only
+     * window onto it.
+     */
+    getDraggingNodeIds(): string[];
+    /**
+     * True while a resize / rotate / vertex gesture owns the pointer.
+     *
+     * The companion to {@link getDraggingNodeIds} for the gestures that are NOT node drags.
+     * Custom-node culling needs it: unmounting a host element mid-resize would take the
+     * pointer capture and the handles with it, and `SelectionToolsController` keeps the
+     * gesture's own node private, so "is a gesture live" plus the current selection is the
+     * answer available from out here.
+     */
+    hasActiveGesture(): boolean;
+    private readonly boundMouseDown;
+    private readonly boundMouseMove;
+    private readonly boundMouseUp;
+    private readonly boundMouseLeave;
+    private readonly boundDblClick;
+    private readonly boundKeyDown;
+    private readonly boundKeyUp;
+    constructor(container: HTMLElement, host: DomEventBinderHost, options?: DomEventBinderOptions);
+    /**
+     * Wave 9 — Card 7. Is editing forbidden RIGHT NOW?
+     *
+     * Was: `this.options.readonly` — a static constructor flag. Which meant
+     * `engine.setMode(PRESENTATION)` — the engine's own read-only mode — did not
+     * reach the event binder AT ALL. You could put the engine in presentation mode
+     * and still drag nodes with the mouse.
+     *
+     * Now the binder asks the DOCUMENT, every time, so the mode is live: flip the
+     * engine to VIEW/PRESENTATION on a mounted canvas and the very next gesture is
+     * refused. The constructor option still forces read-only for a host that has no
+     * mode concept.
+     */
+    private isReadonly;
+    /** Bind DOM listeners. No-op on the server and no-op if already attached. */
+    attach(): void;
+    /** Remove EXACTLY the listeners we added, and drop all gesture state. */
+    detach(): void;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerUp;
+    private onPointerCancel;
+    /**
+     * The native context menu. On touch the long-press already emitted our own
+     * `contextmenu` payload, so the OS menu here would be a duplicate on top of it.
+     */
+    private onContextMenu;
+    get isAttached(): boolean;
+    onWheel(event: WheelEvent): void;
+    /** Wave 6 — Card 5: adapt a DOM event to the framework-free tool contract. */
+    private toToolEvent;
+    /** What the gesture landed on. Resolved ONCE, on pointerdown. */
+    private toToolHit;
+    /**
+     * wave12/node-resize: the resize handle (if any) under a world point.
+     *
+     * Recomputes the tool layer at the CURRENT zoom on every press — the handles are
+     * a constant screen size, so their world footprint changes with the camera, and a
+     * stale layer would hit-test against last frame's zoom. Only `kind: 'resize'`
+     * handles are returned; the controller is configured to emit no others.
+     */
+    private resizeHandleAt;
+    /**
+     * wave14/interaction (defect 1): the reconnectable link ENDPOINT HANDLE under a
+     * world point, or null.
+     *
+     * Non-null only when the part-aware edge hit resolves to a source/target
+     * endpoint (8px grab radius) of a SELECTED link with reconnection enabled —
+     * i.e. exactly when the renderer draws a handle there. The mousedown ladder
+     * consults this INSIDE the hovered-port rung, because the handle is drawn on
+     * top of the port and a press inside its radius means the handle, not the port.
+     * Same gate as the rung-5/6 reconnect branch, so hover-then-press and
+     * press-without-hover start the identical gesture.
+     */
+    private reconnectableEndpointAt;
+    onMouseDown(event: MouseEvent): void;
+    onMouseMove(event: MouseEvent): void;
+    onMouseUp(event: MouseEvent): void;
+    /** Pointer left the canvas — abort every in-flight gesture so nothing sticks. */
+    onMouseLeave(): void;
+    /** Double-click: node → in-place rename; link label → rename; link body → waypoint. */
+    onDoubleClick(event: MouseEvent): void;
+    onKeyDown(event: KeyboardEvent): void;
+    onKeyUp(event: KeyboardEvent): void;
+    private pressNode;
+    private moveNodeDrag;
+    /** The lazily-built proximity-connect engine (only when the feature is on). */
+    private snapController;
+    /**
+     * While dragging, find the best proximity candidate for any dragged node and
+     * highlight its port pair (the SAME flags a connection drag paints). Stores it
+     * so {@link commitProximityConnection} can create the link on drop. No-op —
+     * and clears any prior highlight — when the feature is off or nothing is near.
+     */
+    private updateProximityPreview;
+    /**
+     * wave15/helper-lines: snap a SINGLE top-level dragged node to sibling
+     * alignments/equal-spacing and publish the guide segments for the renderer.
+     * Returns true when it owned the position write (the caller then skips the
+     * raw delta loop). Tracks the VIRTUAL position from {@link NodeDragState.snapAnchor}
+     * so corrections never accumulate into pointer drift.
+     */
+    private applyHelperLineSnap;
+    /** The closest proximity candidate across all dragged nodes (or null). */
+    private bestProximityCandidate;
+    /**
+     * Commit the highlighted proximity candidate as ONE undoable AddLinkCommand,
+     * then clear the highlight. Called on the node-drag mouseup. Returns true when
+     * a link was actually created.
+     */
+    private commitProximityConnection;
+    /** Drop any live proximity highlight/candidate without committing. */
+    private clearProximityPreview;
+    /**
+     * The innermost group whose outer frame contains the world point. "Innermost"
+     * (deepest nesting, then smallest area) so grabbing a nested sub-flow drags the
+     * sub-flow, not the pipeline around it. Skips groups with no drawable frame.
+     */
+    private findGroupAtPoint;
+    /**
+     * Every member NODE (recursively through nested groups) and every group FRAME
+     * (this group + its descendant groups) that a drag of `group` must carry.
+     * Cycle-guarded so a corrupt membership loop can never spin.
+     */
+    private collectGroupContents;
+    /** Snapshot a group frame's restorable geometry (for undo). */
+    private snapshotFrame;
+    /** Arm a group drag (threshold-gated, mirroring the node-drag arming). */
+    private pressGroup;
+    /** Translate the whole subflow live during a group drag (past the threshold). */
+    private moveGroupDrag;
+    /**
+     * wave12: commit a finished node drag as ONE undoable step.
+     *
+     * The live drag mutated node positions directly for feedback and recorded NOTHING on
+     * the command history — so Ctrl+Z could not undo a drag (keyboard-nudge and resize both
+     * commit MoveNodeCommand; only the pointer drag skipped it). This is the same FROM→TO
+     * snapshot endGroupDrag uses: the state is already at `to`, so each MoveNodeCommand's
+     * execute() is a visual no-op that records one history entry, and undo restores `from`.
+     * A multi-node drag collapses into one MacroCommand — one gesture, one undo step.
+     */
+    /**
+     * T8/visio — after a node drag COMMITS its move, reparent it into whatever
+     * container it was dropped in (or unembed it when dropped outside every one).
+     *
+     * The whole drop policy already lived in `GroupMembershipService`: innermost
+     * hit-test, per-group `canAddMember` veto, coordinate translation, and
+     * undoable Add/RemoveFromGroupCommand on the shared stack. It was simply
+     * never constructed outside its own specs, so a drag into a container moved
+     * the node's x/y and nothing else. This is the missing call.
+     *
+     * Runs only for a single-node drag: a multi-select drop into a container is a
+     * separate policy question (which member wins the hit-test?), and guessing it
+     * silently is worse than leaving it to a host.
+     */
+    /**
+     * T2/visio — the snap hook handed to `updateResize`, or undefined when helper
+     * lines are off. Snaps the resized box against every OTHER node's box and
+     * publishes the same guides the drag path draws, so a resize aligns to its
+     * neighbours instead of landing a pixel out.
+     */
+    private resizeSnapHook;
+    private applyMembershipOnDrop;
+    private commitNodeMove;
+    /**
+     * End a group drag: commit the whole gesture as ONE undoable MoveGroupCommand
+     * (drag-start snapshot → current), then emit change events. The live drag has
+     * already applied the final positions, so the command's execute() is a visual
+     * no-op that merely records the single history entry; undo restores the start.
+     */
+    private endGroupDrag;
+    private engine;
+    /**
+     * wave12 (gap 3): is the easy-connect gate satisfied for this press? With
+     * `easyConnectModifier: 'none'` (the default when the feature is on) any plain
+     * body press connects — the whole node is a handle and move is done via a drag
+     * handle / selection. A specific modifier lets a host KEEP body-drag-to-move
+     * and reserve connect for, say, a shift-drag.
+     */
+    private easyConnectModifierHeld;
+    /**
+     * T10/visio — open the transient text widget over a node's label.
+     *
+     * The SESSION (what text, where, single- or multi-line) and the COMMIT (an
+     * undoable command) both come from `InPlaceTextEditor`; the only thing this
+     * adds is the DOM input and where to put it — mapped through the live
+     * world→client transform so it lands on the label at any zoom or pan.
+     */
+    private openTextEditor;
+    /**
+     * Open the in-place label editor programmatically — the seam behind F2 and a
+     * host's context-menu Rename. Unlike the double-click path this is NOT gated
+     * on `enableInPlaceTextEdit`: an explicit call IS the host's opt-in.
+     * Returns false when the target does not exist / is not editable / readonly.
+     */
+    beginLabelEdit(target: TextEditTarget, options?: {
+        seed?: string;
+    }): boolean;
+    /** Drop any live text widget without committing (a new edit, or teardown). */
+    private closeTextEditor;
+    private toWorld;
+    /**
+     * The node under the pointer. SVG hit-testing first; then walk up from
+     * `event.target` looking for a `data-node-id`, which is how nodes rendered
+     * into the HTML layer (foreignObject / custom components) are found — they are
+     * absolutely positioned DOM, invisible to the geometric hit-test.
+     */
+    private resolveNode;
+    /** Did the press that resolveNode just handled land ON a drag handle? */
+    private pressViaDragHandle;
+    /** Does this node delegate its dragging to a designated handle child? */
+    private hasDragHandlerChild;
+    /**
+     * Redirect the press to the node that should actually MOVE: an explicit drag
+     * handle drags its parent, and a child that is neither draggable nor
+     * selectable (e.g. a table row inside a node) drags its nearest draggable
+     * ancestor.
+     */
+    private dragTargetFor;
+    private setCursor;
+    private emitSelectionChange;
+    private emitNodesChange;
+    private emitEdgesChange;
+}