@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/instance/render-scheduler.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RenderScheduler — framework-agnostic rAF coalescing + idle-skip.
+ *
+ * Blocker #3 of the headless-instance contract (see ./diagram-instance.ts): the
+ * only render loop in the codebase was `DiagramCanvasComponent.scheduleRender()`,
+ * a private Angular method. This is that logic, lifted verbatim in behaviour and
+ * with no framework or DOM imports, so React / the web component / a plain
+ * `<script>` host all inherit the same frame discipline:
+ *
+ *   - **Coalescing.** Any number of `schedule()` calls in one tick collapse into
+ *     exactly ONE painted frame. A burst of engine events (`node:changed` ×N, a
+ *     drag's mousemoves, several prop changes in one React commit) paints once.
+ *   - **Idle-skip.** A queued frame is DROPPED when `shouldSkip()` says nothing
+ *     visible can have changed — cheaper than a no-op render of a big diagram.
+ *   - **Synchronous escape.** `flush()` paints right now and cancels the queued
+ *     frame; used for the mount paint (so the first frame is not one rAF late)
+ *     and by tests.
+ *
+ * `requestFrame`/`cancelFrame` are injectable: pass fakes in tests, and note the
+ * default falls back to `setTimeout` where rAF is missing (Node), so a scheduler
+ * constructed during SSR never throws — it simply never gets a chance to fire
+ * because nothing calls `schedule()` on the server.
+ */
+export interface RenderSchedulerOptions {
+    /** The paint. Called at most once per frame. */
+    onFrame: () => void;
+    /**
+     * Idle-skip predicate, evaluated INSIDE the frame (not at schedule time, so it
+     * sees the final state of the tick). Return true to drop the frame.
+     */
+    shouldSkip?: () => boolean;
+    /** Injectable rAF (defaults to the platform one, with a setTimeout fallback). */
+    requestFrame?: (cb: (time: number) => void) => number;
+    /** Injectable cancel, must pair with `requestFrame`. */
+    cancelFrame?: (handle: number) => void;
+}
+/** Cheap counters — a steady-state idle canvas should paint 0 frames. */
+export interface RenderSchedulerStats {
+    /** `schedule()` calls. */
+    scheduled: number;
+    /** Frames actually painted (`onFrame` ran). */
+    painted: number;
+    /** Queued frames dropped by `shouldSkip()`. */
+    skipped: number;
+    /** `schedule()` calls that folded into an already-queued frame. */
+    coalesced: number;
+    /** Duration (ms) of the most recent paint. */
+    lastFrameMs: number;
+}
+export declare class RenderScheduler {
+    private handle;
+    private dirty;
+    private disposed;
+    private readonly onFrame;
+    private readonly shouldSkip?;
+    private readonly requestFrameFn;
+    private readonly cancelFrameFn;
+    private _stats;
+    constructor(options: RenderSchedulerOptions);
+    get stats(): Readonly<RenderSchedulerStats>;
+    /** True while a frame is queued but has not run yet. */
+    get pending(): boolean;
+    /**
+     * Mark dirty and queue a frame. Idempotent within a tick — the second and
+     * later calls before the frame runs are counted as `coalesced`, not queued.
+     */
+    schedule(): void;
+    /**
+     * Paint NOW, bypassing rAF and the idle-skip check, and cancel any queued
+     * frame. This is the mount paint (and the "give me a correct DOM before I
+     * measure it" escape hatch).
+     */
+    flush(): void;
+    /** Drop a queued frame without painting. */
+    cancel(): void;
+    dispose(): void;
+    private cancelPending;
+    private paint;
+}

package/src/libs/renderer/src/instance/render-scheduler.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderScheduler = void 0;
+const platform_1 = require("../platform");
+class RenderScheduler {
+    constructor(options) {
+        var _a, _b;
+        this.handle = null;
+        this.dirty = false;
+        this.disposed = false;
+        this._stats = {
+            scheduled: 0,
+            painted: 0,
+            skipped: 0,
+            coalesced: 0,
+            lastFrameMs: 0,
+        };
+        this.onFrame = options.onFrame;
+        this.shouldSkip = options.shouldSkip;
+        this.requestFrameFn = (_a = options.requestFrame) !== null && _a !== void 0 ? _a : platform_1.requestFrame;
+        this.cancelFrameFn = (_b = options.cancelFrame) !== null && _b !== void 0 ? _b : platform_1.cancelFrame;
+    }
+    get stats() {
+        return this._stats;
+    }
+    /** True while a frame is queued but has not run yet. */
+    get pending() {
+        return this.handle !== null;
+    }
+    /**
+     * Mark dirty and queue a frame. Idempotent within a tick — the second and
+     * later calls before the frame runs are counted as `coalesced`, not queued.
+     */
+    schedule() {
+        if (this.disposed)
+            return;
+        this._stats.scheduled++;
+        this.dirty = true;
+        if (this.handle !== null) {
+            this._stats.coalesced++;
+            return;
+        }
+        this.handle = this.requestFrameFn(() => {
+            var _a;
+            this.handle = null;
+            if (this.disposed)
+                return;
+            // A synchronous flush() already painted this tick's work.
+            if (!this.dirty)
+                return;
+            if ((_a = this.shouldSkip) === null || _a === void 0 ? void 0 : _a.call(this)) {
+                this.dirty = false;
+                this._stats.skipped++;
+                return;
+            }
+            this.paint();
+        });
+    }
+    /**
+     * Paint NOW, bypassing rAF and the idle-skip check, and cancel any queued
+     * frame. This is the mount paint (and the "give me a correct DOM before I
+     * measure it" escape hatch).
+     */
+    flush() {
+        if (this.disposed)
+            return;
+        this.cancelPending();
+        this.dirty = false;
+        this.paint();
+    }
+    /** Drop a queued frame without painting. */
+    cancel() {
+        this.cancelPending();
+        this.dirty = false;
+    }
+    dispose() {
+        this.cancelPending();
+        this.disposed = true;
+        this.dirty = false;
+    }
+    cancelPending() {
+        if (this.handle !== null) {
+            this.cancelFrameFn(this.handle);
+            this.handle = null;
+        }
+    }
+    paint() {
+        const start = (0, platform_1.now)();
+        this.dirty = false;
+        this.onFrame();
+        this._stats.painted++;
+        this._stats.lastFrameMs = (0, platform_1.now)() - start;
+    }
+}
+exports.RenderScheduler = RenderScheduler;
+//# sourceMappingURL=render-scheduler.js.map

package/src/libs/renderer/src/instance/wheel-scroll-yield.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Wheel-over-scrollable-card delegation — makes scrollbars inside HTML nodes
+ * (foreignObject cards: ER tables, class boxes, custom cards) usable, and
+ * keeps a card's wheel from ever panning the canvas out from under the cursor.
+ *
+ * Two facts, both found empirically, force this to be a DELEGATION and not a
+ * mere yield:
+ *
+ *  1. The binder's plain-wheel PAN branch preventDefault()s every wheel, so
+ *     native scroll never runs and the canvas pans under the cursor.
+ *  2. Card content inside a foreignObject is `pointer-events: none` (so
+ *     clicks and drags fall through to the node) — the wheel's target is the
+ *     foreignObject or another SVG element, NEVER the scrollable div. Even if
+ *     the canvas yielded, the browser would have nothing to scroll: a
+ *     pointer-events:none element can't be an event target, and native scroll
+ *     chains only walk UP from the target.
+ *
+ * So the binder finds the scrollable content under the cursor itself and
+ * scrolls it programmatically. The rule is CONTAINMENT (overscroll-behavior:
+ * contain), not scroll-chaining:
+ *
+ *  - ctrl/⌘ wheel (pinch-zoom) ALWAYS belongs to the canvas;
+ *  - a plain wheel over a card that is scrollable in the wheel's axis belongs
+ *    to THAT card — it scrolls as far as it can and, AT THE END OF ITS RANGE,
+ *    the wheel is CONSUMED, not handed to the canvas. Reaching the bottom of a
+ *    table must never suddenly pan the whole diagram (the reported bug). To
+ *    pan, the cursor leaves the card;
+ *  - a plain wheel that is NOT over such a card falls through to the canvas.
+ */
+/**
+ * If this wheel is over scrollable card content, scroll that content and
+ * report the wheel HANDLED — the caller preventDefault()s and skips panning.
+ * Handled is returned whenever the cursor is over such a card, INCLUDING at
+ * the end of its scroll range (containment: the card, not the canvas, absorbs
+ * the wheel). Returns false only for pinch-zoom or when no scrollable card is
+ * under the cursor, so the canvas pans normally.
+ */
+export declare function delegateWheelToScrollable(event: WheelEvent): boolean;

package/src/libs/renderer/src/instance/wheel-scroll-yield.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Wheel-over-scrollable-card delegation — makes scrollbars inside HTML nodes
+ * (foreignObject cards: ER tables, class boxes, custom cards) usable, and
+ * keeps a card's wheel from ever panning the canvas out from under the cursor.
+ *
+ * Two facts, both found empirically, force this to be a DELEGATION and not a
+ * mere yield:
+ *
+ *  1. The binder's plain-wheel PAN branch preventDefault()s every wheel, so
+ *     native scroll never runs and the canvas pans under the cursor.
+ *  2. Card content inside a foreignObject is `pointer-events: none` (so
+ *     clicks and drags fall through to the node) — the wheel's target is the
+ *     foreignObject or another SVG element, NEVER the scrollable div. Even if
+ *     the canvas yielded, the browser would have nothing to scroll: a
+ *     pointer-events:none element can't be an event target, and native scroll
+ *     chains only walk UP from the target.
+ *
+ * So the binder finds the scrollable content under the cursor itself and
+ * scrolls it programmatically. The rule is CONTAINMENT (overscroll-behavior:
+ * contain), not scroll-chaining:
+ *
+ *  - ctrl/⌘ wheel (pinch-zoom) ALWAYS belongs to the canvas;
+ *  - a plain wheel over a card that is scrollable in the wheel's axis belongs
+ *    to THAT card — it scrolls as far as it can and, AT THE END OF ITS RANGE,
+ *    the wheel is CONSUMED, not handed to the canvas. Reaching the bottom of a
+ *    table must never suddenly pan the whole diagram (the reported bug). To
+ *    pan, the cursor leaves the card;
+ *  - a plain wheel that is NOT over such a card falls through to the canvas.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delegateWheelToScrollable = delegateWheelToScrollable;
+const SCROLLABLE_OVERFLOW = /(auto|scroll)/;
+/** Does `el` overflow in an axis this wheel drives (so the card owns the wheel)? */
+function ownsWheel(el, event) {
+    var _a, _b;
+    const style = (_b = (_a = el.ownerDocument) === null || _a === void 0 ? void 0 : _a.defaultView) === null || _b === void 0 ? void 0 : _b.getComputedStyle(el);
+    if (!style)
+        return false;
+    const scrollableY = SCROLLABLE_OVERFLOW.test(style.overflowY) && el.scrollHeight > el.clientHeight;
+    const scrollableX = SCROLLABLE_OVERFLOW.test(style.overflowX) && el.scrollWidth > el.clientWidth;
+    return (event.deltaY !== 0 && scrollableY) || (event.deltaX !== 0 && scrollableX);
+}
+/** Scroll `el` by the event's deltas, clamped to its range. */
+function applyScroll(el, event) {
+    var _a, _b;
+    const style = (_b = (_a = el.ownerDocument) === null || _a === void 0 ? void 0 : _a.defaultView) === null || _b === void 0 ? void 0 : _b.getComputedStyle(el);
+    if (!style)
+        return;
+    if (event.deltaY !== 0 && SCROLLABLE_OVERFLOW.test(style.overflowY) && el.scrollHeight > el.clientHeight) {
+        el.scrollTop = Math.max(0, Math.min(el.scrollTop + event.deltaY, el.scrollHeight - el.clientHeight));
+    }
+    if (event.deltaX !== 0 && SCROLLABLE_OVERFLOW.test(style.overflowX) && el.scrollWidth > el.clientWidth) {
+        el.scrollLeft = Math.max(0, Math.min(el.scrollLeft + event.deltaX, el.scrollWidth - el.clientWidth));
+    }
+}
+/** Nearest ancestor (self included) that is a foreignObject or a node group. */
+function scrollScope(target) {
+    var _a, _b;
+    let el = target;
+    while (el) {
+        const name = el.localName.toLowerCase();
+        if (name === 'foreignobject')
+            return el;
+        if (((_a = el.hasAttribute) === null || _a === void 0 ? void 0 : _a.call(el, 'data-node-id')) || ((_b = el.classList) === null || _b === void 0 ? void 0 : _b.contains('node-group')))
+            return el;
+        el = el.parentElement;
+    }
+    return null;
+}
+/**
+ * If this wheel is over scrollable card content, scroll that content and
+ * report the wheel HANDLED — the caller preventDefault()s and skips panning.
+ * Handled is returned whenever the cursor is over such a card, INCLUDING at
+ * the end of its scroll range (containment: the card, not the canvas, absorbs
+ * the wheel). Returns false only for pinch-zoom or when no scrollable card is
+ * under the cursor, so the canvas pans normally.
+ */
+function delegateWheelToScrollable(event) {
+    if (event.ctrlKey || event.metaKey)
+        return false;
+    const target = event.target instanceof Element ? event.target : null;
+    if (!target)
+        return false;
+    // Path 1 — the target IS HTML (overlay-layer nodes, or cards that enable
+    // pointer events): the innermost element that owns the wheel absorbs it.
+    let el = target;
+    while (el && el instanceof HTMLElement) {
+        if (ownsWheel(el, event)) {
+            applyScroll(el, event);
+            return true;
+        }
+        el = el.parentElement;
+    }
+    // Path 2 — the target is SVG (the usual case: card content is
+    // pointer-events:none, the foreignObject or node shape took the hit).
+    // Find the deepest card element under the cursor that owns the wheel.
+    const scope = scrollScope(target);
+    if (!scope)
+        return false;
+    const { clientX, clientY } = event;
+    const candidates = [];
+    for (const cand of Array.from(scope.querySelectorAll('*'))) {
+        if (!(cand instanceof HTMLElement) || !ownsWheel(cand, event))
+            continue;
+        const rect = cand.getBoundingClientRect();
+        if (clientX < rect.left || clientX > rect.right || clientY < rect.top || clientY > rect.bottom)
+            continue;
+        candidates.push(cand);
+    }
+    // Document order lists ancestors before descendants — the deepest owner wins.
+    const owner = candidates[candidates.length - 1];
+    if (!owner)
+        return false;
+    applyScroll(owner, event);
+    return true;
+}
+//# sourceMappingURL=wheel-scroll-yield.js.map

package/src/libs/renderer/src/interaction/ControlPointEditor.d.ts

@@ -0,0 +1,160 @@
+import type { Point, PathSegment } from '@grafloria/engine';
+import type { ControlPointEditorConfig } from '@grafloria/engine';
+import type { VNode } from '../types/vnode.types';
+/**
+ * Control point information
+ */
+export interface ControlPoint {
+    /** Position of the control point */
+    point: Point;
+    /** Index of the segment this control point belongs to */
+    segmentIndex: number;
+    /** Type of control point (control1 or control2) */
+    type: 'control1' | 'control2';
+    /** Anchor point (from/to) that this control point affects */
+    anchor: Point;
+}
+/**
+ * Result of hit testing a control point
+ */
+export interface ControlPointHitResult {
+    /** Index of the segment */
+    segmentIndex: number;
+    /** Type of control point */
+    controlType: 'control1' | 'control2';
+    /** Position of the control point */
+    point: Point;
+    /** Anchor point */
+    anchor: Point;
+}
+/**
+ * ControlPointEditor provides functionality for editing bezier curve control points
+ *
+ * Features:
+ * - Detect and track control points from path segments
+ * - Hit testing for control point handles
+ * - Move control points via drag
+ * - Auto-generate smooth bezier curves from points
+ * - Grid snapping support
+ * - Symmetric control point mirroring
+ * - Visual rendering of control handles and lines
+ *
+ * @example
+ * ```typescript
+ * const editor = new ControlPointEditor(config);
+ *
+ * // Detect control points from segments
+ * const controlPoints = editor.getControlPoints(link.segments);
+ *
+ * // Hit test for click
+ * const hit = editor.hitTestControlPoint(mouseX, mouseY, link.segments);
+ *
+ * // Move control point
+ * const newSegments = editor.moveControlPoint(hit.segmentIndex, hit.controlType, newPos, link.segments);
+ *
+ * // Render visual handles
+ * const handles = editor.renderControlPointHandles(link.segments, link.id);
+ * ```
+ */
+export declare class ControlPointEditor {
+    private config;
+    constructor(config: ControlPointEditorConfig);
+    /**
+     * Get all control points from path segments
+     *
+     * @param segments - Path segments to extract control points from
+     * @returns Array of control point information
+     */
+    getControlPoints(segments: PathSegment[]): ControlPoint[];
+    /**
+     * Hit test for control point handles
+     * Optimized to avoid allocations on hot path (mousemove)
+     *
+     * @param mouseX - Mouse X coordinate
+     * @param mouseY - Mouse Y coordinate
+     * @param segments - Path segments
+     * @returns Hit result if a control point was clicked, null otherwise
+     */
+    hitTestControlPoint(mouseX: number, mouseY: number, segments: PathSegment[], 
+    /** Wave 9 — Card 2: extra world-space radius for a touch pointer. 0 for mouse. */
+    hitSlop?: number): ControlPointHitResult | null;
+    /**
+     * Move a control point to a new position
+     *
+     * @param segmentIndex - Index of the segment
+     * @param controlType - Type of control point (control1 or control2)
+     * @param newPosition - New position for the control point
+     * @param segments - Current path segments
+     * @returns Updated segments array, or null if invalid
+     */
+    moveControlPoint(segmentIndex: number, controlType: 'control1' | 'control2', newPosition: Point, segments: PathSegment[]): PathSegment[] | null;
+    /**
+     * Apply symmetric control point mirroring to adjacent segment
+     *
+     * @param segments - Segments array (mutated)
+     * @param segmentIndex - Index of the segment being edited
+     * @param controlType - Type of control point being moved
+     * @param newPosition - New position of the control point
+     */
+    private applySymmetricControl;
+    /**
+     * Auto-generate bezier curve segments from an array of points
+     *
+     * Uses Catmull-Rom algorithm to generate smooth curves
+     *
+     * @param points - Array of points to convert to bezier curves
+     * @returns Array of curve segments with auto-generated control points
+     */
+    generateBezierSegments(points: Point[]): PathSegment[];
+    /**
+     * Snap a point to the grid
+     *
+     * @param point - Point to snap
+     * @returns Snapped point
+     */
+    snapToGrid(point: Point): Point;
+    /**
+     * Calculate Euclidean distance between two points
+     *
+     * @param p1 - First point
+     * @param p2 - Second point
+     * @returns Distance in pixels
+     */
+    calculateDistance(p1: Point, p2: Point): number;
+    /**
+     * Render a control point handle as a VNode
+     *
+     * @param controlPoint - Control point to render
+     * @param linkId - ID of the link (for DOM identification)
+     * @returns VNode representing the control point handle
+     */
+    renderControlPointHandle(controlPoint: ControlPoint, linkId: string): VNode;
+    /**
+     * Render a control line (from anchor to control point) as a VNode
+     *
+     * @param controlPoint - Control point to render line for
+     * @param linkId - ID of the link
+     * @returns VNode representing the control line
+     */
+    renderControlLine(controlPoint: ControlPoint, linkId: string): VNode;
+    /**
+     * Render all control point handles for a link
+     *
+     * @param segments - Path segments
+     * @param linkId - ID of the link
+     * @returns Array of VNodes for rendering
+     */
+    renderControlPointHandles(segments: PathSegment[], linkId: string): VNode[];
+    /**
+     * Update configuration (partial update)
+     *
+     * @param partialConfig - Partial configuration to merge
+     */
+    updateConfig(partialConfig: Partial<ControlPointEditorConfig>): void;
+    /**
+     * Get current configuration
+     *
+     * @returns Current configuration (readonly copy)
+     */
+    getConfig(): Readonly<ControlPointEditorConfig>;
+}