@grafloria/element 0.3.20 → 0.3.21

package/src/libs/renderer/src/interaction/keyboard-navigation.js

@@ -1,885 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyboardNavigationController = exports.DEFAULT_KEYBOARD_NAV_CONFIG = void 0;
-const engine_1 = require("@grafloria/engine");
-const snapping_1 = require("./snapping");
-// wave6/a11y: the graph-aware half of navigation. Focus is a keyboard concern,
-// but "where can I go from here" is a TOPOLOGY question — so it is answered by
-// the a11y module's pure analysis, not re-derived here.
-const semantics_1 = require("../a11y/semantics");
-const graph_topology_1 = require("../a11y/graph-topology");
-const diagram_outline_1 = require("../a11y/diagram-outline");
-exports.DEFAULT_KEYBOARD_NAV_CONFIG = {
-    nudgeStep: 1,
-    coarseNudgeStep: 10,
-    wrapFocus: true,
-    focusRingPadding: 6,
-};
-class KeyboardNavigationController {
-    constructor(config = {}) {
-        this.focused = null;
-        this.connectState = null;
-        this.listeners = new Set();
-        this.lastAnnouncement = null;
-        this.seq = 0;
-        this.config = Object.assign(Object.assign({}, exports.DEFAULT_KEYBOARD_NAV_CONFIG), config);
-    }
-    getConfig() {
-        return Object.assign({}, this.config);
-    }
-    updateConfig(patch) {
-        this.config = Object.assign(Object.assign({}, this.config), patch);
-    }
-    // ==========================================================================
-    // Focus order + movement
-    // ==========================================================================
-    /**
-     * Tab order: nodes in reading order (top-to-bottom, then left-to-right), then
-     * links ordered by their source node's place in that same order — so tabbing
-     * walks the structure the way a sighted user reads it.
-     */
-    getFocusOrder(engine) {
-        var _a;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return [];
-        const nodes = diagram.getNodes()
-            .filter((n) => { var _a, _b; return ((_a = n.state) === null || _a === void 0 ? void 0 : _a.visible) !== false && ((_b = n.behavior) === null || _b === void 0 ? void 0 : _b.selectable) !== false; })
-            .sort((a, b) => {
-            const ay = a.getBoundingBox().top;
-            const by = b.getBoundingBox().top;
-            if (Math.abs(ay - by) > 1)
-                return ay - by;
-            return a.getBoundingBox().left - b.getBoundingBox().left;
-        });
-        const rank = new Map();
-        nodes.forEach((node, i) => rank.set(node.id, i));
-        const links = diagram.getLinks().slice().sort((a, b) => {
-            var _a, _b;
-            const ar = (_a = rank.get(this.sourceNodeIdOf(a, diagram))) !== null && _a !== void 0 ? _a : Number.MAX_SAFE_INTEGER;
-            const br = (_b = rank.get(this.sourceNodeIdOf(b, diagram))) !== null && _b !== void 0 ? _b : Number.MAX_SAFE_INTEGER;
-            return ar - br;
-        });
-        return [
-            ...nodes.map((n) => ({ type: 'node', id: n.id })),
-            ...links.map((l) => ({ type: 'link', id: l.id })),
-        ];
-    }
-    getFocused() {
-        return this.focused ? Object.assign({}, this.focused) : null;
-    }
-    /** Set focus (null clears it) and announce the new target. */
-    setFocus(target, engine) {
-        this.focused = target ? Object.assign({}, target) : null;
-        if (target && engine) {
-            this.announce(this.describe(engine, target));
-        }
-        return this.getFocused();
-    }
-    /** Tab. */
-    focusNext(engine) {
-        return this.step(engine, +1);
-    }
-    /** Shift+Tab. */
-    focusPrevious(engine) {
-        return this.step(engine, -1);
-    }
-    step(engine, delta) {
-        const order = this.getFocusOrder(engine);
-        if (order.length === 0)
-            return this.setFocus(null);
-        const index = this.focused
-            ? order.findIndex((t) => t.type === this.focused.type && t.id === this.focused.id)
-            : -1;
-        let next = index + delta;
-        if (index === -1) {
-            next = delta > 0 ? 0 : order.length - 1;
-        }
-        else if (next < 0 || next >= order.length) {
-            if (!this.config.wrapFocus)
-                return this.getFocused();
-            next = (next + order.length) % order.length;
-        }
-        return this.setFocus(order[next], engine);
-    }
-    /**
-     * Spatial arrow-key focus movement across NODES: pick the nearest node whose
-     * centre lies in the requested half-plane, preferring small perpendicular
-     * offset (the standard "directional focus" heuristic).
-     */
-    focusDirection(engine, direction) {
-        var _a, _b;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return this.getFocused();
-        const nodes = diagram.getNodes().filter((n) => { var _a, _b; return ((_a = n.state) === null || _a === void 0 ? void 0 : _a.visible) !== false && ((_b = n.behavior) === null || _b === void 0 ? void 0 : _b.selectable) !== false; });
-        if (nodes.length === 0)
-            return this.getFocused();
-        const current = ((_b = this.focused) === null || _b === void 0 ? void 0 : _b.type) === 'node' ? diagram.getNode(this.focused.id) : undefined;
-        if (!current) {
-            // No node focused yet → enter at the first node in reading order.
-            const order = this.getFocusOrder(engine).find((t) => t.type === 'node');
-            return order ? this.setFocus(order, engine) : this.getFocused();
-        }
-        const from = centerOf(current);
-        let best = null;
-        for (const node of nodes) {
-            if (node.id === current.id)
-                continue;
-            const to = centerOf(node);
-            const dx = to.x - from.x;
-            const dy = to.y - from.y;
-            const along = direction === 'left' ? -dx : direction === 'right' ? dx : direction === 'up' ? -dy : dy;
-            if (along <= 0)
-                continue; // wrong side
-            const across = direction === 'left' || direction === 'right' ? Math.abs(dy) : Math.abs(dx);
-            // Perpendicular drift costs double — keeps focus travelling in a straight line.
-            const score = along + across * 2;
-            if (!best || score < best.score) {
-                best = { node, score };
-            }
-        }
-        if (!best)
-            return this.getFocused();
-        return this.setFocus({ type: 'node', id: best.node.id }, engine);
-    }
-    /** The visible focus ring for the current target (null when nothing is focused). */
-    getFocusRing(engine) {
-        var _a;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        const target = this.focused;
-        if (!diagram || !target)
-            return null;
-        if (target.type === 'node') {
-            const node = diagram.getNode(target.id);
-            if (!node)
-                return null;
-            const box = node.getBoundingBox();
-            const pad = this.config.focusRingPadding;
-            return {
-                type: 'node',
-                id: node.id,
-                bounds: {
-                    x: box.left - pad,
-                    y: box.top - pad,
-                    width: box.right - box.left + pad * 2,
-                    height: box.bottom - box.top + pad * 2,
-                },
-                rotation: node.rotation || 0,
-                label: this.describe(engine, target),
-            };
-        }
-        const link = diagram.getLink(target.id);
-        if (!link || !link.points || link.points.length < 2)
-            return null;
-        return {
-            type: 'link',
-            id: link.id,
-            points: link.points.map((p) => (Object.assign({}, p))),
-            label: this.describe(engine, target),
-        };
-    }
-    /**
-     * Make the focused entity the selection (Space, or Enter on a link).
-     * Selection lives on the model, which is what the renderer draws and what the
-     * clipboard/delete commands read once the host syncs it to the store.
-     */
-    selectFocused(engine, additive = false) {
-        var _a;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        const target = this.focused;
-        if (!diagram || !target)
-            return false;
-        if (target.type === 'node') {
-            const node = diagram.getNode(target.id);
-            if (!node)
-                return false;
-            if (additive) {
-                diagram.toggleNodeSelection(node);
-            }
-            else {
-                diagram.selectNode(node);
-            }
-        }
-        else {
-            const link = diagram.getLink(target.id);
-            if (!link)
-                return false;
-            if (!additive) {
-                diagram.clearSelection();
-                diagram.getLinks().forEach((l) => {
-                    if (l.id !== link.id && l.state === 'selected')
-                        l.setState('default');
-                });
-            }
-            link.setState(link.state === 'selected' ? 'default' : 'selected');
-        }
-        this.announceSelection(engine);
-        return true;
-    }
-    // ==========================================================================
-    // wave6/a11y (card 2) — GRAPH-AWARE traversal.
-    //
-    // Wave 4 shipped SPATIAL arrow focus: "give me the nearest node to the right".
-    // That is geometry, not topology — and geometry is exactly the information a
-    // screen-reader user does not have. What they need is to walk the GRAPH:
-    // "from here, where can I go?" These methods follow real edges.
-    // ==========================================================================
-    /** The edges incident on the focused node, in a stable traversal order. */
-    incidentEdgesOfFocus(engine) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) !== 'node')
-            return [];
-        return (0, graph_topology_1.incidentEdges)(this.focused.id, diagram);
-    }
-    /**
-     * FOLLOW-EDGE NAVIGATION. From a focused node, step along its Nth incident
-     * edge to the node at the far end. From a focused EDGE, step to its endpoints.
-     *
-     * This is the move that makes a diagram traversable without sight: you are on
-     * "Is order valid?", you are told it has 2 outgoing edges, and you walk one.
-     */
-    followEdge(engine, index = 0) {
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || !this.focused)
-            return this.getFocused();
-        // On an edge: hop to the node at its far end.
-        if (this.focused.type === 'link') {
-            const link = diagram.getLink(this.focused.id);
-            if (!link)
-                return this.getFocused();
-            const targetId = index <= 0
-                ? (0, semantics_1.targetNodeIdOf)(link, diagram)
-                : (0, semantics_1.sourceNodeIdOf)(link, diagram);
-            if (!targetId || !diagram.getNode(targetId))
-                return this.getFocused();
-            return this.setFocus({ type: 'node', id: targetId }, engine);
-        }
-        const edges = (0, graph_topology_1.incidentEdges)(this.focused.id, diagram);
-        if (edges.length === 0) {
-            this.announce(`${this.nodeName(diagram.getNode(this.focused.id))} has no connections`, 'polite');
-            return this.getFocused();
-        }
-        const edge = edges[Math.max(0, Math.min(index, edges.length - 1))];
-        const next = diagram.getNode(edge.otherId);
-        if (!next)
-            return this.getFocused();
-        // Announce the EDGE we walked, then the node we landed on — otherwise the
-        // user teleports with no idea which of three branches they took.
-        this.announce(`Following ${edge.direction} edge ${index + 1} of ${edges.length}. ` +
-            `${this.describe(engine, { type: 'node', id: next.id })}`);
-        this.focused = { type: 'node', id: next.id };
-        return this.getFocused();
-    }
-    /** Walk to the Nth node this one points AT. */
-    followOutgoing(engine, index = 0) {
-        return this.followDirected(engine, 'outgoing', index);
-    }
-    /** Walk back to the Nth node that points at this one. */
-    followIncoming(engine, index = 0) {
-        return this.followDirected(engine, 'incoming', index);
-    }
-    followDirected(engine, direction, index) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) !== 'node')
-            return this.getFocused();
-        const edges = (0, graph_topology_1.incidentEdges)(this.focused.id, diagram).filter((e) => e.direction === direction);
-        if (edges.length === 0) {
-            const node = diagram.getNode(this.focused.id);
-            this.announce(`${node ? this.nodeName(node) : 'Node'} has no ${direction} connections`);
-            return this.getFocused();
-        }
-        const edge = edges[Math.max(0, Math.min(index, edges.length - 1))];
-        const next = diagram.getNode(edge.otherId);
-        if (!next)
-            return this.getFocused();
-        this.announce(`${direction} ${index + 1} of ${edges.length}. ` +
-            this.describe(engine, { type: 'node', id: next.id }));
-        this.focused = { type: 'node', id: next.id };
-        return this.getFocused();
-    }
-    /** Focus the EDGE itself (rather than jumping over it) — so it can be deleted. */
-    focusIncidentEdge(engine, index = 0) {
-        const edges = this.incidentEdgesOfFocus(engine);
-        if (edges.length === 0)
-            return this.getFocused();
-        const edge = edges[Math.max(0, Math.min(index, edges.length - 1))];
-        return this.setFocus({ type: 'link', id: edge.link.id }, engine);
-    }
-    /** Jump to the first entry point — "take me back to the start of the flow". */
-    focusEntryPoint(engine, index = 0) {
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram)
-            return this.getFocused();
-        const entries = (0, graph_topology_1.analyseTopology)(diagram).entryPoints;
-        if (entries.length === 0)
-            return this.getFocused();
-        const node = entries[Math.max(0, Math.min(index, entries.length - 1))];
-        return this.setFocus({ type: 'node', id: node.id }, engine);
-    }
-    /**
-     * The POSITION CONTEXT for the focused node — "node 3 of 12, 2 incoming,
-     * 1 outgoing". The orientation a sighted user gets for free from the picture.
-     */
-    positionContextOfFocus(engine) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) !== 'node')
-            return '';
-        return (0, diagram_outline_1.positionContext)(this.focused.id, diagram);
-    }
-    /** Announce where we are in the graph. Bound to a key in the host. */
-    announcePosition(engine) {
-        const context = this.positionContextOfFocus(engine);
-        if (!context)
-            return null;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        const node = diagram === null || diagram === void 0 ? void 0 : diagram.getNode(this.focused.id);
-        return this.announce(`${node ? this.nodeName(node) : ''}, ${context}`);
-    }
-    /** The whole-diagram natural-language summary, announced on entry. */
-    announceSummary(engine) {
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram)
-            return null;
-        return this.announce((0, diagram_outline_1.buildOutline)(diagram).summary);
-    }
-    // ==========================================================================
-    // wave6/a11y (card 3) — keyboard-only EDITING.
-    //
-    // Wave 4 shipped move (nudge) and connect. The holes it left were delete,
-    // duplicate and reparent — so a keyboard-only user could build a graph but
-    // never restructure one. Each returns ONE undoable command; the host executes
-    // it, exactly as it already does for nudge and connect.
-    // ==========================================================================
-    /**
-     * Delete the selection (or, with nothing selected, the focused entity), as one
-     * undoable macro. Deleting a node takes its incident edges with it — leaving
-     * dangling links is how a keyboard user silently corrupts a diagram.
-     */
-    deleteCommand(engine) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram)
-            return null;
-        const nodes = diagram.getNodes().filter((n) => { var _a; return n.isSelected() && ((_a = n.state) === null || _a === void 0 ? void 0 : _a.locked) !== true; });
-        const links = diagram.getLinks().filter((l) => l.state === 'selected');
-        // Nothing selected → act on focus, which is what the user is looking at.
-        if (nodes.length === 0 && links.length === 0 && this.focused) {
-            if (this.focused.type === 'node') {
-                const node = diagram.getNode(this.focused.id);
-                if (node && ((_a = node.state) === null || _a === void 0 ? void 0 : _a.locked) !== true)
-                    nodes.push(node);
-            }
-            else {
-                const link = diagram.getLink(this.focused.id);
-                if (link)
-                    links.push(link);
-            }
-        }
-        if (nodes.length === 0 && links.length === 0)
-            return null;
-        const doomedNodeIds = new Set(nodes.map((n) => n.id));
-        const doomedLinkIds = new Set(links.map((l) => l.id));
-        // Any edge touching a doomed node dies with it.
-        for (const link of diagram.getLinks()) {
-            const s = (0, semantics_1.sourceNodeIdOf)(link, diagram);
-            const t = (0, semantics_1.targetNodeIdOf)(link, diagram);
-            if (doomedNodeIds.has(s) || doomedNodeIds.has(t))
-                doomedLinkIds.add(link.id);
-        }
-        const macro = new engine_1.MacroCommand('Delete');
-        // Links FIRST — removing a node out from under its links can strand them.
-        for (const id of doomedLinkIds)
-            macro.addSteps([new engine_1.RemoveLinkCommand(id)]);
-        for (const id of doomedNodeIds)
-            macro.addSteps([new engine_1.RemoveNodeCommand(id)]);
-        const parts = [];
-        if (doomedNodeIds.size)
-            parts.push(`${doomedNodeIds.size} node${doomedNodeIds.size === 1 ? '' : 's'}`);
-        if (doomedLinkIds.size)
-            parts.push(`${doomedLinkIds.size} edge${doomedLinkIds.size === 1 ? '' : 's'}`);
-        this.announce(`Deleted ${parts.join(' and ')}`);
-        // Focus cannot stay on something that no longer exists.
-        if (this.focused &&
-            ((this.focused.type === 'node' && doomedNodeIds.has(this.focused.id)) ||
-                (this.focused.type === 'link' && doomedLinkIds.has(this.focused.id)))) {
-            this.focused = null;
-        }
-        return macro;
-    }
-    /**
-     * Duplicate the focused/selected nodes at an offset, carrying any edge that
-     * runs BETWEEN two duplicated nodes (an edge to a node you did not copy has
-     * no meaningful counterpart, so it is dropped — the same rule the pointer
-     * duplicate uses).
-     */
-    duplicateCommand(engine, offset = { x: 24, y: 24 }) {
-        var _a, _b, _c, _d, _e;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram)
-            return null;
-        let nodes = diagram.getNodes().filter((n) => n.isSelected());
-        if (nodes.length === 0 && ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) === 'node') {
-            const node = diagram.getNode(this.focused.id);
-            if (node)
-                nodes = [node];
-        }
-        if (nodes.length === 0)
-            return null;
-        const macro = new engine_1.MacroCommand(`Duplicate ${nodes.length} node${nodes.length === 1 ? '' : 's'}`);
-        const idMap = new Map();
-        for (const node of nodes) {
-            const clone = new engine_1.NodeModel({
-                type: node.type,
-                position: {
-                    x: node.position.x + offset.x,
-                    y: node.position.y + offset.y,
-                    z: node.position.z,
-                },
-                size: Object.assign({}, node.size),
-            });
-            // Carry the label and the author's metadata — a duplicate that loses its
-            // name is useless, and doubly so to someone who navigates BY name.
-            for (const [key, value] of node.metadata) {
-                clone.setMetadata(key, value);
-            }
-            clone.style = Object.assign({}, node.style);
-            if (node.parentId)
-                clone.parentId = node.parentId;
-            idMap.set(node.id, clone);
-            macro.addSteps([new engine_1.AddNodeCommand(clone)]);
-        }
-        for (const link of diagram.getLinks()) {
-            const s = idMap.get((0, semantics_1.sourceNodeIdOf)(link, diagram));
-            const t = idMap.get((0, semantics_1.targetNodeIdOf)(link, diagram));
-            if (!s || !t)
-                continue; // an edge leaving the copied set has no counterpart
-            const sourcePort = (_c = (_b = s.getPortBySide) === null || _b === void 0 ? void 0 : _b.call(s, 'right')) !== null && _c !== void 0 ? _c : s.getPorts()[0];
-            const targetPort = (_e = (_d = t.getPortBySide) === null || _d === void 0 ? void 0 : _d.call(t, 'left')) !== null && _e !== void 0 ? _e : t.getPorts()[0];
-            if (!sourcePort || !targetPort)
-                continue;
-            const clone = new engine_1.LinkModel(sourcePort.id, targetPort.id);
-            clone.setSourcePort(sourcePort.id, s.id);
-            clone.setTargetPort(targetPort.id, t.id);
-            macro.addSteps([new engine_1.AddLinkCommand(clone)]);
-        }
-        this.announce(`Duplicated ${nodes.length} node${nodes.length === 1 ? '' : 's'}`);
-        return macro;
-    }
-    /**
-     * REPARENT the focused node into (or out of) a container — the last thing that
-     * was pointer-only. `null` unparents.
-     *
-     * `SetParentCommand` already rejects a cycle; we catch it EARLY so the user
-     * gets an assertive "cannot" instead of an exception thrown into the void.
-     */
-    reparentCommand(engine, parentId) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) !== 'node')
-            return null;
-        const node = diagram.getNode(this.focused.id);
-        if (!node)
-            return null;
-        if (parentId) {
-            const parent = diagram.getNode(parentId);
-            if (!parent) {
-                this.announce(`Cannot reparent: container not found`, 'assertive');
-                return null;
-            }
-            if (parentId === node.id) {
-                this.announce('Cannot reparent a node into itself', 'assertive');
-                return null;
-            }
-            // Would it create a cycle? (Is the prospective parent already OUR child?)
-            const descendants = new Set();
-            const walk = (id) => {
-                for (const candidate of diagram.getNodes()) {
-                    if (candidate.parentId === id && !descendants.has(candidate.id)) {
-                        descendants.add(candidate.id);
-                        walk(candidate.id);
-                    }
-                }
-            };
-            walk(node.id);
-            if (descendants.has(parentId)) {
-                this.announce(`Cannot move ${this.nodeName(node)} into ${this.nodeName(parent)}: it would create a loop`, 'assertive');
-                return null;
-            }
-            this.announce(`Moved ${this.nodeName(node)} into ${this.nodeName(parent)}`);
-        }
-        else {
-            if (!node.parentId)
-                return null; // already top-level — nothing to do
-            this.announce(`Moved ${this.nodeName(node)} out of its container`);
-        }
-        return new engine_1.SetParentCommand(node.id, parentId !== null && parentId !== void 0 ? parentId : undefined);
-    }
-    /**
-     * The containers the focused node could legally be reparented into — what a
-     * host puts in a "move to…" list. Excludes itself and its own descendants.
-     */
-    reparentCandidates(engine) {
-        var _a;
-        const diagram = (0, semantics_1.diagramOf)(engine);
-        if (!diagram || ((_a = this.focused) === null || _a === void 0 ? void 0 : _a.type) !== 'node')
-            return [];
-        const node = diagram.getNode(this.focused.id);
-        if (!node)
-            return [];
-        const descendants = new Set([node.id]);
-        const walk = (id) => {
-            for (const candidate of diagram.getNodes()) {
-                if (candidate.parentId === id && !descendants.has(candidate.id)) {
-                    descendants.add(candidate.id);
-                    walk(candidate.id);
-                }
-            }
-        };
-        walk(node.id);
-        return diagram.getNodes().filter((n) => !descendants.has(n.id) && n.id !== node.parentId);
-    }
-    // ==========================================================================
-    // Nudge
-    // ==========================================================================
-    /** World delta for an arrow key (null when the key is not an arrow). */
-    nudgeDelta(key, coarse = false) {
-        const step = coarse ? this.config.coarseNudgeStep : this.config.nudgeStep;
-        switch (key) {
-            case 'ArrowLeft':
-                return { x: -step, y: 0 };
-            case 'ArrowRight':
-                return { x: step, y: 0 };
-            case 'ArrowUp':
-                return { x: 0, y: -step };
-            case 'ArrowDown':
-                return { x: 0, y: step };
-            default:
-                return null;
-        }
-    }
-    /**
-     * Move the selection (or, with nothing selected, the focused node) by a world
-     * delta, as ONE undoable command per key press. Locked / undraggable nodes are
-     * skipped; returns null when there is nothing to move.
-     *
-     * `mergeable` defaults FALSE — the a11y contract is "⌘Z undoes each nudge to
-     * the exact pixel". An editor that wants held-key auto-repeat to collapse
-     * into one undo entry (Visio's feel) passes true and the CommandManager's
-     * merge window does the rest.
-     */
-    nudgeCommand(engine, dx, dy, options = {}) {
-        var _a, _b;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return null;
-        let nodes = diagram.getSelectedNodes().filter((n) => n.isDraggable());
-        if (nodes.length === 0 && ((_b = this.focused) === null || _b === void 0 ? void 0 : _b.type) === 'node') {
-            const node = diagram.getNode(this.focused.id);
-            if (node === null || node === void 0 ? void 0 : node.isDraggable())
-                nodes = [node];
-        }
-        if (nodes.length === 0)
-            return null;
-        const commands = nodes.map((node) => new engine_1.MoveNodeCommand(node.id, { x: node.position.x + dx, y: node.position.y + dy, z: node.position.z }, { x: node.position.x, y: node.position.y, z: node.position.z }, { mergeable: options.mergeable === true }));
-        this.announce(`Moved ${commands.length === 1 ? this.nodeName(nodes[0]) : `${commands.length} nodes`} by ${Math.round(dx)}, ${Math.round(dy)}`);
-        if (commands.length === 1)
-            return commands[0];
-        const macro = new engine_1.MacroCommand(`Nudge ${commands.length} Nodes`);
-        macro.addSteps(commands);
-        return macro;
-    }
-    // ==========================================================================
-    // Keyboard connect
-    // ==========================================================================
-    getConnectState() {
-        return this.connectState ? Object.assign({}, this.connectState) : null;
-    }
-    isConnecting() {
-        return this.connectState !== null;
-    }
-    /**
-     * Start a keyboard connection from the focused node: phase 1 picks the SOURCE
-     * port (arrow keys cycle it), Enter confirms and moves to phase 2, where Tab
-     * cycles the target node and arrows its port. Returns false when the focused
-     * node has no connectable port.
-     */
-    beginConnect(engine) {
-        var _a, _b;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        const target = this.focused;
-        if (!diagram || (target === null || target === void 0 ? void 0 : target.type) !== 'node')
-            return false;
-        const node = diagram.getNode(target.id);
-        if (!node || ((_b = node.behavior) === null || _b === void 0 ? void 0 : _b.connectable) === false)
-            return false;
-        const ports = this.connectablePorts(node);
-        if (ports.length === 0) {
-            this.announce('No connectable ports on this node', 'assertive');
-            return false;
-        }
-        this.connectState = {
-            phase: 'source',
-            sourceNodeId: node.id,
-            sourcePortId: ports[0].id,
-            valid: false,
-        };
-        this.announce(`Connect from ${this.nodeName(node)}, port ${this.portName(ports[0])}. Arrow keys change port, Enter to choose target.`);
-        return true;
-    }
-    /** Cycle the port being picked in the current phase. */
-    cyclePort(engine, delta) {
-        var _a;
-        const state = this.connectState;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!state || !diagram)
-            return false;
-        const nodeId = state.phase === 'source' ? state.sourceNodeId : state.targetNodeId;
-        if (!nodeId)
-            return false;
-        const node = diagram.getNode(nodeId);
-        if (!node)
-            return false;
-        const ports = this.connectablePorts(node);
-        if (ports.length === 0)
-            return false;
-        const currentId = state.phase === 'source' ? state.sourcePortId : state.targetPortId;
-        const index = Math.max(0, ports.findIndex((p) => p.id === currentId));
-        const next = ports[(index + delta + ports.length) % ports.length];
-        if (state.phase === 'source') {
-            state.sourcePortId = next.id;
-        }
-        else {
-            state.targetPortId = next.id;
-        }
-        this.refreshConnectValidity(engine);
-        this.announce(`Port ${this.portName(next)}${state.phase === 'target'
-            ? state.valid
-                ? ', valid target'
-                : ', not a valid target'
-            : ''}`);
-        return true;
-    }
-    /** Cycle the TARGET node (Tab during phase 2). */
-    cycleTargetNode(engine, delta) {
-        var _a, _b;
-        const state = this.connectState;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!state || !diagram || state.phase !== 'target')
-            return false;
-        const candidates = this.getFocusOrder(engine)
-            .filter((t) => t.type === 'node' && t.id !== state.sourceNodeId)
-            .map((t) => diagram.getNode(t.id))
-            .filter((n) => { var _a; return !!n && ((_a = n.behavior) === null || _a === void 0 ? void 0 : _a.connectable) !== false; });
-        if (candidates.length === 0)
-            return false;
-        const index = Math.max(0, candidates.findIndex((n) => n.id === state.targetNodeId));
-        const next = candidates[(index + delta + candidates.length) % candidates.length];
-        state.targetNodeId = next.id;
-        state.targetPortId = (_b = this.connectablePorts(next)[0]) === null || _b === void 0 ? void 0 : _b.id;
-        this.refreshConnectValidity(engine);
-        this.announce(`Target ${this.nodeName(next)}${state.valid ? ', valid' : ', not a valid target'}`);
-        return true;
-    }
-    /**
-     * Enter: phase 1 → confirm the source and enter phase 2 (seeding the first
-     * candidate target); phase 2 → COMMIT, returning the undoable AddLinkCommand
-     * (null when the pair is not legal).
-     */
-    confirmConnect(engine) {
-        var _a, _b;
-        const state = this.connectState;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!state || !diagram)
-            return null;
-        if (state.phase === 'source') {
-            state.phase = 'target';
-            const first = this.getFocusOrder(engine)
-                .filter((t) => t.type === 'node' && t.id !== state.sourceNodeId)
-                .map((t) => diagram.getNode(t.id))
-                .find((n) => { var _a; return !!n && ((_a = n.behavior) === null || _a === void 0 ? void 0 : _a.connectable) !== false; });
-            if (!first) {
-                this.announce('No other node to connect to', 'assertive');
-                this.connectState = null;
-                return null;
-            }
-            state.targetNodeId = first.id;
-            state.targetPortId = (_b = this.connectablePorts(first)[0]) === null || _b === void 0 ? void 0 : _b.id;
-            this.refreshConnectValidity(engine);
-            this.announce(`Choose target. ${this.nodeName(first)}${state.valid ? ', valid' : ', not a valid target'}. Tab cycles nodes, Enter connects.`);
-            return null;
-        }
-        // Commit.
-        this.refreshConnectValidity(engine);
-        if (!state.valid || !state.targetPortId || !state.targetNodeId) {
-            this.announce('Cannot connect these ports', 'assertive');
-            return null;
-        }
-        const link = new engine_1.LinkModel(state.sourcePortId, state.targetPortId);
-        link.setSourcePort(state.sourcePortId, state.sourceNodeId);
-        link.setTargetPort(state.targetPortId, state.targetNodeId);
-        const sourceNode = diagram.getNode(state.sourceNodeId);
-        const targetNode = diagram.getNode(state.targetNodeId);
-        this.announce(`Connected ${sourceNode ? this.nodeName(sourceNode) : 'source'} to ${targetNode ? this.nodeName(targetNode) : 'target'}`);
-        this.connectState = null;
-        return new engine_1.AddLinkCommand(link);
-    }
-    /** Escape. */
-    cancelConnect() {
-        if (!this.connectState)
-            return;
-        this.connectState = null;
-        this.announce('Connection cancelled');
-    }
-    /** Re-evaluate the source/target pair against the shared connection rule. */
-    refreshConnectValidity(engine) {
-        var _a;
-        const state = this.connectState;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!state || !diagram)
-            return;
-        if (state.phase === 'source' || !state.targetNodeId || !state.targetPortId) {
-            state.valid = false;
-            return;
-        }
-        const sourceNode = diagram.getNode(state.sourceNodeId);
-        const targetNode = diagram.getNode(state.targetNodeId);
-        const sourcePort = sourceNode === null || sourceNode === void 0 ? void 0 : sourceNode.getPort(state.sourcePortId);
-        const targetPort = targetNode === null || targetNode === void 0 ? void 0 : targetNode.getPort(state.targetPortId);
-        if (!sourceNode || !targetNode || !sourcePort || !targetPort) {
-            state.valid = false;
-            return;
-        }
-        state.valid = (0, snapping_1.canConnectPorts)(sourcePort, targetPort, sourceNode, targetNode, engine, diagram);
-    }
-    connectablePorts(node) {
-        return node.getPorts();
-    }
-    // ==========================================================================
-    // Announcements (the aria-live seam)
-    // ==========================================================================
-    onAnnounce(listener) {
-        this.listeners.add(listener);
-        return () => this.listeners.delete(listener);
-    }
-    getLastAnnouncement() {
-        return this.lastAnnouncement ? Object.assign({}, this.lastAnnouncement) : null;
-    }
-    announce(message, politeness = 'polite') {
-        const announcement = { message, politeness, seq: ++this.seq };
-        this.lastAnnouncement = announcement;
-        this.listeners.forEach((listener) => listener(announcement));
-        return announcement;
-    }
-    /** "2 nodes and 1 link selected" — announced whenever the selection changes. */
-    announceSelection(engine) {
-        var _a;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return null;
-        const nodes = diagram.getNodes().filter((n) => n.isSelected());
-        const links = diagram.getLinks().filter((l) => l.state === 'selected');
-        if (nodes.length === 0 && links.length === 0) {
-            return this.announce('Selection cleared');
-        }
-        // `describe()` already ends in ", selected" for a selected entity — appending
-        // another "selected" here made the screen reader say it twice.
-        if (nodes.length === 1 && links.length === 0) {
-            return this.announce(this.describe(engine, { type: 'node', id: nodes[0].id }));
-        }
-        if (nodes.length === 0 && links.length === 1) {
-            return this.announce(this.describe(engine, { type: 'link', id: links[0].id }));
-        }
-        const parts = [];
-        if (nodes.length)
-            parts.push(`${nodes.length} node${nodes.length === 1 ? '' : 's'}`);
-        if (links.length)
-            parts.push(`${links.length} link${links.length === 1 ? '' : 's'}`);
-        return this.announce(`${parts.join(' and ')} selected`);
-    }
-    /** "Node Start added. 4 nodes, 3 links." — for structure changes. */
-    announceStructure(engine, change) {
-        var _a;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return null;
-        const nodes = diagram.getNodes().length;
-        const links = diagram.getLinks().length;
-        return this.announce(`${change}. ${nodes} node${nodes === 1 ? '' : 's'}, ${links} link${links === 1 ? '' : 's'}.`);
-    }
-    /**
-     * The accessible name of a target: what a screen reader reads on focus, and
-     * what the host puts in `aria-label` on the rendered element.
-     */
-    describe(engine, target) {
-        var _a, _b;
-        const diagram = (_a = engine === null || engine === void 0 ? void 0 : engine.getDiagram) === null || _a === void 0 ? void 0 : _a.call(engine);
-        if (!diagram)
-            return '';
-        if (target.type === 'node') {
-            const node = diagram.getNode(target.id);
-            if (!node)
-                return '';
-            const links = diagram
-                .getLinks()
-                .filter((l) => this.sourceNodeIdOf(l, diagram) === node.id ||
-                this.targetNodeIdOf(l, diagram) === node.id).length;
-            const bits = [`${node.type} node`, this.nodeName(node)];
-            bits.push(`${links} connection${links === 1 ? '' : 's'}`);
-            if (node.isSelected())
-                bits.push('selected');
-            if ((_b = node.state) === null || _b === void 0 ? void 0 : _b.locked)
-                bits.push('locked');
-            return bits.join(', ');
-        }
-        const link = diagram.getLink(target.id);
-        if (!link)
-            return '';
-        const source = diagram.getNode(this.sourceNodeIdOf(link, diagram));
-        const target2 = diagram.getNode(this.targetNodeIdOf(link, diagram));
-        const bits = [
-            'link',
-            `from ${source ? this.nodeName(source) : 'unknown'}`,
-            `to ${target2 ? this.nodeName(target2) : 'unknown'}`,
-        ];
-        if (link.state === 'selected')
-            bits.push('selected');
-        return bits.join(', ');
-    }
-    /** Human name of a node: its label, else its type + short id. */
-    nodeName(node) {
-        const label = node.getLabel();
-        if (typeof label === 'string' && label.trim().length > 0)
-            return label;
-        return `${node.type} ${node.id.slice(0, 4)}`;
-    }
-    portName(port) {
-        var _a, _b, _c;
-        const label = (_a = port.getMetadata) === null || _a === void 0 ? void 0 : _a.call(port, 'label');
-        if (typeof label === 'string' && label.trim().length > 0)
-            return label;
-        return `${(_c = (_b = port.alignment) === null || _b === void 0 ? void 0 : _b.side) !== null && _c !== void 0 ? _c : 'port'} ${port.type}`;
-    }
-    sourceNodeIdOf(link, diagram) {
-        var _a, _b, _c;
-        return (_c = (_a = link.sourceNodeId) !== null && _a !== void 0 ? _a : (_b = diagram.getNodeByPortId(link.sourcePortId)) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : '';
-    }
-    targetNodeIdOf(link, diagram) {
-        var _a, _b, _c;
-        return (_c = (_a = link.targetNodeId) !== null && _a !== void 0 ? _a : (_b = diagram.getNodeByPortId(link.targetPortId)) === null || _b === void 0 ? void 0 : _b.id) !== null && _c !== void 0 ? _c : '';
-    }
-    dispose() {
-        this.listeners.clear();
-        this.focused = null;
-        this.connectState = null;
-    }
-}
-exports.KeyboardNavigationController = KeyboardNavigationController;
-function centerOf(node) {
-    const box = node.getBoundingBox();
-    return { x: (box.left + box.right) / 2, y: (box.top + box.bottom) / 2 };
-}
-//# sourceMappingURL=keyboard-navigation.js.map