@grafloria/element 0.3.20 → 0.3.21

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

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