@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/interaction/selection-tools.d.ts

@@ -0,0 +1,343 @@
+import type { DiagramEngine, NodeModel, LinkModel, Point, Command } from '@grafloria/engine';
+import type { Rectangle } from '../types/geometry.types';
+import { type NodeSizing } from '../svg/node-sizing';
+import { type ToolbarResolver } from '../svg/node-toolbar';
+/**
+ * SelectionToolsController — the floating tool layer (Card 5, wave4/interaction).
+ *
+ * Everything a user can grab AROUND a selection lives here: the 8 resize
+ * handles, the rotate handle, the remove button, the Halo context toolbar
+ * (connect / clone / fork / delete), and — for links — the endpoint reconnect
+ * anchors and the add/remove-vertex tools.
+ *
+ * ## Framework contract (same as InteractionController)
+ *
+ * This class answers "**what tools exist right now, where, and what does
+ * grabbing one DO?**". It never renders and never re-renders: it emits plain
+ * geometry ({@link SelectionToolLayer}) that any host can draw, and it returns
+ * {@link Command}s that the host dispatches on the engine's CommandManager. Zero
+ * framework imports; instantiate with a plain `new`.
+ *
+ * ## Coordinates
+ *
+ * All handle positions are WORLD coordinates, because the host already owns the
+ * world→screen map (ViewportController) and the model lives in world space. Sizes
+ * the user perceives (handle size, halo gap) are configured in SCREEN px and
+ * divided by `zoom` when the layer is computed, so handles keep a constant
+ * on-screen size at any zoom — the JointJS/GoJS behaviour.
+ *
+ * ## Rotation
+ *
+ * A node renders as `translate(pos) rotate(θ, w/2, h/2)`, i.e. rotation about the
+ * box CENTRE. The tool layer applies the same rotation to every handle, so the
+ * handles stay glued to a rotated node's corners, and a resize drag is
+ * transformed back into the node's local frame before it is applied
+ * ({@link applyResizeToNode}) — with the centre-compensation that keeps the
+ * unresized edge visually still.
+ */
+/** The 8 resize handles, named by compass direction. */
+export type ResizeHandleId = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+/** Halo (context toolbar) actions, JointJS+-style. */
+export type HaloAction = 'connect' | 'clone' | 'fork' | 'delete';
+export type ToolKind = 'resize' | 'rotate' | 'remove' | 'halo' | 'link-endpoint' | 'vertex-add' | 'vertex-remove';
+/** One grabbable tool in the floating layer. */
+export interface ToolHandle {
+    /** Stable key (also the DOM key a host keys its @for/map on). */
+    id: string;
+    kind: ToolKind;
+    /** Centre of the handle, in WORLD coordinates. */
+    world: Point;
+    /** Hit radius in WORLD units (= screen px / zoom). */
+    hitRadius: number;
+    /**
+     * resize-ux: for the four SIDE resize handles (n/e/s/w), the full edge they
+     * own, as a WORLD segment (rotated with the node). React Flow's side
+     * affordance is the whole border line, not a midpoint dot — the live audit
+     * found the 6px dots unreachable (fully inside the port's hover halo), so a
+     * side handle hit-tests as a BAND around this segment: grab the border
+     * anywhere and that edge follows. `world` stays the midpoint for hosts that
+     * draw dots. Corner handles never carry a segment.
+     */
+    segment?: {
+        a: Point;
+        b: Point;
+    };
+    /** CSS cursor a host should show over this handle. */
+    cursor: string;
+    /** Accessible name (also used for tooltips / ARIA). */
+    label: string;
+    /** For `resize`. */
+    handleId?: ResizeHandleId;
+    /** For `halo`. */
+    action?: HaloAction;
+    /** For `link-endpoint`. */
+    endpoint?: 'source' | 'target';
+    /** Vertex index (`vertex-remove`) or segment index (`vertex-add`). */
+    index?: number;
+    /** Owning entity. */
+    nodeId?: string;
+    linkId?: string;
+}
+/** Everything the host needs to draw the tool layer for the current selection. */
+export interface SelectionToolLayer {
+    /** World bbox of the selection; null when nothing is selected. */
+    bounds: Rectangle | null;
+    /** Rotation (deg) of the single selected node; 0 otherwise. */
+    rotation: number;
+    /** World centre the bounds rotate about (the frame outline follows it). */
+    center: Point | null;
+    nodeIds: string[];
+    linkIds: string[];
+    handles: ToolHandle[];
+}
+export interface SelectionToolsConfig {
+    /** Side of a square resize handle, in SCREEN px. */
+    handleSize: number;
+    /** Distance from the selection's top edge to the rotate handle, SCREEN px. */
+    rotateHandleOffset: number;
+    /** Gap between the selection box and the halo column, SCREEN px. */
+    haloGap: number;
+    /** Diameter of a halo button, SCREEN px. */
+    haloButtonSize: number;
+    /** Show the Halo context toolbar. */
+    showHalo: boolean;
+    /** Show the 8 resize handles (single-node selection only). */
+    showResizeHandles: boolean;
+    /** Show the rotate handle (single-node selection, `behavior.rotatable`). */
+    showRotateHandle: boolean;
+    /** Show the ✕ remove button. */
+    showRemoveButton: boolean;
+    /** Show link endpoint / vertex tools for a selected link. */
+    showLinkTools: boolean;
+    /** Smallest width/height a resize may produce, WORLD units. */
+    minWidth: number;
+    minHeight: number;
+    /** Rotation snap while a modifier is held, in degrees. */
+    rotationSnapDegrees: number;
+    /**
+     * Per-TYPE toolbar policy (Card 6). Layered on top of each node's own
+     * `metadata.toolbar`; lets a host decide which tools a node type exposes
+     * without touching per-node data. Omit for "every tool, every node".
+     */
+    resolveNodeToolbar?: ToolbarResolver;
+}
+export declare const DEFAULT_SELECTION_TOOLS_CONFIG: SelectionToolsConfig;
+export declare const RESIZE_HANDLE_IDS: ResizeHandleId[];
+/**
+ * resize-ux: the ONE side-handle-vs-port priority predicate.
+ *
+ * The four side handles live ON the node border, where the default side ports
+ * also live. React Flow resolves the coincidence by z-order: the port glyph
+ * (drawn on top of the resize line) wins its own core, the line wins the rest
+ * of the edge. Ours is the same rule expressed in hover state: when the pointer
+ * is inside a port's grab radius (`hoveredPort` is set) on the SAME node, the
+ * port claims the press/cursor; everywhere else along the band, resize does.
+ *
+ * Exported so the mouse ladder, the touch ladder AND the hover-cursor logic
+ * share one predicate — three private copies is how they drift.
+ */
+export declare function sideHandleYieldsToPort(handle: ToolHandle, hoveredPort: {
+    nodeId?: string;
+} | null | undefined): boolean;
+/** Rotate `(x, y)` about the origin by `deg` degrees (SVG's positive = clockwise). */
+export declare function rotateVector(x: number, y: number, deg: number): Point;
+/** Rotate `point` about `center` by `deg` degrees. */
+export declare function rotatePoint(point: Point, center: Point, deg: number): Point;
+export interface ResizeOptions {
+    minWidth?: number;
+    minHeight?: number;
+    /** Upper bound on the dragged size, clamped DURING the gesture. Default ∞. */
+    maxWidth?: number;
+    maxHeight?: number;
+    /** Preserve the starting aspect ratio (corner handles only). */
+    keepAspect?: boolean;
+    /**
+     * Explicit width÷height ratio to lock to (corner handles only). Set by a
+     * per-node aspect lock; overrides the start ratio and implies keepAspect.
+     */
+    aspect?: number;
+}
+/**
+ * Apply a resize drag to a box, in the box's OWN frame.
+ *
+ * `dx/dy` is the pointer delta since the drag began (same frame as the box). The
+ * dragged edge(s) follow the pointer; the opposite edge stays put. Min/max clamp
+ * the DRAGGED edge, never the anchored one — so a runaway drag can neither flip
+ * nor shrink past the minimum nor grow past the maximum, all mid-gesture.
+ */
+export declare function resizeBox(start: Rectangle, handle: ResizeHandleId, dx: number, dy: number, options?: ResizeOptions): Rectangle;
+/**
+ * Apply a resize drag to a possibly-ROTATED node.
+ *
+ * The pointer delta arrives in WORLD space, but the box the user is resizing is
+ * drawn in the node's local (unrotated) frame and rotated about its centre. So:
+ *
+ *  1. rotate the world delta by −θ → the node's local frame;
+ *  2. resize the local box;
+ *  3. the node re-renders rotated about its NEW centre, so compensate the
+ *     position by rotating the centre shift back into world space.
+ *
+ * At θ = 0 this collapses to `pos + (box.x, box.y)`. Getting step 3 wrong is what
+ * makes rotated resize "swim" away from the cursor in most implementations.
+ */
+export declare function applyResizeToNode(start: {
+    position: Point;
+    size: {
+        width: number;
+        height: number;
+    };
+    rotation: number;
+}, handle: ResizeHandleId, worldDx: number, worldDy: number, options?: ResizeOptions): {
+    position: Point;
+    size: {
+        width: number;
+        height: number;
+    };
+};
+/** Angle (deg) of `point` seen from `center`; 0° = straight up, growing clockwise. */
+export declare function angleAt(center: Point, point: Point): number;
+/** Fold an angle into [0, 360). */
+export declare function normalizeAngle(deg: number): number;
+/** Snap `deg` to the nearest multiple of `step` (step ≤ 0 → unchanged). */
+export declare function snapAngle(deg: number, step: number): number;
+interface ResizeGesture {
+    kind: 'resize';
+    nodeId: string;
+    handle: ResizeHandleId;
+    startPointer: Point;
+    startPosition: Point;
+    startSize: {
+        width: number;
+        height: number;
+    };
+    startRotation: number;
+    /** The node's sizing config at gesture start (min/max/aspect), read once. */
+    sizing: NodeSizing;
+    /**
+     * The `sizing.auto` flag before the gesture pinned it off, so cancel can
+     * restore it. `undefined` when the node was not auto-sized.
+     */
+    pinnedAuto?: boolean;
+}
+interface RotateGesture {
+    kind: 'rotate';
+    nodeId: string;
+    center: Point;
+    startRotation: number;
+    /** Pointer angle when the gesture began — rotation is relative to it. */
+    startAngle: number;
+}
+interface VertexGesture {
+    kind: 'vertex';
+    linkId: string;
+    index: number;
+    startPoints: Point[];
+}
+type ToolGesture = ResizeGesture | RotateGesture | VertexGesture;
+/** Modifier snapshot a host forwards from its pointer events. */
+export interface ToolModifierState {
+    shift?: boolean;
+    alt?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+}
+export declare class SelectionToolsController {
+    protected config: SelectionToolsConfig;
+    protected gesture: ToolGesture | null;
+    constructor(config?: Partial<SelectionToolsConfig>);
+    getConfig(): SelectionToolsConfig;
+    updateConfig(patch: Partial<SelectionToolsConfig>): void;
+    /** True while a resize / rotate / vertex drag owns the pointer. */
+    isActive(): boolean;
+    /** The kind of gesture in flight (`null` when idle) — hosts branch on it. */
+    activeGesture(): 'resize' | 'rotate' | 'vertex' | null;
+    /** The node the in-flight gesture is acting on (`null` when idle). Lets a host
+     *  exclude it from a snap's sibling set — a box must not snap to itself. */
+    activeGestureNodeId(): string | null;
+    /**
+     * Compute the tool layer for the CURRENT selection.
+     *
+     * `zoom` converts the screen-px sizes in the config into world units, so the
+     * handles are the same physical size at every zoom level.
+     *
+     * Scope note (deliberate): resize + rotate are offered for a SINGLE selected
+     * node. A multi-node selection gets the bounding frame, the halo and the remove
+     * button — proportional multi-node resize is not implemented.
+     */
+    computeLayer(engine: DiagramEngine, zoom?: number): SelectionToolLayer;
+    /** Link tools: endpoint reconnect anchors, add/remove-vertex, remove. */
+    protected computeLinkLayer(links: LinkModel[], scale: number): SelectionToolLayer;
+    /**
+     * Which tool (if any) is under a world point.
+     *
+     * Later handles win ties, so the halo/remove buttons (emitted last) stay
+     * clickable where they overlap a resize handle.
+     *
+     * resize-ux: a handle that carries a `segment` (the four side resize handles)
+     * hit-tests as a BAND around that segment — the whole edge is grabbable, the
+     * React Flow line behaviour. POINT handles always beat bands: the corner dots
+     * sit exactly where two bands end, and the dot must win its own pixel (RF
+     * draws the dots on top of the lines for the same reason). Halo/remove/rotate
+     * are point handles, so their priority over resize is unchanged.
+     */
+    hitTest(layer: SelectionToolLayer, worldX: number, worldY: number): ToolHandle | null;
+    /**
+     * resize-ux: the RESIZE handle under a world point, with optional extra grab
+     * slop (world units). One entry point for the mouse ladder (slop 0) and the
+     * touch ladder (finger-sized slop), so bands and dots grow identically.
+     */
+    hitTestResize(layer: SelectionToolLayer, worldX: number, worldY: number, slop?: number): ToolHandle | null;
+    private hitHandles;
+    /** World bbox of a node set. */
+    protected unionBounds(nodes: NodeModel[]): Rectangle | null;
+    /** Arm a resize. Returns false when the handle/node is not resizable. */
+    beginResize(handle: ToolHandle, engine: DiagramEngine, worldX: number, worldY: number): boolean;
+    /**
+     * Live-resize the node (direct model mutation, like the drag tool: smooth, no
+     * command churn — the single undo entry is minted at {@link endGesture}).
+     * `snap` optionally quantises the resulting box (grid / alignment) — the host
+     * passes the SnapController's hook so Card 6 composes with Card 5.
+     */
+    updateResize(engine: DiagramEngine, worldX: number, worldY: number, modifiers?: ToolModifierState, snap?: (box: Rectangle) => Rectangle): boolean;
+    beginRotate(handle: ToolHandle, engine: DiagramEngine, worldX: number, worldY: number): boolean;
+    /** Live-rotate; Shift snaps to `rotationSnapDegrees`. */
+    updateRotate(engine: DiagramEngine, worldX: number, worldY: number, modifiers?: ToolModifierState): boolean;
+    beginVertexDrag(handle: ToolHandle, engine: DiagramEngine): boolean;
+    updateVertexDrag(engine: DiagramEngine, worldX: number, worldY: number, snapPoint?: (p: Point) => Point): boolean;
+    /**
+     * End the active gesture and return the ONE command that makes it undoable
+     * (null for a no-op gesture). The model already sits at its final state — the
+     * command re-applies it (a no-op) and records the inverse, exactly like the
+     * wave-3 node-drag commit.
+     */
+    endGesture(engine: DiagramEngine): Command | null;
+    /** Abandon the gesture, restoring the model to its pre-gesture state. */
+    cancelGesture(engine: DiagramEngine): void;
+    /** Insert a vertex at the clicked segment midpoint. Undoable. */
+    addVertexCommand(handle: ToolHandle, engine: DiagramEngine): Command | null;
+    /** Remove the vertex under the tool. Undoable. */
+    removeVertexCommand(handle: ToolHandle, engine: DiagramEngine): Command | null;
+    /**
+     * The command behind a remove button / halo `delete`: drop the whole selection
+     * (every selected node AND link) in ONE undo step.
+     */
+    removeSelectionCommand(engine: DiagramEngine): Command | null;
+    /**
+     * Halo `clone`: a copy of the node, offset, as one undoable AddNodeCommand.
+     * Ports get fresh ids (via the engine's shared {@link remapNodePortIds}) so the
+     * clone never shares port identity with its source — the bug paste/duplicate
+     * already learned.
+     */
+    cloneNodeCommand(engine: DiagramEngine, nodeId: string, offset?: Point): Command | null;
+    /**
+     * Halo `fork`: clone the node AND link the original to the clone — one undo
+     * step (MacroCommand). The link runs from an output-capable port on the source
+     * to an input-capable port on the clone; null when either side has no usable port.
+     */
+    forkNodeCommand(engine: DiagramEngine, nodeId: string, offset?: Point): Command | null;
+    /** Deserialize → re-id → offset. Shared by clone + fork. */
+    protected buildClone(engine: DiagramEngine, nodeId: string, offset: Point): {
+        node: NodeModel;
+    } | null;
+}
+export {};