@grafloria/element 0.3.18 → 0.3.19

package/src/libs/renderer/src/interaction/interaction-controller.d.ts

@@ -0,0 +1,555 @@
+import type { DiagramEngine, NodeModel, LinkModel, Point, ArrowStyle } from '@grafloria/engine';
+import { PortModel } from '@grafloria/engine';
+import { WaypointEditor } from './WaypointEditor';
+import { ControlPointEditor } from './ControlPointEditor';
+import { ArrowRenderer } from '../svg/ArrowRenderer';
+import type { LinkHitTestOptions, LinkPart } from '../svg/link-hit-test';
+/**
+ * Part-aware link hit result: a link plus WHICH sub-part of it was hit
+ * (body / label / endpoint / arrow) and local info (label index, or the 0-1
+ * position `t` along the path for body hits). Downstream edge features
+ * (inline label editing, endpoint reconnection, edge toolbar) key off `part`.
+ */
+export interface LinkPartHit {
+    link: LinkModel;
+    part: LinkPart;
+    labelIndex?: number;
+    t?: number;
+}
+/**
+ * InteractionController — the framework-agnostic interaction brain.
+ *
+ * Owns all pointer/keyboard-driven interaction LOGIC for a diagram: hover
+ * detection, port connection dragging, link endpoint reconnection, inline label
+ * repositioning, and waypoint / control-point editing.
+ *
+ * ## Framework contract
+ *
+ * This class answers **"WHAT changed?"** — never **"who should re-render?"**.
+ * Every handler returns a boolean (or a value) telling the host whether a
+ * re-render is warranted; the host framework decides how to act on that:
+ *
+ * - Angular  → `cdr.markForCheck()`   (see `InteractionHandlerService`)
+ * - React    → `setState` / `useSyncExternalStore`
+ * - Vue      → touch a `ref`
+ * - Vanilla  → call your own `render()`
+ *
+ * It therefore has **zero framework imports** (no Angular, no DOM beyond the
+ * ambient `performance.now()` clock) and is instantiated with a plain `new`.
+ * It takes WORLD coordinates only: converting client/screen pixels into world
+ * space is the job of {@link ViewportController}, so this class never touches
+ * an event, an element, or a bounding rect.
+ *
+ * Supports three interaction modes (driven by the engine's interaction config):
+ * - DIRECT: Drag node body to move, drag port to connect
+ * - DELIBERATE: Select node first, then drag to move
+ * - SMART: Visio-style with hover-based port visibility
+ *
+ * The Angular `InteractionHandlerService` is a thin `@Injectable` subclass of
+ * this class and adds no behaviour of its own.
+ */
+export declare class InteractionController {
+    /**
+     * Shared arrow renderer used only for canonical arrow tip-offset geometry
+     * when computing arrowhead hit anchors (see {@link buildLinkHitOptions}).
+     */
+    protected readonly arrowRenderer: ArrowRenderer;
+    /**
+     * Wave 9 — Card 2. Extra hit radius in WORLD units, granted while a TOUCH
+     * pointer owns the gesture (the binder sets it on touch down and clears it on
+     * up). A 5px port is not hittable with a fingertip; this is what makes ports,
+     * waypoints and control-point handles touch-sized without changing how any of
+     * them RENDER — the visual stays crisp, only the catchment grows.
+     *
+     * World, not screen: every hit test here is world-space, so a screen-px slop
+     * would shrink to nothing exactly when you are zoomed out and the targets are
+     * already smallest.
+     */
+    private hitSlop;
+    /**
+     * Wave 9 — Card 7. Is the document locked?
+     *
+     * The InteractionController is the LAST place a read-only bypass could hide,
+     * because it is the one layer that mutates the model DIRECTLY — it never touches
+     * the CommandManager. Most of its writes now hit the model-level guards anyway,
+     * but `moveControlPoint` writes `link.segments` as a RAW PUBLIC FIELD, which no
+     * model guard can see. So the refusal has to be here as well.
+     */
+    private isReadonlyEngine;
+    /** Read-only probe for the methods that are handed a link but no engine. */
+    private isReadonlyLink;
+    /** Grow every hit target by `world` units (0 = mouse-precision, the default). */
+    setHitSlop(world: number): void;
+    getHitSlop(): number;
+    /**
+     * The renderer's configured interaction-stroke width (`linkHitAreaWidth`).
+     * The link grab distance derives from it so the painted invitation and the
+     * accepted press stay the SAME geometry — createDiagram syncs it whenever
+     * the host overrides the renderer default.
+     */
+    private linkHitAreaWidthConfig;
+    setLinkHitAreaWidth(width: number): void;
+    /**
+     * Current hover state
+     */
+    protected hoveredNode: NodeModel | null;
+    protected hoveredPort: PortModel | null;
+    protected hoveredLink: LinkModel | null;
+    /**
+     * Connection drag state
+     */
+    protected isConnecting: boolean;
+    protected connectionSourcePort: PortModel | null;
+    /**
+     * Link reconnection state
+     */
+    protected isReconnectingLink: boolean;
+    protected reconnectingLink: LinkModel | null;
+    protected reconnectingEndpoint: 'source' | 'target' | null;
+    /** Wave 2: current cursor position while dragging a reconnecting endpoint. */
+    protected reconnectingMousePoint: Point | null;
+    /**
+     * Wave 2 (Edges & links): inline label drag-reposition state. While active,
+     * mouse moves remap the cursor to a (position 0-1, offset) pair on the model
+     * so the label survives re-routing. See {@link computeLabelDragUpdate}.
+     */
+    protected isDraggingLabel: boolean;
+    protected editingLabelLink: LinkModel | null;
+    protected editingLabelIndex: number | null;
+    /**
+     * Phase 2.3a: Waypoint editing state
+     */
+    protected isDraggingWaypoint: boolean;
+    protected editingLink: LinkModel | null;
+    protected editingWaypointIndex: number | null;
+    /**
+     * wave12: the link's points when a waypoint drag STARTED, so endWaypointDrag can commit
+     * the whole gesture as one undoable SetLinkPointsCommand (FROM→TO). Absent between drags.
+     */
+    protected waypointDragStartPoints: Point[] | null;
+    protected waypointEditor: WaypointEditor | null;
+    protected hoveredWaypointIndex: number | null;
+    protected hoveredWaypointLink: LinkModel | null;
+    /**
+     * Phase 2.3b: Control point editing state
+     */
+    protected isDraggingControlPoint: boolean;
+    protected editingControlPointLink: LinkModel | null;
+    protected editingControlPointSegmentIndex: number | null;
+    protected editingControlPointType: 'control1' | 'control2' | null;
+    protected controlPointEditor: ControlPointEditor | null;
+    protected hoveredControlPointSegmentIndex: number | null;
+    protected hoveredControlPointType: 'control1' | 'control2' | null;
+    protected hoveredControlPointLink: LinkModel | null;
+    /**
+     * Phase 5: Performance optimization - debounce hover detection
+     */
+    protected hoverDebounceTimer: any;
+    protected readonly HOVER_DEBOUNCE_MS = 16;
+    /**
+     * Phase 5: Performance monitoring
+     */
+    protected performanceMetrics: {
+        hoverDetectionTime: number;
+        connectionUpdateTime: number;
+        portHitTestTime: number;
+    };
+    /**
+     * Phase 5: Port hit test cache for performance
+     */
+    protected portHitCache: Map<string, {
+        x: number;
+        y: number;
+        radius: number;
+    }>;
+    protected portHitCacheInvalidated: boolean;
+    constructor();
+    /**
+     * Phase 5: Dispose and cleanup resources
+     */
+    dispose(): void;
+    /**
+     * Phase 5: Get performance metrics
+     */
+    getPerformanceMetrics(): {
+        hoverDetectionTime: number;
+        connectionUpdateTime: number;
+        portHitTestTime: number;
+    };
+    /**
+     * Phase 5: Invalidate port hit cache (call when nodes move or ports change)
+     */
+    invalidatePortHitCache(): void;
+    /**
+     * Phase 3: Handle mouse move for hover detection
+     * Phase 5: Enhanced with performance monitoring and validation
+     * Updates hover states for nodes, ports, and links
+     * CRITICAL FIX: Added comprehensive debugging
+     */
+    handleMouseMove(worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /**
+     * Phase 3: Handle connection drag update
+     * Phase 5: Enhanced with performance monitoring and validation
+     * Updates connection preview during drag
+     */
+    handleConnectionDrag(worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /**
+     * Phase 3: Start connection from port
+     * Phase 5: Enhanced with validation and error handling
+     * CRITICAL FIX: Added detailed logging
+     */
+    startConnection(port: PortModel, worldX: number, worldY: number, engine: DiagramEngine): void;
+    /**
+     * wave12/connect-ergonomics (gap 3) — Easy Connect: start a connection from a
+     * node BODY, not a port glyph. Picks the source port nearest the press point
+     * (so a drag off the right side starts from the right port) and begins the
+     * normal connection drag from it. Returns false when the node has no port to
+     * start from. The whole gesture then flows through the existing connection
+     * pipeline (preview on move, {@link completeConnection} on drop).
+     */
+    startNodeBodyConnection(node: NodeModel, worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /** The node's port whose drawn position is nearest `(worldX, worldY)`, or null. */
+    private nearestPortOnNode;
+    /**
+     * Phase 3: Complete connection to target port
+     * Phase 5: Enhanced with validation and error handling
+     */
+    completeConnection(engine: DiagramEngine): boolean;
+    /**
+     * Phase 3: Cancel connection
+     */
+    cancelConnection(engine: DiagramEngine): void;
+    /**
+     * Phase 3 / Wave 2: Start link reconnection.
+     *
+     * Enters endpoint-drag mode: the dragged endpoint follows the cursor while
+     * the OTHER endpoint stays put. Seeds the engine's {@link ReconnectionPreview}
+     * so the renderer can draw a ghost link, and primes port validity highlights.
+     */
+    startLinkReconnection(link: LinkModel, endpoint: 'source' | 'target', worldX: number, worldY: number, engine: DiagramEngine): void;
+    /**
+     * Wave 2: Update the in-progress endpoint reconnection as the cursor moves.
+     *
+     * Refreshes the ghost-preview endpoint, recomputes which ports are valid drop
+     * targets (highlighting them), and reflects whether the currently hovered
+     * port would be accepted. Returns true when a re-render is warranted.
+     */
+    updateLinkReconnection(worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /**
+     * Wave 2: Is `candidatePort` a legal target for reconnecting `endpoint` of
+     * `link`? The OTHER endpoint's port stays fixed; the candidate must differ
+     * from it, live on a different node, be type-compatible (input↔output, or a
+     * bidirectional port), and satisfy the connection-group rules. Pure w.r.t.
+     * the passed models — the core of the reconnect-validation tests.
+     */
+    isValidReconnectionTarget(link: LinkModel, endpoint: 'source' | 'target', candidatePort: PortModel, engine: DiagramEngine): boolean;
+    /**
+     * Wave 2: Highlight ports as valid/invalid drop targets during an endpoint
+     * reconnection. Mirrors {@link updatePortHighlights} but uses the reconnect
+     * validity rule instead of the {@link ConnectionStateManager} valid-target set
+     * (which is empty during reconnection).
+     */
+    protected updateReconnectPortHighlights(engine: DiagramEngine): void;
+    /**
+     * Phase 3 / Wave 2: Complete link reconnection.
+     *
+     * Drops the dragged endpoint on the hovered port. Rejects (and restores the
+     * original connection) when there is no port under the cursor or the port
+     * fails {@link isValidReconnectionTarget}.
+     */
+    completeLinkReconnection(engine: DiagramEngine): boolean;
+    /**
+     * Wave 2: Cancel an in-progress endpoint reconnection, restoring the link to
+     * its original connection. Safe to call when not reconnecting.
+     */
+    cancelLinkReconnection(engine: DiagramEngine): void;
+    /**
+     * Wave 2: Tear down all reconnection state — deselect the link's endpoints,
+     * clear the engine preview, and clear port highlights.
+     */
+    protected resetReconnectionState(engine: DiagramEngine): void;
+    /**
+     * Wave 2: Map a dragged world point to a model-space label placement.
+     *
+     * Returns the `{ position, offset }` to store on the label such that the
+     * renderer draws it exactly under the cursor now AND it sticks to the same
+     * fraction of the path after re-routing:
+     *   - `position` (0-1) = closest point on the path to the cursor;
+     *   - `offset`         = cursor − on-path anchor at `position`.
+     *
+     * The offset is measured against the SAME anchor the renderer uses
+     * ({@link LinkModel.getPointAtPosition}), so `getPointAtPosition(position) +
+     * offset` reproduces the cursor by construction. Falls back to a direct
+     * polyline projection over `link.points` when the model has no segments
+     * (renderers sync `points` but leave `segments` stale). Returns null when the
+     * link has no drawable path.
+     */
+    computeLabelDragUpdate(link: LinkModel, worldPoint: Point): {
+        position: number;
+        offset: Point;
+    } | null;
+    /**
+     * Arc-length position (0-1) of the closest point on a polyline to `query`.
+     * Returns null for < 2 points. Matches the parametrization used by
+     * {@link LinkModel.getPointAtPosition}'s polyline fallback and the
+     * hit-test primitive.
+     */
+    protected closestPositionOnPolyline(points: Point[], query: Point): number | null;
+    /**
+     * Wave 2: Begin dragging label `labelIndex` of `link`.
+     */
+    startLabelDrag(link: LinkModel, labelIndex: number): void;
+    /**
+     * Wave 2: Move the dragging label to follow the cursor. Writes the remapped
+     * `{ position, offset }` back onto the model so the label survives re-routing.
+     * Returns true when a re-render is warranted.
+     */
+    moveLabelDrag(worldX: number, worldY: number): boolean;
+    /**
+     * Wave 2: End the label drag.
+     */
+    endLabelDrag(): void;
+    /**
+     * Phase 3: Handle link selection
+     * FIXED: Support multi-select with Ctrl key, deselect other links otherwise
+     */
+    selectLink(link: LinkModel, engine: DiagramEngine, multiSelect?: boolean): void;
+    /**
+     * Phase 3: Delete selected link
+     */
+    deleteSelectedLink(engine: DiagramEngine): boolean;
+    /**
+     * Find link at world position (public wrapper for hit testing)
+     * Used for direct link selection without requiring hover state
+     */
+    getLinkAtPosition(worldX: number, worldY: number, engine: DiagramEngine): LinkModel | null;
+    /**
+     * Part-aware public wrapper: like {@link getLinkAtPosition} but also reports
+     * WHICH sub-part of the link was hit (body / label / endpoint / arrow) plus
+     * local info. Foundation for later edge cards (label editing, endpoint
+     * reconnection, edge toolbar placement).
+     */
+    getLinkHitAtPosition(worldX: number, worldY: number, engine: DiagramEngine): LinkPartHit | null;
+    /**
+     * Phase 3: Get current interaction state
+     */
+    getState(): {
+        isConnecting: boolean;
+        isReconnectingLink: boolean;
+        reconnectingEndpoint: "source" | "target" | null;
+        reconnectingLink: LinkModel | null;
+        hoveredNode: NodeModel | null;
+        hoveredPort: PortModel | null;
+        hoveredLink: LinkModel | null;
+        isDraggingLabel: boolean;
+        editingLabelLink: LinkModel | null;
+        editingLabelIndex: number | null;
+        isDraggingWaypoint: boolean;
+        editingLink: LinkModel | null;
+        editingWaypointIndex: number | null;
+        hoveredWaypointIndex: number | null;
+        hoveredWaypointLink: LinkModel | null;
+        isDraggingControlPoint: boolean;
+        editingControlPointLink: LinkModel | null;
+        editingControlPointSegmentIndex: number | null;
+        editingControlPointType: "control1" | "control2" | null;
+        hoveredControlPointSegmentIndex: number | null;
+        hoveredControlPointType: "control1" | "control2" | null;
+        hoveredControlPointLink: LinkModel | null;
+    };
+    /**
+     * Phase 3: Check if currently interacting
+     */
+    isInteracting(): boolean;
+    /**
+     * Phase 3: Get appropriate cursor for current state
+     */
+    getCursor(engine: DiagramEngine): string;
+    /**
+     * Find port at world position
+     * Phase 5: Optimized with performance monitoring and early exit
+     * CRITICAL FIX: Accept engine parameter instead of calling diagram.getEngine()
+     */
+    protected findPortAtPosition(worldX: number, worldY: number, diagram: any, engine: DiagramEngine): PortModel | null;
+    /**
+     * Find link at world position.
+     *
+     * Backward-compatible thin wrapper over {@link findLinkHitAtPosition}:
+     * existing callers that only ask "which link (if any) is under the cursor?"
+     * keep getting a `LinkModel | null`. Use `findLinkHitAtPosition` /
+     * `getLinkHitAtPosition` when you need to know WHICH sub-part was hit.
+     */
+    protected findLinkAtPosition(worldX: number, worldY: number, diagram: any): LinkModel | null;
+    /**
+     * Part-aware link hit-test.
+     *
+     * Reports the link under the cursor AND which sub-part of it was hit
+     * (body / label / source|target-endpoint / source|target-arrow) plus local
+     * info: the label index for label hits, or the 0-1 position `t` along the
+     * path for body hits. Delegates the geometry to the pure `hitTestLink`
+     * primitive in `@grafloria/renderer` so the same logic backs both hit paths.
+     */
+    findLinkHitAtPosition(worldX: number, worldY: number, diagram: any): LinkPartHit | null;
+    /**
+     * The link's resolved numeric stroke width, mirroring the SVG renderer's
+     * `linkPaintLiterals` fallback: a theme-bound `var(--…)` width is not a
+     * number, so it falls back to 2 (the theme default) rather than NaN-ing the
+     * grab distance.
+     */
+    private literalLinkStrokeWidth;
+    /**
+     * Translate a link model into the framework-agnostic geometry the pure
+     * `hitTestLink` primitive expects (routed points, label placements and
+     * endpoint / arrowhead anchors). Endpoints default to the path ends inside
+     * the primitive; arrowhead anchors are inset from those ends by the arrow's
+     * canonical tip offset so they line up with the rendered markers.
+     */
+    protected buildLinkHitOptions(link: LinkModel): LinkHitTestOptions;
+    /**
+     * Anchor point for an arrowhead hit region: the terminal point moved inward
+     * along the last (or first) segment by the arrow's tip offset, matching where
+     * the marker actually sits. Returns null when there is no visible arrow.
+     */
+    protected arrowAnchor(points: Point[], atTarget: boolean, style: ArrowStyle | undefined): Point | null;
+    /**
+     * Wave 6 (Card 6): the nearest VALID target port within the magnet radius.
+     *
+     * "Valid" means the connection manager's valid-target set — the same set the
+     * highlight paints — so the magnet can never latch onto a port the drop would
+     * then reject. Returns null when nothing is in reach, leaving the drag free.
+     */
+    protected findMagnetPort(worldX: number, worldY: number, engine: DiagramEngine): PortModel | null;
+    /**
+     * Update port highlight states during connection.
+     *
+     * Wave 6 (Card 6): this method was already correct — and already dead. It
+     * loops over `dragState.validTargetPorts`, a set that NOTHING ever filled:
+     * `ConnectionStateManager.calculateValidTargets()` was a comment-only stub and
+     * `setValidTargets()` had no production caller. So the loop ran zero times,
+     * every frame, and only the hovered port ever lit up. The manager now computes
+     * the set for real, which is what finally brings this to life — plus the
+     * `highlightValidTargets` config flag, itself dead config until now (declared,
+     * defaulted true, written by the config panel, read by nobody).
+     */
+    protected updatePortHighlights(engine: DiagramEngine): void;
+    /**
+     * Clear all port highlights
+     */
+    protected clearPortHighlights(engine: DiagramEngine): void;
+    /**
+     * Find port by ID
+     */
+    protected findPortById(portId: string, diagram: any): PortModel | null;
+    /**
+     * Find node that owns a port
+     */
+    protected findNodeForPort(portId: string, diagram: any): NodeModel | undefined;
+    /**
+     * Hit test for waypoint handle at mouse position
+     * Returns the waypoint index if hit, null otherwise
+     */
+    hitTestWaypoint(mouseX: number, mouseY: number, link: LinkModel): number | null;
+    /**
+     * Hit test for clicking on link path (to add waypoint)
+     */
+    hitTestPath(mouseX: number, mouseY: number, link: LinkModel): boolean;
+    /**
+     * Start dragging a waypoint
+     */
+    startWaypointDrag(waypointIndex: number, link: LinkModel): void;
+    /**
+     * Move waypoint during drag
+     * The waypoint is just moved, orthogonal routing happens during rendering
+     */
+    moveWaypoint(worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /**
+     * End waypoint drag
+     */
+    endWaypointDrag(engine?: DiagramEngine): void;
+    /**
+     * Add waypoint at click position on path
+     */
+    addWaypoint(clickX: number, clickY: number, link: LinkModel): boolean;
+    /**
+     * Remove waypoint at index
+     */
+    removeWaypoint(waypointIndex: number, link: LinkModel): boolean;
+    /**
+     * Update waypoint editor configuration
+     */
+    updateWaypointEditorConfig(config: Partial<any>): void;
+    /**
+     * Synchronize editor configs with engine interaction config
+     * ADDED: Call this when engine config changes to update editor visuals
+     */
+    syncWithEngineConfig(engine: DiagramEngine): void;
+    /**
+     * ==========================================================================
+     * wave10/gallery BUG FIX — `registerConnectionValidator` did not veto a DRAG.
+     * ==========================================================================
+     *
+     * `ext/tools.ts` documents its registry as: "Validators registered here are
+     * consulted wherever the renderer offers a connection", and its whole reason
+     * for existing is that "a HOST had no way to inject 'an Order may not connect
+     * to an Invoice'".
+     *
+     * It was consulted in exactly ONE place: `canConnectPorts()` in snapping.ts —
+     * i.e. proximity-connect and keyboard-connect. The MOUSE DRAG, which is how
+     * essentially every connection in every diagram ever made actually gets made,
+     * never asked. You could register a validator that rejected every connection
+     * in the graph, drag from a port to a port, and get the link.
+     *
+     * The engine has its own validator list on `ConnectionStateManager` — which
+     * the drag DOES consult, and which also feeds `calculateValidTargets()`, so a
+     * veto registered there also dims the invalid ports during the drag. So the
+     * fix is a bridge, not a second enforcement point: forward the host registry
+     * into the engine's list, once per engine. With no validators registered
+     * `isValidConnection()` returns `{ valid: true }`, so the bridge costs a
+     * function call on a path that is already doing a hit-test.
+     */
+    private validatorBridgedEngines;
+    private installHostConnectionValidatorBridge;
+    /**
+     * Update hovered waypoint (for Delete key support)
+     * Call this from mousemove to track which waypoint is under cursor
+     */
+    updateHoveredWaypoint(worldX: number, worldY: number, link: LinkModel | null): void;
+    /**
+     * Delete currently hovered waypoint (for Delete key)
+     */
+    deleteHoveredWaypoint(): boolean;
+    /**
+     * Hit test for control point handle at mouse position
+     * Returns the control point info if hit, null otherwise
+     */
+    hitTestControlPoint(mouseX: number, mouseY: number, link: LinkModel): {
+        segmentIndex: number;
+        controlType: 'control1' | 'control2';
+    } | null;
+    /**
+     * Start dragging a control point
+     */
+    startControlPointDrag(segmentIndex: number, controlType: 'control1' | 'control2', link: LinkModel): void;
+    /**
+     * Move control point during drag
+     */
+    moveControlPoint(worldX: number, worldY: number, engine: DiagramEngine): boolean;
+    /**
+     * End control point drag
+     */
+    endControlPointDrag(): void;
+    /**
+     * Update control point editor configuration
+     */
+    updateControlPointEditorConfig(config: Partial<any>): void;
+    /**
+     * Update hovered control point (for Delete key support)
+     * Call this from mousemove to track which control point is under cursor
+     */
+    updateHoveredControlPoint(worldX: number, worldY: number, link: LinkModel | null): void;
+    /**
+     * Reset control point to auto-generated position (for Delete key)
+     * This removes custom control point adjustment, reverting to default bezier
+     */
+    resetHoveredControlPoint(): boolean;
+}