@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,48 +0,0 @@
-/**
- * ============================================================================
- * 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

@@ -1,51 +0,0 @@
-"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

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