@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/html-ui-kit/src/nav/nav-controller.js

@@ -0,0 +1,215 @@
+// ============================================================================
+// nav-controller.ts — gamepad/keyboard spatial navigation over an html-ui doc.
+//
+// One NavController per UiPanelHandle. The doc's focusables are enumerated via
+// navSnapshot (single backend roundtrip); directional moves are resolved
+// locally with a directional-distance + alignment score (generalized from
+// Ember's useGridFocus). `data-nav-zone` on a container creates a scope; a
+// zone stack traps focus inside modals/blades and remembers the last focused
+// node per zone.
+//
+// Focus is real DOM focus (dd_osr_focus → :focus styles) plus a
+// `data-nav-focus="1"` attribute for an explicit focus ring in kit themes.
+// Confirm synthesizes a pointer click at the node's rect center, so existing
+// data-action/kit verb handlers work unchanged.
+// ============================================================================
+const DEFAULT_SEL = "[data-nav],[data-action],button,a,input,textarea,select,[tabindex],.dd-btn";
+export class NavController {
+    handle;
+    opts;
+    nodes = [];
+    dirty = true;
+    snapshotInFlight = null;
+    /** Current focused node handle (0 = none), mirrored from focus events. */
+    focused = 0;
+    /** Last nav-resolved position — used when DOM focus hasn't caught up. */
+    cursor = null;
+    zones = [];
+    zoneMemory = new Map();
+    unsubEvents = null;
+    constructor(handle, opts = {}) {
+        this.handle = handle;
+        this.opts = opts;
+        if (opts.zone !== undefined)
+            this.zones.push({ zone: opts.zone, lastFocus: 0 });
+        this.unsubEvents = handle.onEvent((ev) => {
+            if (ev.t === "focus")
+                this.focused = ev.n;
+            else if (ev.t === "blur" && this.focused === ev.n)
+                this.focused = 0;
+            // Any DOM event may imply structure changed — schedule a refresh
+            // lazily; the next nav action will see fresh state.
+        });
+    }
+    /** Re-enumerate focusables. Safe to call eagerly; concurrent calls share
+     *  one backend roundtrip. */
+    refresh() {
+        if (!this.snapshotInFlight) {
+            this.snapshotInFlight = this.handle
+                .navSnapshot(this.opts.focusableSelector ?? DEFAULT_SEL)
+                .then((nodes) => {
+                this.nodes = nodes.filter((n) => n.rect && !n.disabled);
+                this.dirty = false;
+                this.snapshotInFlight = null;
+                return this.nodes;
+            });
+        }
+        return this.snapshotInFlight;
+    }
+    /** Mark the snapshot stale (call after setHtml/mutate/resize). */
+    invalidate() {
+        this.dirty = true;
+    }
+    /** Push a zone scope — nav stays inside `zone` until popZone(). */
+    pushZone(zone) {
+        this.zoneMemory.set(this.activeZone(), this.focused);
+        this.zones.push({ zone, lastFocus: 0 });
+        this.dirty = true;
+    }
+    /** Pop the current zone scope and restore the remembered focus. */
+    popZone() {
+        if (this.zones.length === 0)
+            return;
+        this.zones.pop();
+        const remembered = this.zoneMemory.get(this.activeZone());
+        this.dirty = true;
+        if (remembered)
+            void this.focusNode(remembered);
+    }
+    activeZone() {
+        return this.zones.length ? this.zones[this.zones.length - 1].zone : null;
+    }
+    candidates() {
+        const zone = this.activeZone();
+        return zone === null ? this.nodes : this.nodes.filter((n) => n.zone === zone);
+    }
+    byNode(id) {
+        return this.nodes.find((n) => n.node === id) ?? null;
+    }
+    /** Sync lookup of the focused node in the last snapshot (may be stale —
+     *  cheap check for callers that can't await, e.g. key interception). */
+    focusedInfo() {
+        return this.focused ? this.byNode(this.focused) : null;
+    }
+    /** Focused node info, or the first candidate when nothing is focused yet. */
+    async current() {
+        if (this.dirty)
+            await this.refresh();
+        return this.cursorNode(this.candidates());
+    }
+    /** Dispatch one nav action. Async because the snapshot may refresh first. */
+    async dispatch(action) {
+        if (this.dirty)
+            await this.refresh();
+        const cands = this.candidates();
+        switch (action) {
+            case "confirm": {
+                const target = this.byNode(this.focused) ?? this.cursorNode(cands);
+                if (!target)
+                    return;
+                this.handle.click(target.node);
+                this.opts.onConfirm?.(target);
+                return;
+            }
+            case "cancel": {
+                if (this.zones.length > 1)
+                    this.popZone();
+                else
+                    this.opts.onCancel?.();
+                return;
+            }
+            case "menu":
+                this.opts.onMenu?.();
+                return;
+            case "next":
+            case "prev": {
+                this.step(action === "next" ? 1 : -1, cands);
+                return;
+            }
+            default: {
+                this.spatialMove(action, cands);
+            }
+        }
+    }
+    /** Focus a specific node (DOM focus + nav-focus attr + scroll). */
+    async focusNode(node) {
+        const info = this.byNode(node);
+        const prev = this.focused ? this.byNode(this.focused) : null;
+        this.handle.mutate([
+            ...(prev ? [{ op: "rattr", node: prev.node, name: "data-nav-focus" }] : []),
+            { op: "focus", node },
+            { op: "attr", node, name: "data-nav-focus", value: "1" },
+            { op: "scrollIntoView", node, vertical: "nearest", horizontal: "nearest" },
+        ]);
+        if (info?.rect)
+            this.cursor = info.rect;
+        this.focused = node;
+        this.opts.onMove?.(prev, info);
+    }
+    cursorNode(cands) {
+        if (this.focused) {
+            const f = this.byNode(this.focused);
+            if (f && (!this.activeZone() || f.zone === this.activeZone()))
+                return f;
+        }
+        return cands[0] ?? null;
+    }
+    /** next/prev — document-order cycle within the active zone. */
+    step(dir, cands) {
+        if (!cands.length)
+            return;
+        const cur = this.cursorNode(cands);
+        const i = cur ? cands.indexOf(cur) : -1;
+        const next = cands[(i + dir + cands.length) % cands.length];
+        void this.focusNode(next.node);
+    }
+    /**
+     * Directional pick: score = distance along the move axis + a perpendicular
+     * penalty. Rejects candidates not in the move half-plane. Falls back to a
+     * document-order step when nothing qualifies (edges of grids).
+     */
+    spatialMove(dir, cands) {
+        const cur = this.cursorNode(cands);
+        if (!cur || !cur.rect) {
+            if (cands[0])
+                void this.focusNode(cands[0].node);
+            return;
+        }
+        const c = cur.rect;
+        const cx = c.x + c.w / 2, cy = c.y + c.h / 2;
+        const horiz = dir === "left" || dir === "right";
+        const sign = dir === "down" || dir === "right" ? 1 : -1;
+        let best = null;
+        let bestScore = Infinity;
+        for (const n of cands) {
+            if (n === cur || !n.rect)
+                continue;
+            const r = n.rect;
+            const nx = r.x + r.w / 2, ny = r.y + r.h / 2;
+            const primary = horiz ? (nx - cx) * sign : (ny - cy) * sign;
+            const perp = horiz ? Math.abs(ny - cy) : Math.abs(nx - cx);
+            if (primary <= 1)
+                continue;
+            // Strongly prefer candidates overlapping the current row/column band.
+            const overlap = horiz
+                ? Math.min(c.y + c.h, r.y + r.h) - Math.max(c.y, r.y)
+                : Math.min(c.x + c.w, r.x + r.w) - Math.max(c.x, r.x);
+            const score = primary + perp * 2.5 - Math.max(0, overlap) * 1.5;
+            if (score < bestScore) {
+                bestScore = score;
+                best = n;
+            }
+        }
+        if (best) {
+            void this.focusNode(best.node);
+        }
+        else {
+            // Edge of the layout — wrap in document order (couch-UI friendly).
+            this.step(sign, cands);
+        }
+    }
+    dispose() {
+        this.unsubEvents?.();
+        this.unsubEvents = null;
+    }
+}

package/dist/libraries/html-ui-kit/src/nav/nav-input.js

@@ -0,0 +1,138 @@
+// ============================================================================
+// nav-input.ts — normalize input sources into NavAction events with
+// edge-detection and hold-repeat.
+//
+// PadNavDriver polls a GamepadSource slot each frame (call update() from the
+// app's frame loop). Directions come from dpad buttons AND the left stick
+// (with hysteresis), repeat after an initial delay; A=confirm, B=cancel,
+// START=menu, LB/RB=prev/next. KeyboardNavDriver maps arrow keys +
+// Enter/Escape/Tab onto the same action stream — desktop testing without a
+// pad, and arrow-key nav for free on any keyboard.
+// ============================================================================
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+/** Map W3C gamepad bit + axes → NavAction edges with repeat. Frame-driven. */
+export class PadNavDriver {
+    src;
+    slot;
+    dispatch;
+    opts;
+    dirs = new Map();
+    prevBtn = 0;
+    prevDirAxis = null;
+    constructor(source, slot, dispatch, opts = {}) {
+        this.src = source;
+        this.slot = slot;
+        this.dispatch = dispatch;
+        this.opts = {
+            stickThreshold: opts.stickThreshold ?? 0.5,
+            stickRelease: opts.stickRelease ?? 0.35,
+            repeatDelayMs: opts.repeatDelayMs ?? 400,
+            repeatIntervalMs: opts.repeatIntervalMs ?? 130,
+        };
+        for (const d of ["up", "down", "left", "right"]) {
+            this.dirs.set(d, { held: false, since: 0, lastFire: 0 });
+        }
+    }
+    /** Poll the pad and dispatch actions. Call once per frame. */
+    update(now = performance.now()) {
+        const snap = this.src.read(this.slot);
+        if (!snap) {
+            this.prevBtn = 0;
+            this.releaseAll();
+            return;
+        }
+        // ── Dpad buttons + stick → direction holds ──
+        const pressed = new Set();
+        const b = snap.buttonsLo;
+        if (b & (1 << GP_BTN.DPAD_UP))
+            pressed.add("up");
+        if (b & (1 << GP_BTN.DPAD_DOWN))
+            pressed.add("down");
+        if (b & (1 << GP_BTN.DPAD_LEFT))
+            pressed.add("left");
+        if (b & (1 << GP_BTN.DPAD_RIGHT))
+            pressed.add("right");
+        const lx = snap.axes[GP_AXIS.LEFT_X] ?? 0;
+        const ly = snap.axes[GP_AXIS.LEFT_Y] ?? 0;
+        // Hysteresis: engage at stickThreshold, release at stickRelease.
+        const axisDir = (prev) => {
+            const t = prev ? this.opts.stickRelease : this.opts.stickThreshold;
+            if (Math.abs(lx) < t && Math.abs(ly) < t)
+                return null;
+            return Math.abs(lx) > Math.abs(ly)
+                ? (lx > 0 ? "right" : "left")
+                : (ly > 0 ? "down" : "up");
+        };
+        const stickDir = axisDir(this.prevDirAxis);
+        this.prevDirAxis = stickDir;
+        if (stickDir)
+            pressed.add(stickDir);
+        for (const [dir, st] of this.dirs) {
+            const isDown = pressed.has(dir);
+            if (isDown && !st.held) {
+                st.held = true;
+                st.since = now;
+                st.lastFire = now;
+                this.dispatch(dir);
+            }
+            else if (isDown && st.held) {
+                if (now - st.since >= this.opts.repeatDelayMs
+                    && now - st.lastFire >= this.opts.repeatIntervalMs) {
+                    st.lastFire = now;
+                    this.dispatch(dir);
+                }
+            }
+            else if (!isDown) {
+                st.held = false;
+            }
+        }
+        // ── Buttons → discrete actions (edge-triggered) ──
+        const changed = b ^ this.prevBtn;
+        if (changed && this.opts.onButtonEdge) {
+            for (let bit = 0; bit < 20; bit++) {
+                if (changed & (1 << bit))
+                    this.opts.onButtonEdge(bit, (b & (1 << bit)) !== 0);
+            }
+        }
+        const press = (bit) => (b & (1 << bit)) !== 0 && (this.prevBtn & (1 << bit)) === 0;
+        if (press(GP_BTN.SOUTH))
+            this.dispatch("confirm");
+        if (press(GP_BTN.EAST))
+            this.dispatch("cancel");
+        if (press(GP_BTN.START))
+            this.dispatch("menu");
+        if (press(GP_BTN.LEFT_SHOULDER))
+            this.dispatch("prev");
+        if (press(GP_BTN.RIGHT_SHOULDER))
+            this.dispatch("next");
+        this.prevBtn = b;
+    }
+    releaseAll() {
+        for (const st of this.dirs.values())
+            st.held = false;
+        this.prevDirAxis = null;
+    }
+}
+const KEY_ACTIONS = {
+    38: "up", 40: "down", 37: "left", 39: "right", // arrows
+    13: "confirm", // Enter
+    27: "cancel", // Escape
+    9: "next", // Tab (shift+Tab → prev handled via event)
+};
+const KEY_NAMES = {
+    ArrowUp: "up", ArrowDown: "down", ArrowLeft: "left", ArrowRight: "right",
+    Enter: "confirm", Escape: "cancel", Tab: "next",
+};
+/** Arrow-key nav for keyboard users / dev without a pad. Accepts a DOM
+ *  keyCode (browser) or `key` string (native) — wire into the app's keydown
+ *  path; returns false for unhandled keys. */
+export function keyToNavAction(key, shiftKey = false) {
+    if (typeof key === "number") {
+        if (key === 9)
+            return shiftKey ? "prev" : "next";
+        return KEY_ACTIONS[key] ?? null;
+    }
+    if (key === "Tab")
+        return shiftKey ? "prev" : "next";
+    return KEY_NAMES[key] ?? null;
+}

package/dist/libraries/html-ui-kit/src/nav/osk.js

@@ -0,0 +1,135 @@
+// ============================================================================
+// osk.ts — engine-provided on-screen keyboard for controller-driven html-ui.
+//
+// openOsk() mounts a bottom-anchored html-ui panel of kit buttons, gives it
+// its own NavController pushed onto the "osk" zone, and forwards typed
+// characters into the *target* panel via handle.sendKey — so the focused
+// <input>/<textarea> in that doc receives real key events (text insertion,
+// backspace, Enter) exactly as if typed.
+//
+// Usage: while open, route your nav dispatch through osk.dispatch(action);
+// it returns false once closed so the app resumes its own nav.
+// ============================================================================
+import { kitStyleTag } from "../theme.js";
+import { NavController } from "./nav-controller.js";
+const ROWS = [
+    "1234567890",
+    "qwertyuiop",
+    "asdfghjkl",
+    "zxcvbnm",
+];
+const KEY_CSS = `
+/* overflow:visible — kit's body{overflow:hidden} clips everything when the
+   body has no in-flow content (.osk is absolute → body height collapses). */
+body { overflow: visible; }
+.osk { position:absolute; left:0; top:0; right:0; bottom:0; background:#0d1117;
+  display:flex; flex-direction:column; gap:6px; padding:10px; }
+.osk-row { display:flex; flex-direction:row; gap:5px; justify-content:center; }
+.osk-key { min-width:30px; text-align:center; padding:8px 6px; border-radius:5px;
+  border:1px solid #30363d; background:#1a212b; color:#e8edf2; font-size:13px; }
+.osk-key[data-nav-focus="1"] { border-color:#58a6ff; background:#26303d; }
+.osk-wide { min-width:64px; }
+.osk-preview { color:#8b98a5; font-size:12px; text-align:center; min-height:14px; }
+`;
+function keyBtn(k, wide = false) {
+    return `<div class="osk-key${wide ? " osk-wide" : ""}" data-action="osk:key" data-key="${k}">${k}</div>`;
+}
+function oskHtml() {
+    const rows = ROWS.map((r) => `<div class="osk-row">${[...r].map((k) => keyBtn(k)).join("")}</div>`).join("");
+    const ctl = `<div class="osk-row">
+    ${keyBtn("⇧", true)}${keyBtn("space", true)}${keyBtn("⌫", true)}${keyBtn("done", true)}${keyBtn("esc", true)}
+  </div>`;
+    return `<html><head>${kitStyleTag()}<style>${KEY_CSS}</style></head>
+<body><div class="osk" data-nav-zone="osk">
+  <div class="osk-preview" id="osk-preview"></div>
+  ${rows}${ctl}
+</div></body></html>`;
+}
+/**
+ * Open an OSK bound to `target` (the panel whose focused field receives the
+ * typed keys). The caller must keep routing NavActions through
+ * session.dispatch() from its pad/keyboard driver.
+ */
+export function openOsk(host, target, targetNode, opts) {
+    const height = opts.height ?? 190;
+    const panel = host.mount({
+        id: "dd-osk",
+        rect: { x: 0, y: opts.screenH - height, w: opts.screenW, h: height },
+        z: 1000,
+        scale: 1,
+        html: oskHtml(),
+    });
+    let text = opts.value ?? "";
+    let shift = false;
+    let open = true;
+    const nav = new NavController(panel, { zone: "osk" });
+    const type = (key) => {
+        const keyName = key === "space" ? " " : key === "⌫" ? "Backspace" : key === "done" ? "Enter"
+            : shift && key.length === 1 ? key.toUpperCase() : key;
+        const text = key.length === 1 ? (shift ? key.toUpperCase() : key) : key === "space" ? " " : undefined;
+        target.sendKey(true, keyName, { text });
+        target.sendKey(false, keyName, {});
+    };
+    const refreshPreview = async () => {
+        const v = await target.getAttr(targetNode, "value");
+        if (v !== null)
+            text = v;
+        panel.setText("#osk-preview", text);
+    };
+    void refreshPreview();
+    void nav.refresh();
+    const session = {
+        text: () => text,
+        dispatch(action) {
+            if (!open)
+                return false;
+            if (action === "cancel") {
+                session.close(false);
+                return false;
+            }
+            if (action === "confirm") {
+                // Which OSK key is focused (or first candidate before first move)?
+                void (async () => {
+                    const info = await nav.current();
+                    if (!info)
+                        return;
+                    const key = await panel.getAttr(info.node, "data-key");
+                    if (!key)
+                        return;
+                    if (key === "esc") {
+                        session.close(false);
+                        return;
+                    }
+                    if (key === "done") {
+                        session.close(true);
+                        return;
+                    }
+                    if (key === "⇧") {
+                        shift = !shift;
+                        panel.setAttr(info.node, "data-on", String(shift));
+                        return;
+                    }
+                    type(key);
+                    if (key !== "⇧" && shift)
+                        shift = false;
+                    void refreshPreview();
+                })();
+                return true;
+            }
+            void nav.dispatch(action);
+            return true;
+        },
+        close(commit) {
+            if (!open)
+                return;
+            open = false;
+            if (commit)
+                opts.onDone?.(text);
+            else
+                opts.onCancel?.();
+            nav.dispose();
+            panel.dispose();
+        },
+    };
+    return session;
+}

package/dist/libraries/html-ui-kit/src/nav/router.js

@@ -0,0 +1,152 @@
+// ============================================================================
+// router.ts — batteries-included nav wiring for an HtmlUiHost.
+//
+//   UiNavRouter owns one NavController per mounted panel, routes a shared
+//   input stream (any connected pad + optional keyboard) to the topmost
+//   panel, and auto-opens the OSK when a pad confirms an editable node.
+//   createHtmlUi wires this up when `nav` is enabled; games can also build
+//   one directly for bespoke integration.
+// ============================================================================
+import { NavController } from "./nav-controller.js";
+import { keyToNavAction, PadNavDriver } from "./nav-input.js";
+import { openOsk } from "./osk.js";
+/**
+ * Focus-stack + input router for controller navigation. The "active" panel
+ * is the most recently attached live panel — mount a modal on top and it
+ * captures nav; dispose it and focus returns underneath.
+ */
+export class UiNavRouter {
+    /** Master switch — false suspends pad/key routing (OSK stays interactive). */
+    enabled = true;
+    host;
+    opts;
+    ctrls = new Map();
+    order = [];
+    pads = new Map();
+    source;
+    oskSession = null;
+    /** Which device kind produced the in-flight dispatch — read by onConfirm. */
+    lastVia = "key";
+    lastTime;
+    constructor(host, opts) {
+        this.host = host;
+        this.opts = opts;
+        this.source = opts.source ?? null;
+    }
+    setScreen(w, h) {
+        this.opts = { ...this.opts, screenW: w, screenH: h };
+    }
+    /** Register a panel for navigation; returns its controller (cached). */
+    attach(handle, navOpts) {
+        let c = this.ctrls.get(handle);
+        if (c)
+            return c;
+        const userConfirm = navOpts?.onConfirm ?? this.opts.nav?.onConfirm;
+        c = new NavController(handle, {
+            ...this.opts.nav,
+            ...navOpts,
+            onConfirm: (info) => {
+                userConfirm?.(info);
+                const autoOsk = this.opts.autoOsk !== false;
+                if (info.editable && autoOsk && this.lastVia === "pad") {
+                    void this.maybeOpenOsk(handle, info.node);
+                }
+            },
+        });
+        this.ctrls.set(handle, c);
+        if (!this.order.includes(handle))
+            this.order.push(handle);
+        return c;
+    }
+    detach(handle) {
+        this.ctrls.delete(handle);
+        this.order = this.order.filter((h) => h !== handle);
+    }
+    /** Refresh nav snapshots (call after mutating structure). */
+    invalidate(handle) {
+        if (handle) {
+            this.ctrls.get(handle)?.invalidate();
+            return;
+        }
+        for (const c of this.ctrls.values())
+            c.invalidate();
+    }
+    /** NavController for the topmost attached panel. */
+    active() {
+        for (let i = this.order.length - 1; i >= 0; i--) {
+            const c = this.ctrls.get(this.order[i]);
+            if (c)
+                return c;
+        }
+        return null;
+    }
+    /** Make a specific panel's controller the nav target. */
+    setActive(handle) {
+        if (!handle)
+            return;
+        this.order = this.order.filter((h) => h !== handle);
+        this.order.push(handle);
+    }
+    /** Dispatch an action; `via` records the source device for OSK logic. */
+    dispatch(a, via = "key") {
+        this.lastVia = via;
+        if (this.oskSession) {
+            if (this.oskSession.dispatch(a))
+                return;
+            this.oskSession = null;
+        }
+        if (!this.enabled)
+            return;
+        this.active()?.dispatch(a);
+    }
+    /** Keyboard entry point — returns true when the key was consumed. */
+    handleKey(e) {
+        const a = keyToNavAction(e.key ?? e.keyCode ?? "", e.shiftKey ?? false);
+        if (!a)
+            return false;
+        // While an editable element holds DOM focus, keys belong to the doc —
+        // arrows/backspace are text input, not navigation. (OSK keys still route.)
+        if (!this.oskSession && this.active()?.focusedInfo()?.editable)
+            return false;
+        if (this.oskSession || this.enabled) {
+            this.dispatch(a, "key");
+            return true;
+        }
+        return false;
+    }
+    /** Poll connected pads — call once per frame (createHtmlUi does this). */
+    update(nowMs) {
+        if (!this.source)
+            return;
+        for (const slot of this.source.listConnected()) {
+            let d = this.pads.get(slot);
+            if (!d) {
+                d = new PadNavDriver(this.source, slot, (a) => this.dispatch(a, "pad"), this.opts.pad);
+                this.pads.set(slot, d);
+            }
+            d.update(nowMs);
+        }
+    }
+    /** Open the OSK for a node unless it opted out with `data-no-osk`. */
+    async maybeOpenOsk(handle, node) {
+        const noOsk = await handle.getAttr(node, "data-no-osk");
+        if (noOsk !== null && noOsk !== undefined)
+            return;
+        if (this.oskSession)
+            return; // an OSK may have opened meanwhile
+        this.oskSession = openOsk(this.host, handle, node, {
+            screenW: this.opts.screenW,
+            screenH: this.opts.screenH,
+            ...this.opts.osk,
+        });
+    }
+    /** While an OSK session is open, expose it (for inspection/tests). */
+    get osk() { return this.oskSession; }
+    dispose() {
+        this.oskSession?.close(false);
+        this.oskSession = null;
+        this.ctrls.clear();
+        this.order = [];
+        this.pads.clear();
+    }
+}