@bindtty/interaction 0.1.0-alpha.2 → 0.1.0-alpha.3

package/dist/controller.js

@@ -1,10 +1,25 @@
-import { isShiftTabKey, isTabKey } from "./keyboard.js";
+import { createKeyEvent, dispatchTo, runTabFallback } from "./dispatch.js";
 function createEmptyResult(handled = false) {
     return {
         handled,
         dirtyNodes: []
     };
 }
+function uniqueNodes(nodes) {
+    const seen = new Set();
+    const result = [];
+    for (const node of nodes) {
+        if (seen.has(node)) {
+            continue;
+        }
+        seen.add(node);
+        result.push(node);
+    }
+    return result;
+}
+function collectFocusDirtyNodes(previousPath, nextPath) {
+    return uniqueNodes([...previousPath, ...nextPath]);
+}
 export function createInteractionController() {
     const focusChangeListeners = new Set();
     const internalIds = new WeakMap();
@@ -12,7 +27,8 @@ export function createInteractionController() {
     let entries = [];
     let focusState = {
         entry: null,
-        previousOrder: null
+        previousOrder: null,
+        focusedPath: []
     };
     let disposed = false;
     function allocateInternalId(node) {
@@ -35,28 +51,17 @@ export function createInteractionController() {
     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
-            };
+    function isFocusable(node) {
+        const explicit = node.props.focusable;
+        if (explicit !== undefined) {
+            return explicit === true;
         }
-        if (typeof onKey === "function") {
-            return {
-                id: getEntryId(node),
-                node,
-                order,
-                handler: onKey
-            };
-        }
-        return null;
+        const onKey = resolveOnKey(node.props.onKey);
+        return onKey === true || typeof onKey === "function";
     }
     function collectEntries(root) {
         const nextEntries = [];
+        const path = [];
         let order = 0;
         function visit(node) {
             if (!node) {
@@ -64,14 +69,20 @@ export function createInteractionController() {
             }
             switch (node.kind) {
                 case "element": {
-                    const entry = toFocusEntry(node, order);
-                    order += 1;
-                    if (entry) {
-                        nextEntries.push(entry);
+                    path.push(node);
+                    if (isFocusable(node)) {
+                        nextEntries.push({
+                            id: getEntryId(node),
+                            node,
+                            order,
+                            path: [...path]
+                        });
                     }
+                    order += 1;
                     for (const child of node.children) {
                         visit(child);
                     }
+                    path.pop();
                     return;
                 }
                 case "fragment":
@@ -97,8 +108,7 @@ export function createInteractionController() {
             return null;
         }
         return {
-            id: entry.id,
-            node: entry.node
+            id: entry.id
         };
     }
     function readNodeFocusChange(node) {
@@ -109,13 +119,12 @@ export function createInteractionController() {
         if (typeof listener === "function") {
             listener({
                 id: entry.id,
-                node: entry.node,
                 focused,
                 reason
             });
         }
     }
-    function buildFocusResult(previous, current, reason, handled) {
+    function buildFocusResult(previous, current, previousPath, reason, handled) {
         if (previous?.node === current?.node) {
             return createEmptyResult(handled);
         }
@@ -124,13 +133,11 @@ export function createInteractionController() {
             current: toSnapshot(current),
             reason
         };
-        const dirtyNodes = [];
+        const dirtyNodes = collectFocusDirtyNodes(previousPath, current?.path ?? []);
         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]) {
@@ -144,11 +151,13 @@ export function createInteractionController() {
     }
     function setFocusedEntry(entry, reason, handled) {
         const previous = focusState.entry;
+        const previousPath = focusState.focusedPath;
         focusState = {
             entry,
-            previousOrder: entry?.order ?? previous?.order ?? focusState.previousOrder
+            previousOrder: entry?.order ?? previous?.order ?? focusState.previousOrder,
+            focusedPath: entry?.path ?? []
         };
-        return buildFocusResult(previous, entry, reason, handled);
+        return buildFocusResult(previous, entry, previousPath, reason, handled);
     }
     function findEntryForNode(node) {
         return entries.find((entry) => entry.node === node) ?? null;
@@ -188,6 +197,9 @@ export function createInteractionController() {
         }
         return setFocusedEntry(entries[nextIndex], step === 1 ? "next" : "previous", true);
     }
+    function runFallbackKeyAction(raw) {
+        return runTabFallback(raw, moveFocus);
+    }
     return {
         refresh(root) {
             if (disposed) {
@@ -201,7 +213,8 @@ export function createInteractionController() {
                 if (retained) {
                     focusState = {
                         entry: retained,
-                        previousOrder: retained.order
+                        previousOrder: retained.order,
+                        focusedPath: retained.path
                     };
                     return createEmptyResult();
                 }
@@ -214,17 +227,34 @@ export function createInteractionController() {
             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);
+            if (!focusedEntry) {
+                return runFallbackKeyAction(event);
+            }
+            const keyEvent = createKeyEvent(event);
+            let handled = false;
+            for (const node of focusedEntry.path.slice(0, -1)) {
+                handled = dispatchTo(node, "capture", keyEvent) || handled;
+                if (keyEvent.propagationStopped) {
+                    break;
+                }
+            }
+            if (!keyEvent.propagationStopped) {
+                handled =
+                    dispatchTo(focusedEntry.node, "target", keyEvent) || handled;
             }
-            return createEmptyResult(focusedEntry.handler(event, {
-                node: focusedEntry.node,
-                isFocused: true
-            }) === true);
+            if (!keyEvent.propagationStopped) {
+                for (const node of focusedEntry.path.slice(0, -1).reverse()) {
+                    handled = dispatchTo(node, "bubble", keyEvent) || handled;
+                    if (keyEvent.propagationStopped) {
+                        break;
+                    }
+                }
+            }
+            if (!handled) {
+                return runFallbackKeyAction(event);
+            }
+            return createEmptyResult(true);
         },
         onFocusChange(listener) {
             if (disposed) {
@@ -277,7 +307,8 @@ export function createInteractionController() {
             entries = [];
             focusState = {
                 entry: null,
-                previousOrder: null
+                previousOrder: null,
+                focusedPath: []
             };
         }
     };

package/dist/dispatch.d.ts

@@ -0,0 +1,8 @@
+import type { TerminalKeyEvent } from "@bindtty/terminal";
+import type { MountedElementNode } from "@bindtty/vnode";
+import type { BindTTYKeyEvent, InteractionKeyBinding, InteractionKeyListener, InteractionResult, KeyEventPhase } from "./types.js";
+export declare function createKeyEvent(raw: TerminalKeyEvent): BindTTYKeyEvent;
+export declare function resolveKeyCaptureBinding(node: MountedElementNode): InteractionKeyListener;
+export declare function resolveKeyBinding(node: MountedElementNode): InteractionKeyBinding;
+export declare function dispatchTo(node: MountedElementNode, phase: KeyEventPhase, event: BindTTYKeyEvent): boolean;
+export declare function runTabFallback(raw: TerminalKeyEvent, moveFocus: (step: 1 | -1) => InteractionResult): InteractionResult;

package/dist/dispatch.js

@@ -0,0 +1,47 @@
+import { isShiftTabKey, isTabKey } from "./keyboard.js";
+export function createKeyEvent(raw) {
+    const event = {
+        input: raw.input,
+        name: raw.name,
+        ctrl: raw.ctrl,
+        meta: raw.meta,
+        shift: raw.shift,
+        sequence: raw.sequence,
+        phase: "target",
+        propagationStopped: false,
+        stopPropagation() {
+            event.propagationStopped = true;
+        }
+    };
+    return event;
+}
+export function resolveKeyCaptureBinding(node) {
+    return node.props.onKeyCapture;
+}
+export function resolveKeyBinding(node) {
+    return node.props.onKey;
+}
+export function dispatchTo(node, phase, event) {
+    event.phase = phase;
+    const binding = phase === "capture"
+        ? resolveKeyCaptureBinding(node)
+        : resolveKeyBinding(node);
+    if (binding === true || typeof binding !== "function") {
+        return false;
+    }
+    const handled = binding(event) === true;
+    if (handled) {
+        event.stopPropagation();
+        return true;
+    }
+    return false;
+}
+export function runTabFallback(raw, moveFocus) {
+    if (isTabKey(raw)) {
+        return isShiftTabKey(raw) ? moveFocus(-1) : moveFocus(1);
+    }
+    return {
+        handled: false,
+        dirtyNodes: []
+    };
+}

package/dist/index.d.ts

@@ -1,3 +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";
+export type { BindTTYKeyEvent, InteractionController, InteractionFocusChangeEvent, InteractionFocusChangeListener, InteractionFocusChangeReason, InteractionFocusSnapshot, InteractionKeyBinding, InteractionKeyHandler, InteractionKeyListener, InteractionNodeFocusChangeEvent, InteractionResult, IntrinsicInteractionProps, KeyEventPhase } from "./types.js";

package/dist/key-event.d.ts

@@ -0,0 +1,6 @@
+import type { TerminalKeyEvent } from "@bindtty/terminal";
+import type { MountedElementNode } from "@bindtty/vnode";
+import type { BindTTYKeyEvent, InteractionKeyContext, InteractionKeyHandler } from "./types.js";
+export declare function createBindTTYKeyEvent(terminal: TerminalKeyEvent, target: MountedElementNode, currentTarget: MountedElementNode, phase: BindTTYKeyEvent["phase"]): BindTTYKeyEvent;
+export declare function invokeKeyHandler(handler: InteractionKeyHandler, event: BindTTYKeyEvent, context: InteractionKeyContext): void;
+export declare function resolveKeyHandler(props: Record<string, unknown>, propName: "onKey" | "onKeyCapture"): InteractionKeyHandler | null;

package/dist/key-event.js

@@ -0,0 +1,45 @@
+import { resolveBindingValue } from "@bindtty/vnode";
+export function createBindTTYKeyEvent(terminal, target, currentTarget, phase) {
+    let defaultPrevented = false;
+    let propagationStopped = false;
+    return {
+        input: terminal.input,
+        name: terminal.name,
+        ctrl: terminal.ctrl,
+        meta: terminal.meta,
+        shift: terminal.shift,
+        sequence: terminal.sequence,
+        target,
+        currentTarget,
+        phase,
+        get defaultPrevented() {
+            return defaultPrevented;
+        },
+        get propagationStopped() {
+            return propagationStopped;
+        },
+        preventDefault() {
+            defaultPrevented = true;
+        },
+        stopPropagation() {
+            propagationStopped = true;
+        }
+    };
+}
+export function invokeKeyHandler(handler, event, context) {
+    const result = handler(event, context);
+    if (result === true) {
+        event.preventDefault();
+        event.stopPropagation();
+    }
+}
+export function resolveKeyHandler(props, propName) {
+    if (!Object.prototype.hasOwnProperty.call(props, propName)) {
+        return null;
+    }
+    const binding = resolveBindingValue(props[propName]);
+    if (typeof binding === "function") {
+        return binding;
+    }
+    return null;
+}

package/dist/types.d.ts

@@ -3,7 +3,6 @@ import type { BindingValue, MountedElementNode, MountedNode } from "@bindtty/vno
 export type InteractionFocusChangeReason = "initial" | "next" | "previous" | "programmatic" | "clear" | "refresh";
 export interface InteractionFocusSnapshot {
     id: string;
-    node: MountedElementNode;
 }
 export interface InteractionFocusChangeEvent {
     previous: InteractionFocusSnapshot | null;
@@ -12,19 +11,29 @@ export interface InteractionFocusChangeEvent {
 }
 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 KeyEventPhase = "capture" | "target" | "bubble";
+export interface BindTTYKeyEvent {
+    input: string;
+    name?: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    sequence?: string;
+    phase: KeyEventPhase;
+    propagationStopped: boolean;
+    stopPropagation(): void;
+}
+export type InteractionKeyHandler = (event: BindTTYKeyEvent) => boolean | void;
+export type InteractionKeyListener = InteractionKeyHandler | null | undefined;
 export type InteractionKeyBinding = boolean | InteractionKeyHandler | null | undefined;
 export interface IntrinsicInteractionProps {
     id?: BindingValue<string | number>;
+    focusable?: BindingValue<boolean>;
+    onKeyCapture?: BindingValue<InteractionKeyListener>;
     onKey?: BindingValue<InteractionKeyBinding>;
     onFocusChange?: (event: InteractionNodeFocusChangeEvent) => void;
 }
@@ -33,12 +42,6 @@ export interface InteractionResult {
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bindtty/interaction",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "type": "module",
   "description": "Keyboard focus and key dispatch layer for BindTTY.",
   "main": "./dist/index.js",
@@ -21,8 +21,8 @@
     "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.2",
-    "@bindtty/vnode": "0.1.0-alpha.2"
+    "@bindtty/terminal": "0.1.0-alpha.3",
+    "@bindtty/vnode": "0.1.0-alpha.3"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",