@grafloria/element 0.3.20 → 0.3.22

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

@@ -1,210 +0,0 @@
-import type { DiagramEngine, NodeModel, LinkModel, Point, Command } from '@grafloria/engine';
-import { PortModel } from '@grafloria/engine';
-import type { Rectangle } from '../types/geometry.types';
-/**
- * SnapController — alignment snaplines, equal-spacing guides, grid snap,
- * keep-in-bounds, magnetic snap-to-port and proximity connect (Card 6,
- * wave4/interaction).
- *
- * Framework-agnostic and pure w.r.t. the geometry it is handed: `computeSnap`
- * takes the moving box + the boxes it may align to and returns the corrected box
- * PLUS the guides a host should draw. Nothing here renders, and nothing mutates
- * the model — except the explicit port-highlight helper, which sets the same
- * `isHighlighted` / `isValidTarget` flags the renderer already draws for
- * connection dragging.
- *
- * Everything is measured in WORLD units. Hosts that want a constant on-screen
- * feel pass `snapThreshold: px / zoom` (see `DiagramCanvasComponent`).
- */
-export interface SnapConfig {
-    /** Master switch for alignment snaplines + equal spacing. */
-    enabled: boolean;
-    /** Quantise the box to a grid (applied when no alignment guide claims an axis). */
-    snapToGrid: boolean;
-    gridSize: number;
-    /** Distance (world units) within which an alignment candidate snaps. */
-    snapThreshold: number;
-    /** Emit equal-spacing guides (Figma/GoJS-style distribution hints). */
-    equalSpacing: boolean;
-    /** World rectangle the moving box must stay inside (null = unbounded). */
-    keepInBounds: Rectangle | null;
-    /** Magnetic port radius — the engine's `snapToPortRadius` lives here. */
-    snapToPortRadius: number;
-    /** Drop-a-node-near-a-port auto-link radius (React-Flow proximity connect). */
-    proximityConnectRadius: number;
-}
-export declare const DEFAULT_SNAP_CONFIG: SnapConfig;
-/** A single alignment snapline. `position` is the aligned coordinate. */
-export interface AlignmentGuide {
-    orientation: 'vertical' | 'horizontal';
-    /** World x (vertical guide) or world y (horizontal guide). */
-    position: number;
-    /** Extent of the drawn line along the other axis. */
-    from: number;
-    to: number;
-    kind: 'edge' | 'center';
-}
-/** An equal-spacing hint: two or more equal gaps, each with a distance label. */
-export interface SpacingGuide {
-    orientation: 'horizontal' | 'vertical';
-    /** The equal gap, in world units. */
-    gap: number;
-    /** Human label the host draws at the segment's midpoint (e.g. "40"). */
-    label: string;
-    /** The measured gaps, as segments to draw. */
-    segments: Array<{
-        x1: number;
-        y1: number;
-        x2: number;
-        y2: number;
-    }>;
-}
-export interface SnapResult {
-    /** The corrected box (grid / alignment / spacing / bounds applied). */
-    box: Rectangle;
-    /** Correction applied to the input box. */
-    dx: number;
-    dy: number;
-    guides: AlignmentGuide[];
-    spacing: SpacingGuide[];
-}
-/** A port the magnet found, with its owner. */
-export interface PortHit {
-    port: PortModel;
-    node: NodeModel;
-    /** World position of the port. */
-    position: Point;
-    distance: number;
-}
-/** A proximity-connect candidate: link `source` → `target` if the user drops here. */
-export interface ProximityCandidate {
-    sourcePort: PortModel;
-    targetPort: PortModel;
-    sourceNodeId: string;
-    targetNodeId: string;
-    distance: number;
-}
-/**
- * Can ports `a` (on `nodeA`) and `b` (on `nodeB`) be linked?
- *
- * The ONE rule shared by proximity connect (Card 6) and keyboard connect
- * (Card 7), so the two can never disagree about what is legal.
- *
- * Wave 6: it no longer OWNS that rule — it delegates to
- * `evaluatePortConnection`, the engine-side validator the connection drag also
- * runs through. Before wave 6 this function was one of THREE disagreeing copies
- * (the others: `PortModel.canConnectTo` and
- * `ConnectionStateManager.isValidConnection`), and the drift was real: this one
- * rejected duplicates and honoured `node.behavior.connectable`, the drag checked
- * neither; the drag ignored `maxConnections`, this one never heard of it. A port
- * you could legally drag to was one the magnet refused to snap to.
- *
- * `rejectDuplicatesByDefault` preserves this call site's own historical stance:
- * auto-linking a duplicate because a node drifted near is never what the user
- * meant, whatever the port's `allowDuplicateLinks` says.
- *
- * Note the argument order: `a` is the SOURCE. The rule is directional, and the
- * proximity search calls it once per orientation.
- */
-export declare function canConnectPorts(a: PortModel, b: PortModel, nodeA: NodeModel, nodeB: NodeModel, engine: DiagramEngine, diagram: {
-    getLinks(): LinkModel[];
-}): boolean;
-export declare class SnapController {
-    protected config: SnapConfig;
-    constructor(config?: Partial<SnapConfig>);
-    getConfig(): SnapConfig;
-    updateConfig(patch: Partial<SnapConfig>): void;
-    /**
-     * Read the snapping knobs off the engine's interaction config.
-     *
-     * `snapToPortRadius` has existed in `InteractionConfig` since the first
-     * interaction phase and was read by NOTHING — the config panel wrote it, the
-     * default was 30, and no code path ever consulted it. This is the seam that
-     * finally consumes it (see {@link findPortMagnet} / {@link findProximityConnection}),
-     * along with the waypoint editor's grid settings.
-     */
-    syncWithEngineConfig(engine: DiagramEngine): void;
-    /**
-     * Snap `box` against `others`.
-     *
-     * Precedence per axis (strongest first):
-     *   1. alignment snapline (edge/centre) within `snapThreshold`
-     *   2. equal-spacing guide within `snapThreshold`
-     *   3. grid
-     * then keep-in-bounds clamps whatever survived. Precedence matters: a grid snap
-     * that fought an alignment snap would visibly jitter between the two.
-     */
-    computeSnap(box: Rectangle, others: Rectangle[]): SnapResult;
-    /** Quantise a single point to the grid (used by the vertex drag). */
-    snapPointToGrid(point: Point): Point;
-    /** Clamp a box so it stays fully inside `bounds` (no-op when it cannot fit). */
-    keepInBounds(box: Rectangle, bounds: Rectangle): Rectangle;
-    /** Best edge/centre alignment on one axis. */
-    protected bestAlignment(box: Rectangle, others: Rectangle[], axis: 'x' | 'y'): {
-        delta: number;
-        guides: AlignmentGuide[];
-    } | null;
-    /** Does `rect` have an edge or centre exactly on `position` (on `axis`)? */
-    protected touchesLine(rect: Rectangle, position: number, axis: 'x' | 'y'): boolean;
-    /**
-     * Equal-spacing snap on one axis.
-     *
-     * Two patterns, both classic:
-     *  - BETWEEN: the moving box lands between two neighbours with equal gaps.
-     *  - CHAIN:   an existing pair already has gap `g`; the moving box lands one
-     *             gap `g` further along, continuing the rhythm.
-     */
-    protected bestSpacing(box: Rectangle, others: Rectangle[], axis: 'x' | 'y'): {
-        delta: number;
-        guide: SpacingGuide;
-    } | null;
-    /** Build the drawable gap segments between consecutive boxes, sorted along `axis`. */
-    protected buildSpacingGuide(boxes: Rectangle[], gap: number, axis: 'x' | 'y'): SpacingGuide;
-    protected overlapsOnOtherAxis(a: Rectangle, b: Rectangle, axis: 'x' | 'y'): boolean;
-    /** World bounding boxes of every node EXCEPT `excludeIds` (the moving ones). */
-    siblingBoxes(engine: DiagramEngine, excludeIds?: Iterable<string>): Rectangle[];
-    /**
-     * World position of a port — THE one the port is actually drawn at.
-     *
-     * BUG (wave 6): this used `port.getAbsolutePosition(node.getBoundingBox())`,
-     * which walks the BOUNDING BOX and lands on an edge midpoint — blind to the
-     * node's silhouette and to how many ports share the side. The renderer draws
-     * ports with `getPortPositionForShape`. So on a circle, a diamond, a hexagon,
-     * a cylinder — or ANY side carrying more than one port — the magnet was
-     * snapping to a point several pixels away from the port you could see, and
-     * proximity-connect measured its radius from the wrong place.
-     */
-    portPosition(node: NodeModel, port: PortModel): Point;
-    /**
-     * The nearest port to a world point within `snapToPortRadius` — the magnet the
-     * connection drag snaps to. `excludeNodeId` keeps a drag from snapping back to
-     * the node it started on.
-     */
-    findPortMagnet(engine: DiagramEngine, worldX: number, worldY: number, options?: {
-        excludeNodeId?: string;
-        radius?: number;
-        filter?: (port: PortModel, node: NodeModel) => boolean;
-    }): PortHit | null;
-    /**
-     * React-Flow-style proximity connect: after dragging `nodeId`, is one of ITS
-     * ports close enough to a compatible port on another node to auto-link them?
-     *
-     * Validity is the same rule the connection drag enforces: different nodes,
-     * direction-compatible ports (output→input, or a `bi` port on either side),
-     * allowed by the connection groups, and not already connected.
-     */
-    findProximityConnection(engine: DiagramEngine, nodeId: string, radius?: number): ProximityCandidate | null;
-    /** The connection rule shared by the magnet, the highlight and the auto-link. */
-    protected canConnect(a: PortModel, b: PortModel, nodeA: NodeModel, nodeB: NodeModel, engine: DiagramEngine, diagram: {
-        getLinks(): LinkModel[];
-    }): boolean;
-    /** Turn a candidate into the ONE undoable command that creates the link. */
-    buildProximityLinkCommand(candidate: ProximityCandidate): Command;
-    /**
-     * Paint the nearest valid target: exactly the flags the SVG renderer already
-     * draws for a connection drag (`isValidTarget` = eligible, `isHighlighted` =
-     * the one that would win). Clears every other port so the highlight can never
-     * go stale — the failure mode of "highlight on, nothing turns it off".
-     */
-    highlightProximityTarget(engine: DiagramEngine, candidate: ProximityCandidate | null): void;
-}