@hypen-space/web 0.4.980 → 0.5.3

package/dist/dom/operability.js

@@ -0,0 +1,298 @@
+/**
+ * Keyboard operability for actionable elements.
+ *
+ * Native interactive elements (`<button>`, `<a href>`) are keyboard-operable
+ * for free — the browser activates them on Enter/Space. But Hypen's actionable
+ * `Card` renders a plain `<div>`, which is neither focusable nor
+ * keyboard-activatable. This module closes that gap: a non-native actionable
+ * host is given a `button` role, made focusable (`tabindex=0`), and wired so
+ * Enter/Space dispatch the same action as a click.
+ *
+ * This is intentionally client-side: focus and key handling are synchronous
+ * interactions the streaming engine cannot mediate.
+ */
+import { triggerElementAction } from "./applicators/events.js";
+import { getMeta, setMeta } from "./element-data.js";
+import { focusRouteTarget } from "./route-focus.js";
+/** Host tags that the browser already makes keyboard-operable. */
+const NATIVE_INTERACTIVE = new Set(["BUTTON", "A"]);
+/**
+ * Make a non-native actionable element keyboard-operable. Idempotent across
+ * re-renders (guarded by a dataset flag). No-op for native interactive tags.
+ */
+export function makeKeyboardActivatable(element, actionValue) {
+    const tag = element.tagName?.toUpperCase();
+    if (tag && NATIVE_INTERACTIVE.has(tag))
+        return;
+    // The keydown listener reads the action from element meta, so a later
+    // re-apply with a different action retargets keyboard activation exactly
+    // as it does the click listener — no stale action, no second listener.
+    setMeta(element, "kbdAction", actionValue);
+    // Wire the keydown listener only once.
+    if (element.dataset?.hypenKbd)
+        return;
+    if (element.dataset)
+        element.dataset.hypenKbd = "1";
+    // Announce as a button, make it reachable, and activate on Enter/Space.
+    element.setAttribute("role", "button");
+    element.tabIndex = 0;
+    element.addEventListener("keydown", (event) => {
+        const key = event.key;
+        if (key === "Enter" || key === " " || key === "Spacebar") {
+            // Space would otherwise scroll the page.
+            event.preventDefault?.();
+            triggerElementAction(element, getMeta(element, "kbdAction"));
+        }
+    });
+}
+/** CSS selector for the elements that can hold keyboard focus. */
+const FOCUSABLE_SELECTOR = "a,button,input,textarea,select,[tabindex]";
+/**
+ * Pick the focus target for a Tab keypress within a trapped container, wrapping
+ * at the ends.
+ *
+ * Pure over the ordered list of focusable descendants so it is testable without
+ * a real DOM: given the currently-focused element (`active`) and the Shift
+ * state, returns the element that should receive focus next, or `null` when
+ * there is nothing to focus. Tab past the last element wraps to the first;
+ * Shift+Tab past the first wraps to the last. When focus is outside the set,
+ * Tab lands on the first element and Shift+Tab on the last.
+ */
+export function nextTrapFocus(focusable, active, shift) {
+    if (focusable.length === 0)
+        return null;
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    const index = active == null ? -1 : focusable.indexOf(active);
+    if (index === -1)
+        return shift ? last : first;
+    if (shift)
+        return index === 0 ? last : focusable[index - 1];
+    return index === focusable.length - 1 ? first : focusable[index + 1];
+}
+/**
+ * Pick the tab that should receive focus for a keypress inside a roving
+ * tablist (WAI-ARIA APG "Tabs" keyboard contract). Pure over the ordered tab
+ * list so it is testable without a real DOM: Arrow Right/Down move to the
+ * next tab (wrapping), Arrow Left/Up to the previous (wrapping), Home/End to
+ * the first/last. Any other key — or an empty list — returns `null` (leave
+ * focus alone).
+ */
+export function nextRovingFocus(tabs, active, key) {
+    if (tabs.length === 0)
+        return null;
+    const first = tabs[0];
+    const last = tabs[tabs.length - 1];
+    if (key === "Home")
+        return first;
+    if (key === "End")
+        return last;
+    const forward = key === "ArrowRight" || key === "ArrowDown";
+    const backward = key === "ArrowLeft" || key === "ArrowUp";
+    if (!forward && !backward)
+        return null;
+    const index = active == null ? -1 : tabs.indexOf(active);
+    if (index === -1)
+        return first;
+    if (forward)
+        return index === tabs.length - 1 ? first : tabs[index + 1];
+    return index === 0 ? last : tabs[index - 1];
+}
+/**
+ * Pick the item typeahead should move focus to (WAI-ARIA APG first-character
+ * navigation). Pure over the ordered item list so it is testable without a
+ * real DOM: the search is a case-insensitive `startsWith` over `textOf(item)`,
+ * starting from the item AFTER `active` and wrapping; `active` itself is the
+ * last candidate, so a query the current item already matches keeps focus in
+ * place (multi-char accumulation refining onto the same item). Returns `null`
+ * when nothing matches or the query is empty. Query accumulation and its
+ * timeout live at the caller.
+ */
+export function nextTypeaheadFocus(items, active, query, textOf) {
+    if (items.length === 0 || query.length === 0)
+        return null;
+    const q = query.toLowerCase();
+    const start = active == null ? -1 : items.indexOf(active);
+    for (let step = 1; step <= items.length; step++) {
+        const item = items[(start + step + items.length) % items.length];
+        if (textOf(item).trim().toLowerCase().startsWith(q))
+            return item;
+    }
+    return null;
+}
+/** Pause after which an accumulated typeahead query starts over. */
+const TYPEAHEAD_RESET_MS = 500;
+/**
+ * Shared roving-tabindex installer for composite widgets (tablist, listbox):
+ * arrow keys move focus among the `itemSelector` descendants (wrapping),
+ * Home/End jump to the ends, and only the focused item stays in the page Tab
+ * order (`tabindex=0`; the rest drop to `-1`) so a single Tab keypress leaves
+ * the widget. Printable characters accumulate into a short-lived typeahead
+ * query (reset after a 500ms pause, tracked by timestamp — no timers) that
+ * roves to the next item whose text starts with the query. Space is excluded:
+ * it activates the focused item, and stealing it would break native Button
+ * hosts. Activation stays with the item's own click/Enter handling —
+ * selection is app state, not focus state. Idempotent across re-renders,
+ * guarded by a dataset flag.
+ */
+function installRovingWidget(container, itemSelector) {
+    if (container.dataset?.hypenRoving)
+        return;
+    if (container.dataset)
+        container.dataset.hypenRoving = "1";
+    const itemsOf = () => Array.from(container.querySelectorAll(itemSelector));
+    const rove = (target, items) => {
+        for (const item of items) {
+            item.tabIndex = item === target ? 0 : -1;
+        }
+        target.focus?.();
+    };
+    let typeahead = "";
+    let typeaheadAt = 0;
+    container.addEventListener("keydown", (event) => {
+        const keyEvent = event;
+        const key = keyEvent.key;
+        const items = itemsOf();
+        const focused = (container.ownerDocument?.activeElement ?? null);
+        const active = focused && items.includes(focused) ? focused : null;
+        let target = nextRovingFocus(items, active, key);
+        if (!target &&
+            key.length === 1 &&
+            key !== " " &&
+            !keyEvent.ctrlKey &&
+            !keyEvent.metaKey &&
+            !keyEvent.altKey) {
+            const now = Date.now();
+            if (now - typeaheadAt > TYPEAHEAD_RESET_MS)
+                typeahead = "";
+            typeaheadAt = now;
+            typeahead += key;
+            target = nextTypeaheadFocus(items, active, typeahead, (item) => item.textContent ?? "");
+        }
+        if (target) {
+            event.preventDefault?.();
+            rove(target, items);
+        }
+    });
+    // First entry into the widget establishes the roving state (focused item
+    // reachable, siblings parked at -1) without needing any keydown first.
+    container.addEventListener("focusin", (event) => {
+        const items = itemsOf();
+        const focused = event.target;
+        if (focused && items.includes(focused)) {
+            for (const item of items) {
+                item.tabIndex = item === focused ? 0 : -1;
+            }
+        }
+    });
+}
+/**
+ * Install the WAI-ARIA APG "Tabs" keyboard contract on a tablist container:
+ * roving tabindex over the `role="tab"` descendants plus first-character
+ * typeahead (see `installRovingWidget`).
+ */
+export function makeRovingTablist(container) {
+    installRovingWidget(container, '[role="tab"]');
+}
+/**
+ * Install the WAI-ARIA APG "Listbox" keyboard contract on a listbox
+ * container: roving tabindex over the `role="option"` descendants plus
+ * first-character typeahead (see `installRovingWidget`). No-op for a native
+ * `<select>` host (Hypen's `Select`), where the browser already owns arrow
+ * and typeahead behaviour.
+ */
+export function makeRovingListbox(container) {
+    if (container.tagName?.toUpperCase() === "SELECT")
+        return;
+    installRovingWidget(container, '[role="option"]');
+}
+/**
+ * Install a focus trap on a dialog-like container: Tab / Shift+Tab cycle focus
+ * among the container's focusable descendants and wrap at the ends. Closing is
+ * app state: Escape is handled by `installDialogEscape` only when the dialog
+ * declares an `onClose` action. Idempotent across re-renders, guarded by a
+ * dataset flag.
+ */
+export function makeFocusTrap(container) {
+    if (container.dataset?.hypenTrap)
+        return;
+    if (container.dataset)
+        container.dataset.hypenTrap = "1";
+    container.addEventListener("keydown", (event) => {
+        if (event.key !== "Tab")
+            return;
+        const focusable = Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR));
+        const active = (container.ownerDocument?.activeElement ?? null);
+        const target = nextTrapFocus(focusable, active, event.shiftKey === true);
+        if (target) {
+            event.preventDefault?.();
+            target.focus?.();
+        }
+    });
+}
+/** Tags that can hold focus without a tabindex — the DFS twin of `FOCUSABLE_SELECTOR`. */
+const FOCUSABLE_TAGS = new Set(["A", "BUTTON", "INPUT", "TEXTAREA", "SELECT"]);
+/**
+ * First focusable descendant of `root` in document order, or `null`. Matches
+ * the focus trap's element set (`FOCUSABLE_SELECTOR`) but walks `children`
+ * recursively instead of `querySelectorAll`, so it works on hosts without
+ * selector support (test doubles) — document order is exactly child order.
+ */
+export function findFirstFocusable(root) {
+    const children = Array.from((root.children ?? []));
+    for (const child of children) {
+        const tag = child.tagName?.toUpperCase() ?? "";
+        if (FOCUSABLE_TAGS.has(tag) || child.getAttribute?.("tabindex") != null)
+            return child;
+        const nested = findFirstFocusable(child);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/**
+ * Dialog auto-focus on mount (WAI-ARIA APG "Dialog (Modal)"): focus the
+ * dialog's first focusable descendant, else the dialog itself (granted
+ * programmatic focusability by `focusRouteTarget`). Returns the element that
+ * held focus before the dialog opened, so the caller can restore it on close.
+ */
+export function focusDialogOnOpen(dialog) {
+    const doc = dialog.ownerDocument ?? (typeof document !== "undefined" ? document : null);
+    const previous = (doc?.activeElement ?? null);
+    focusRouteTarget(findFirstFocusable(dialog) ?? dialog);
+    return previous;
+}
+/**
+ * Restore focus to the element that had it before a dialog opened. Skipped
+ * when the opener is gone: no longer connected to the document, or living
+ * inside the (now closed) dialog itself.
+ */
+export function restoreDialogFocus(dialog, opener) {
+    if (!opener)
+        return;
+    if (dialog === opener || dialog.contains?.(opener))
+        return;
+    if (opener.isConnected === false)
+        return;
+    opener.focus?.();
+}
+/**
+ * Escape-to-close for a dialog that declares an `onClose` action: Escape
+ * dispatches the action; the actual close (state flip, unmount) stays with
+ * the app. A dialog without `onClose` gets no Escape behaviour — the renderer
+ * cannot know how to close it. Idempotent across re-renders, guarded by a
+ * dataset flag.
+ */
+export function installDialogEscape(dialog, onCloseValue) {
+    if (dialog.dataset?.hypenDialogEsc)
+        return;
+    if (dialog.dataset)
+        dialog.dataset.hypenDialogEsc = "1";
+    dialog.addEventListener("keydown", (event) => {
+        if (event.key !== "Escape")
+            return;
+        event.preventDefault?.();
+        triggerElementAction(dialog, onCloseValue);
+    });
+}
+//# sourceMappingURL=operability.js.map

package/dist/dom/operability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operability.js","sourceRoot":"","sources":["../../src/dom/operability.ts"],"names":[],"mappings":"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"}

package/dist/dom/renderer.d.ts

@@ -12,6 +12,17 @@ import { type DebugConfig } from "./debug.js";
 interface IEngine {
     dispatchAction(name: string, payload?: any): void;
 }
+export interface DOMRendererOptions {
+    /**
+     * Route-change focus contract (route-focus.ts). `"auto"` (default) moves
+     * focus to the incoming route's first heading / `main` landmark / subtree
+     * root on every navigation. `"off"` skips `focusIncomingRoute` entirely —
+     * the escape hatch for authors who own focus management themselves (custom
+     * transition choreography, embedded shells) and would otherwise fight the
+     * renderer for focus on every navigation.
+     */
+    routeFocus?: "auto" | "off";
+}
 export declare class DOMRenderer {
     private container;
     private nodes;
@@ -24,12 +35,45 @@ export declare class DOMRenderer {
     private globalContext;
     private componentInstances;
     private debugTracker;
+    /**
+     * Text elements whose template contains an `@{...}` binding, with the
+     * template pre-compiled into segments. Only these nodes are visited on
+     * state changes — static text never re-interpolates.
+     */
+    private textBindings;
     private canvasRenderers;
     private canvasSubtreeMap;
+    private canvasNodeChildren;
+    private canvasNodeParent;
     private canvasElements;
     /** Props stashed at create-time so we can forward them to CanvasRenderer */
     private pendingCreateProps;
-    constructor(container: HTMLElement, engine: IEngine, debugConfig?: Partial<DebugConfig>);
+    /**
+     * Focus-restore memory for the Router subtree cache, keyed by detached
+     * subtree root id: the element that held focus when the route was
+     * detached, restored on cached re-`attach`. Entries are dropped on
+     * `remove` (Router LRU eviction) so focus restore can never target an
+     * evicted NodeId — the route-focus contract (see route-focus.ts).
+     */
+    private routeFocusMemory;
+    /** See `DOMRendererOptions.routeFocus` — `"off"` disables `focusIncomingRoute`. */
+    private routeFocus;
+    /** Ids created with `semantics.role === "dialog"`, so insert/remove hooks can act. */
+    private dialogIds;
+    /**
+     * Open dialog id → the element that held focus before the dialog took it
+     * (the trigger), restored on dialog remove/detach when still connected.
+     * Presence of an entry means "already focused" — re-inserts (moves) of an
+     * open dialog never re-run the mount focus.
+     */
+    private dialogOpeners;
+    /**
+     * Dialog ids inserted during the current batch. Mount focus runs after the
+     * whole batch, because a dialog's focusable children may be inserted after
+     * the dialog's own insert patch.
+     */
+    private pendingDialogMounts;
+    constructor(container: HTMLElement, engine: IEngine, debugConfig?: Partial<DebugConfig>, options?: DOMRendererOptions);
     /**
      * Set router and global context for component composition
      */
@@ -42,11 +86,37 @@ export declare class DOMRenderer {
      * the DOMRenderer or the owning CanvasRenderer.
      */
     applyPatches(patches: Patch[]): void;
+    /**
+     * Apply the dialog focus contract to dialogs inserted by the finished
+     * batch: focus the first focusable descendant, else the dialog itself, and
+     * remember the previously-focused element (the trigger) for restore on
+     * close. Deferred to batch end so descendants inserted after the dialog's
+     * own insert patch are visible to the focus search.
+     */
+    private flushDialogMounts;
+    /**
+     * Apply the route-focus contract to a freshly-shown route subtree: restore
+     * the remembered focus of a cached route when it is still inside the
+     * subtree, otherwise land on the first heading / main landmark / the
+     * subtree root (see route-focus.ts for the full contract).
+     */
+    private focusIncomingRoute;
     /**
      * Determine which canvas root (if any) a patch should be routed to.
      * Returns the canvas root node ID, or undefined for DOM patches.
      */
     private getCanvasRouteTarget;
+    /**
+     * Record a node as a member of a canvas subtree, tracking its parent link
+     * so a later `remove` can prune the whole subtree from the routing maps.
+     */
+    private registerCanvasMember;
+    /**
+     * Drop a removed canvas node and all of its descendants from the canvas
+     * routing maps. The engine emits `remove` only for the subtree root, so
+     * descendants are walked via the tracked child links.
+     */
+    private pruneCanvasSubtree;
     /**
      * Update state and interpolate text content
      */
@@ -56,19 +126,35 @@ export declare class DOMRenderer {
      */
     private mergeComponentState;
     /**
-     * Interpolate state values in all text elements
+     * Interpolate state values in all binding-bearing text elements
      */
     private interpolateAllText;
     /**
-     * Interpolate state values in text template.
+     * Resolve a compiled template against the current state.
      *
-     * Bindings use the `@{state.path}` syntax (matching the engine's parser).
+     * Bindings use the `@{state.path}` syntax (matching the engine's parser);
+     * unresolvable bindings render as their original `@{...}` text.
      */
-    private interpolateText;
+    private interpolateSegments;
+    /**
+     * Keep the binding index in sync with the element's stored template:
+     * register text elements whose template contains an `@{...}` binding,
+     * drop everything else.
+     */
+    private syncTextBinding;
     /**
      * Apply a single patch.
      */
     private applyPatch;
+    /**
+     * Reactive accessibility update: re-run the create-time semantics
+     * translation on the live element with the node's complete re-resolved
+     * block. `applySemantics` is idempotent and clears attributes it set on a
+     * previous pass that the new block no longer produces. This is the sole
+     * ARIA writer for bound self-state — the SetProp that accompanies a bound
+     * `.expanded(@state.open)` change does not touch ARIA attributes.
+     */
+    private onSetSemantics;
     /**
      * Create a new element
      */
@@ -111,6 +197,13 @@ export declare class DOMRenderer {
      * route subtrees alive between navigations.
      */
     private onDetach;
+    /**
+     * Close-side of the dialog focus contract: every open dialog at-or-under
+     * `subtree` has left the document — restore focus to its remembered
+     * trigger (when still connected) and drop the open entry so a later
+     * insert/attach counts as a fresh mount.
+     */
+    private restoreDialogsWithin;
     /**
      * Remove an element from the tree
      */