@grafloria/element 0.3.17 → 0.3.19

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

@@ -0,0 +1,885 @@
+"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