@bindtty/interaction 0.1.0-alpha.1

package/dist/controller.d.ts

@@ -0,0 +1,2 @@
+import type { InteractionController } from "./types.js";
+export declare function createInteractionController(): InteractionController;

package/dist/controller.js

@@ -0,0 +1,284 @@
+import { isShiftTabKey, isTabKey } from "./keyboard.js";
+function createEmptyResult(handled = false) {
+    return {
+        handled,
+        dirtyNodes: []
+    };
+}
+export function createInteractionController() {
+    const focusChangeListeners = new Set();
+    const internalIds = new WeakMap();
+    let nextInternalId = 1;
+    let entries = [];
+    let focusState = {
+        entry: null,
+        previousOrder: null
+    };
+    let disposed = false;
+    function allocateInternalId(node) {
+        const existing = internalIds.get(node);
+        if (existing) {
+            return existing;
+        }
+        const id = `bindtty-internal-focus-${nextInternalId}`;
+        nextInternalId += 1;
+        internalIds.set(node, id);
+        return id;
+    }
+    function getEntryId(node) {
+        const id = node.props.id;
+        if (typeof id === "string" || typeof id === "number") {
+            return String(id);
+        }
+        return allocateInternalId(node);
+    }
+    function resolveOnKey(value) {
+        return value;
+    }
+    function toFocusEntry(node, order) {
+        const onKey = resolveOnKey(node.props.onKey);
+        if (onKey === true) {
+            return {
+                id: getEntryId(node),
+                node,
+                order,
+                handler: null
+            };
+        }
+        if (typeof onKey === "function") {
+            return {
+                id: getEntryId(node),
+                node,
+                order,
+                handler: onKey
+            };
+        }
+        return null;
+    }
+    function collectEntries(root) {
+        const nextEntries = [];
+        let order = 0;
+        function visit(node) {
+            if (!node) {
+                return;
+            }
+            switch (node.kind) {
+                case "element": {
+                    const entry = toFocusEntry(node, order);
+                    order += 1;
+                    if (entry) {
+                        nextEntries.push(entry);
+                    }
+                    for (const child of node.children) {
+                        visit(child);
+                    }
+                    return;
+                }
+                case "fragment":
+                    for (const child of node.children) {
+                        visit(child);
+                    }
+                    return;
+                case "show":
+                    visit(node.activeBranch);
+                    return;
+                case "for":
+                    for (const item of node.items) {
+                        visit(item.node);
+                    }
+                    return;
+            }
+        }
+        visit(root);
+        return nextEntries;
+    }
+    function toSnapshot(entry) {
+        if (!entry) {
+            return null;
+        }
+        return {
+            id: entry.id,
+            node: entry.node
+        };
+    }
+    function readNodeFocusChange(node) {
+        return node.props.onFocusChange;
+    }
+    function notifyNodeFocusChange(entry, focused, reason) {
+        const listener = readNodeFocusChange(entry.node);
+        if (typeof listener === "function") {
+            listener({
+                id: entry.id,
+                node: entry.node,
+                focused,
+                reason
+            });
+        }
+    }
+    function buildFocusResult(previous, current, reason, handled) {
+        if (previous?.node === current?.node) {
+            return createEmptyResult(handled);
+        }
+        const focusChange = {
+            previous: toSnapshot(previous),
+            current: toSnapshot(current),
+            reason
+        };
+        const dirtyNodes = [];
+        if (previous) {
+            dirtyNodes.push(previous.node);
+            notifyNodeFocusChange(previous, false, reason);
+        }
+        if (current) {
+            dirtyNodes.push(current.node);
+            notifyNodeFocusChange(current, true, reason);
+        }
+        for (const listener of [...focusChangeListeners]) {
+            listener(focusChange);
+        }
+        return {
+            handled,
+            dirtyNodes,
+            focusChange
+        };
+    }
+    function setFocusedEntry(entry, reason, handled) {
+        const previous = focusState.entry;
+        focusState = {
+            entry,
+            previousOrder: entry?.order ?? previous?.order ?? focusState.previousOrder
+        };
+        return buildFocusResult(previous, entry, reason, handled);
+    }
+    function findEntryForNode(node) {
+        return entries.find((entry) => entry.node === node) ?? null;
+    }
+    function findEntryForId(id) {
+        return entries.find((entry) => entry.id === id) ?? null;
+    }
+    function findRefreshFallback(previousOrder) {
+        if (entries.length === 0) {
+            return null;
+        }
+        if (previousOrder === null) {
+            return entries[0];
+        }
+        return (entries.find((entry) => entry.order >= previousOrder) ??
+            entries[entries.length - 1]);
+    }
+    function moveFocus(step) {
+        if (disposed || entries.length === 0) {
+            return createEmptyResult(false);
+        }
+        if (entries.length === 1 && focusState.entry) {
+            return createEmptyResult(true);
+        }
+        let nextIndex;
+        if (!focusState.entry) {
+            nextIndex = step === 1 ? 0 : entries.length - 1;
+        }
+        else {
+            const currentIndex = entries.findIndex((entry) => entry.node === focusState.entry?.node);
+            if (currentIndex === -1) {
+                nextIndex = step === 1 ? 0 : entries.length - 1;
+            }
+            else {
+                nextIndex = (currentIndex + step + entries.length) % entries.length;
+            }
+        }
+        return setFocusedEntry(entries[nextIndex], step === 1 ? "next" : "previous", true);
+    }
+    return {
+        refresh(root) {
+            if (disposed) {
+                return createEmptyResult();
+            }
+            const previousEntry = focusState.entry;
+            const previousOrder = previousEntry?.order ?? focusState.previousOrder;
+            entries = collectEntries(root);
+            if (previousEntry) {
+                const retained = findEntryForNode(previousEntry.node);
+                if (retained) {
+                    focusState = {
+                        entry: retained,
+                        previousOrder: retained.order
+                    };
+                    return createEmptyResult();
+                }
+            }
+            const nextEntry = findRefreshFallback(previousOrder);
+            const reason = previousEntry ? "refresh" : "initial";
+            return setFocusedEntry(nextEntry, reason, false);
+        },
+        handleKey(event) {
+            if (disposed) {
+                return createEmptyResult(false);
+            }
+            if (isTabKey(event)) {
+                return isShiftTabKey(event) ? moveFocus(-1) : moveFocus(1);
+            }
+            const focusedEntry = focusState.entry;
+            if (!focusedEntry?.handler) {
+                return createEmptyResult(false);
+            }
+            return createEmptyResult(focusedEntry.handler(event, {
+                node: focusedEntry.node,
+                isFocused: true
+            }) === true);
+        },
+        onFocusChange(listener) {
+            if (disposed) {
+                return () => { };
+            }
+            focusChangeListeners.add(listener);
+            return () => {
+                focusChangeListeners.delete(listener);
+            };
+        },
+        focus(target) {
+            if (disposed) {
+                return createEmptyResult();
+            }
+            const entry = typeof target === "string"
+                ? findEntryForId(target)
+                : findEntryForNode(target);
+            if (!entry) {
+                return createEmptyResult(false);
+            }
+            return setFocusedEntry(entry, "programmatic", true);
+        },
+        focusNext() {
+            return moveFocus(1);
+        },
+        focusPrevious() {
+            return moveFocus(-1);
+        },
+        clearFocus() {
+            if (disposed || !focusState.entry) {
+                return createEmptyResult(false);
+            }
+            return setFocusedEntry(null, "clear", true);
+        },
+        getFocusedId() {
+            return focusState.entry?.id ?? null;
+        },
+        getFocusedNode() {
+            return focusState.entry?.node ?? null;
+        },
+        isFocused(node) {
+            return node.kind === "element" && focusState.entry?.node === node;
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            focusChangeListeners.clear();
+            entries = [];
+            focusState = {
+                entry: null,
+                previousOrder: null
+            };
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createInteractionController } from "./controller.js";
+export { isArrowKey, isEnterKey, isEscapeKey, isShiftTabKey, isTabKey, isTextInputKey } from "./keyboard.js";
+export type { InteractionController, InteractionFocusChangeEvent, InteractionFocusChangeListener, InteractionFocusChangeReason, InteractionFocusSnapshot, InteractionKeyBinding, InteractionKeyContext, InteractionKeyHandler, InteractionNodeFocusChangeEvent, InteractionResult, IntrinsicInteractionProps, KeyFocusEntry } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createInteractionController } from "./controller.js";
+export { isArrowKey, isEnterKey, isEscapeKey, isShiftTabKey, isTabKey, isTextInputKey } from "./keyboard.js";

package/dist/keyboard.d.ts

@@ -0,0 +1,7 @@
+import type { TerminalKeyEvent } from "@bindtty/terminal";
+export declare function isTabKey(event: TerminalKeyEvent): boolean;
+export declare function isShiftTabKey(event: TerminalKeyEvent): boolean;
+export declare function isEnterKey(event: TerminalKeyEvent): boolean;
+export declare function isEscapeKey(event: TerminalKeyEvent): boolean;
+export declare function isArrowKey(event: TerminalKeyEvent): boolean;
+export declare function isTextInputKey(event: TerminalKeyEvent): boolean;

package/dist/keyboard.js

@@ -0,0 +1,21 @@
+export function isTabKey(event) {
+    return event.name === "tab" || event.input === "\t";
+}
+export function isShiftTabKey(event) {
+    return isTabKey(event) && event.shift;
+}
+export function isEnterKey(event) {
+    return event.name === "return" || event.name === "enter" || event.input === "\r";
+}
+export function isEscapeKey(event) {
+    return event.name === "escape" || event.input === "\u001b";
+}
+export function isArrowKey(event) {
+    return (event.name === "left" ||
+        event.name === "right" ||
+        event.name === "up" ||
+        event.name === "down");
+}
+export function isTextInputKey(event) {
+    return event.input.length > 0 && !event.ctrl && !event.meta && !event.name;
+}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+import type { TerminalKeyEvent } from "@bindtty/terminal";
+import type { BindingValue, MountedElementNode, MountedNode } from "@bindtty/vnode";
+export type InteractionFocusChangeReason = "initial" | "next" | "previous" | "programmatic" | "clear" | "refresh";
+export interface InteractionFocusSnapshot {
+    id: string;
+    node: MountedElementNode;
+}
+export interface InteractionFocusChangeEvent {
+    previous: InteractionFocusSnapshot | null;
+    current: InteractionFocusSnapshot | null;
+    reason: InteractionFocusChangeReason;
+}
+export interface InteractionNodeFocusChangeEvent {
+    id: string;
+    node: MountedElementNode;
+    focused: boolean;
+    reason: InteractionFocusChangeReason;
+}
+export type InteractionFocusChangeListener = (event: InteractionFocusChangeEvent) => void;
+export interface InteractionKeyContext {
+    node: MountedElementNode;
+    isFocused: true;
+}
+export type InteractionKeyHandler = (event: TerminalKeyEvent, context: InteractionKeyContext) => boolean | void;
+export type InteractionKeyBinding = boolean | InteractionKeyHandler | null | undefined;
+export interface IntrinsicInteractionProps {
+    id?: BindingValue<string | number>;
+    onKey?: BindingValue<InteractionKeyBinding>;
+    onFocusChange?: (event: InteractionNodeFocusChangeEvent) => void;
+}
+export interface InteractionResult {
+    handled: boolean;
+    dirtyNodes: MountedNode[];
+    focusChange?: InteractionFocusChangeEvent;
+}
+export interface KeyFocusEntry {
+    id: string;
+    node: MountedElementNode;
+    order: number;
+    handler: InteractionKeyHandler | null;
+}
+export interface InteractionController {
+    refresh(root: MountedNode | null): InteractionResult;
+    handleKey(event: TerminalKeyEvent): InteractionResult;
+    onFocusChange(listener: InteractionFocusChangeListener): () => void;
+    focus(target: string | MountedElementNode): InteractionResult;
+    focusNext(): InteractionResult;
+    focusPrevious(): InteractionResult;
+    clearFocus(): InteractionResult;
+    getFocusedId(): string | null;
+    getFocusedNode(): MountedElementNode | null;
+    isFocused(node: MountedNode): boolean;
+    dispose(): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bindtty/interaction",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Keyboard focus and key dispatch layer for BindTTY.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build --workspace @bindtty/vnode && npm run build --workspace @bindtty/terminal && npm run build && tsc -p test/tsconfig.json && node --test test/dist/*.test.js"
+  },
+  "dependencies": {
+    "@bindtty/terminal": "0.1.0-alpha.1",
+    "@bindtty/vnode": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lithdoo/BindTTY.git",
+    "directory": "packages/interaction"
+  },
+  "bugs": {
+    "url": "https://github.com/lithdoo/BindTTY/issues"
+  },
+  "homepage": "https://github.com/lithdoo/BindTTY/tree/main/packages/interaction#readme"
+}