@grafloria/element 0.3.20 → 0.3.21

package/src/libs/renderer/src/interaction/keyboard-navigation.d.ts

@@ -1,223 +0,0 @@
-import type { DiagramEngine, NodeModel, LinkModel, Point, Command } from '@grafloria/engine';
-import { PortModel } from '@grafloria/engine';
-import type { Rectangle } from '../types/geometry.types';
-import { type Incidence } from '../a11y/graph-topology';
-/**
- * KeyboardNavigationController — a fully keyboard-operable, screen-reader-
- * announced canvas (Card 7, wave4/interaction).
- *
- * No diagramming competitor does this: Mermaid is read-only, and React Flow /
- * JointJS+ / GoJS are pointer-first with, at best, arrow-key nudging. This class
- * owns the whole keyboard model:
- *
- *  - a FOCUS ring that walks nodes and links (Tab / Shift+Tab, arrow keys for
- *    spatial movement) — focus is distinct from selection, as in every native UI;
- *  - arrow-key NUDGE of the selection (Shift = coarse step), committed as ONE
- *    undoable command per key press;
- *  - Enter to edit the focused node's label (the host opens the editor);
- *  - keyboard CONNECT: pick a source port, then a target node/port, commit;
- *  - ARIA ANNOUNCEMENTS for selection and structure changes, which the host pipes
- *    into an `aria-live` region.
- *
- * Framework-agnostic: it emits state + {@link Command}s, and never renders.
- */
-export type FocusTargetType = 'node' | 'link';
-export interface FocusTarget {
-    type: FocusTargetType;
-    id: string;
-}
-/** What the host draws as the visible focus ring. */
-export interface FocusRing {
-    type: FocusTargetType;
-    id: string;
-    /** Nodes: the padded world box. */
-    bounds?: Rectangle;
-    rotation?: number;
-    /** Links: the routed polyline. */
-    points?: Point[];
-    /** The accessible name announced for this target. */
-    label: string;
-}
-export interface Announcement {
-    message: string;
-    /** `assertive` interrupts the screen reader (errors); default polite. */
-    politeness: 'polite' | 'assertive';
-    /** Monotonic counter — hosts re-announce only when this changes. */
-    seq: number;
-}
-export type AnnouncementListener = (announcement: Announcement) => void;
-/** Remove an announcement listener. (Named to avoid clashing with the
- *  viewport module's `Unsubscribe`, which is re-exported from the same barrel.) */
-export type AnnouncementUnsubscribe = () => void;
-export type NavDirection = 'up' | 'down' | 'left' | 'right';
-export interface KeyboardNavConfig {
-    /** Fine nudge step, world units (arrow key). */
-    nudgeStep: number;
-    /** Coarse nudge step, world units (Shift + arrow). */
-    coarseNudgeStep: number;
-    /** Focus wraps around at the ends of the order. */
-    wrapFocus: boolean;
-    /** World padding of the focus ring around a node's box. */
-    focusRingPadding: number;
-}
-export declare const DEFAULT_KEYBOARD_NAV_CONFIG: KeyboardNavConfig;
-/** The keyboard-connect state machine. */
-export interface KeyboardConnectState {
-    phase: 'source' | 'target';
-    sourceNodeId: string;
-    sourcePortId: string;
-    targetNodeId?: string;
-    targetPortId?: string;
-    /** True when the current source/target pair is a legal link. */
-    valid: boolean;
-}
-export declare class KeyboardNavigationController {
-    protected config: KeyboardNavConfig;
-    protected focused: FocusTarget | null;
-    protected connectState: KeyboardConnectState | null;
-    protected listeners: Set<AnnouncementListener>;
-    protected lastAnnouncement: Announcement | null;
-    protected seq: number;
-    constructor(config?: Partial<KeyboardNavConfig>);
-    getConfig(): KeyboardNavConfig;
-    updateConfig(patch: Partial<KeyboardNavConfig>): void;
-    /**
-     * 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: DiagramEngine): FocusTarget[];
-    getFocused(): FocusTarget | null;
-    /** Set focus (null clears it) and announce the new target. */
-    setFocus(target: FocusTarget | null, engine?: DiagramEngine): FocusTarget | null;
-    /** Tab. */
-    focusNext(engine: DiagramEngine): FocusTarget | null;
-    /** Shift+Tab. */
-    focusPrevious(engine: DiagramEngine): FocusTarget | null;
-    protected step(engine: DiagramEngine, delta: number): FocusTarget | null;
-    /**
-     * 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: DiagramEngine, direction: NavDirection): FocusTarget | null;
-    /** The visible focus ring for the current target (null when nothing is focused). */
-    getFocusRing(engine: DiagramEngine): FocusRing | null;
-    /**
-     * 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: DiagramEngine, additive?: boolean): boolean;
-    /** The edges incident on the focused node, in a stable traversal order. */
-    incidentEdgesOfFocus(engine: DiagramEngine): Incidence[];
-    /**
-     * 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: DiagramEngine, index?: number): FocusTarget | null;
-    /** Walk to the Nth node this one points AT. */
-    followOutgoing(engine: DiagramEngine, index?: number): FocusTarget | null;
-    /** Walk back to the Nth node that points at this one. */
-    followIncoming(engine: DiagramEngine, index?: number): FocusTarget | null;
-    protected followDirected(engine: DiagramEngine, direction: 'outgoing' | 'incoming', index: number): FocusTarget | null;
-    /** Focus the EDGE itself (rather than jumping over it) — so it can be deleted. */
-    focusIncidentEdge(engine: DiagramEngine, index?: number): FocusTarget | null;
-    /** Jump to the first entry point — "take me back to the start of the flow". */
-    focusEntryPoint(engine: DiagramEngine, index?: number): FocusTarget | null;
-    /**
-     * 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: DiagramEngine): string;
-    /** Announce where we are in the graph. Bound to a key in the host. */
-    announcePosition(engine: DiagramEngine): Announcement | null;
-    /** The whole-diagram natural-language summary, announced on entry. */
-    announceSummary(engine: DiagramEngine): Announcement | null;
-    /**
-     * 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: DiagramEngine): Command | null;
-    /**
-     * 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: DiagramEngine, offset?: Point): Command | null;
-    /**
-     * 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: DiagramEngine, parentId: string | null): Command | null;
-    /**
-     * 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: DiagramEngine): NodeModel[];
-    /** World delta for an arrow key (null when the key is not an arrow). */
-    nudgeDelta(key: string, coarse?: boolean): Point | 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: DiagramEngine, dx: number, dy: number, options?: {
-        mergeable?: boolean;
-    }): Command | null;
-    getConnectState(): KeyboardConnectState | null;
-    isConnecting(): boolean;
-    /**
-     * 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: DiagramEngine): boolean;
-    /** Cycle the port being picked in the current phase. */
-    cyclePort(engine: DiagramEngine, delta: number): boolean;
-    /** Cycle the TARGET node (Tab during phase 2). */
-    cycleTargetNode(engine: DiagramEngine, delta: number): boolean;
-    /**
-     * 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: DiagramEngine): Command | null;
-    /** Escape. */
-    cancelConnect(): void;
-    /** Re-evaluate the source/target pair against the shared connection rule. */
-    protected refreshConnectValidity(engine: DiagramEngine): void;
-    protected connectablePorts(node: NodeModel): PortModel[];
-    onAnnounce(listener: AnnouncementListener): AnnouncementUnsubscribe;
-    getLastAnnouncement(): Announcement | null;
-    announce(message: string, politeness?: 'polite' | 'assertive'): Announcement;
-    /** "2 nodes and 1 link selected" — announced whenever the selection changes. */
-    announceSelection(engine: DiagramEngine): Announcement | null;
-    /** "Node Start added. 4 nodes, 3 links." — for structure changes. */
-    announceStructure(engine: DiagramEngine, change: string): Announcement | null;
-    /**
-     * 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: DiagramEngine, target: FocusTarget): string;
-    /** Human name of a node: its label, else its type + short id. */
-    nodeName(node: NodeModel): string;
-    protected portName(port: PortModel): string;
-    protected sourceNodeIdOf(link: LinkModel, diagram: any): string;
-    protected targetNodeIdOf(link: LinkModel, diagram: any): string;
-    dispose(): void;
-}