@downdraft/engine 0.0.0 → 0.1.0

package/libraries/html-ui-kit/src/nav/nav-controller.ts

@@ -0,0 +1,238 @@
+// ============================================================================
+// 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.
+// ============================================================================
+
+import type { NavNodeInfo, UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+
+export type NavDirection = "up" | "down" | "left" | "right";
+export type NavAction = NavDirection | "confirm" | "cancel" | "next" | "prev" | "menu";
+
+export interface Rect { x: number; y: number; w: number; h: number }
+
+export interface NavControllerOptions {
+  /** Selector enumerating focusable nodes. Default covers kit widgets,
+   *  links, inputs and explicit opt-ins. */
+  focusableSelector?: string;
+  /** Initial zone restriction (a `data-nav-zone` value). */
+  zone?: string;
+  onConfirm?: (info: NavNodeInfo) => void;
+  onCancel?: () => void;
+  onMenu?: () => void;
+  onMove?: (from: NavNodeInfo | null, to: NavNodeInfo | null) => void;
+}
+
+const DEFAULT_SEL =
+  "[data-nav],[data-action],button,a,input,textarea,select,[tabindex],.dd-btn";
+
+interface ZoneFrame {
+  zone: string | null;
+  /** Node id that was focused when this zone was left (zone memory). */
+  lastFocus: number;
+}
+
+export class NavController {
+  private handle: UiPanelHandle;
+  private opts: NavControllerOptions;
+  private nodes: NavNodeInfo[] = [];
+  private dirty = true;
+  private snapshotInFlight: Promise<NavNodeInfo[]> | null = 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. */
+  private cursor: Rect | null = null;
+  private zones: ZoneFrame[] = [];
+  private zoneMemory = new Map<string | null, number>();
+  private unsubEvents: (() => void) | null = null;
+
+  constructor(handle: UiPanelHandle, opts: NavControllerOptions = {}) {
+    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(): Promise<NavNodeInfo[]> {
+    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(): void {
+    this.dirty = true;
+  }
+
+  /** Push a zone scope — nav stays inside `zone` until popZone(). */
+  pushZone(zone: string | null): void {
+    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(): void {
+    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(): string | null {
+    return this.zones.length ? this.zones[this.zones.length - 1].zone : null;
+  }
+
+  private candidates(): NavNodeInfo[] {
+    const zone = this.activeZone();
+    return zone === null ? this.nodes : this.nodes.filter((n) => n.zone === zone);
+  }
+
+  private byNode(id: number): NavNodeInfo | null {
+    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(): NavNodeInfo | null {
+    return this.focused ? this.byNode(this.focused) : null;
+  }
+
+  /** Focused node info, or the first candidate when nothing is focused yet. */
+  async current(): Promise<NavNodeInfo | null> {
+    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: NavAction): Promise<void> {
+    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: number): Promise<void> {
+    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" } as const] : []),
+      { 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);
+  }
+
+  private cursorNode(cands: NavNodeInfo[]): NavNodeInfo | null {
+    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. */
+  private step(dir: 1 | -1, cands: NavNodeInfo[]): void {
+    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).
+   */
+  private spatialMove(dir: NavDirection, cands: NavNodeInfo[]): void {
+    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: NavNodeInfo | null = 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(): void {
+    this.unsubEvents?.();
+    this.unsubEvents = null;
+  }
+}

package/libraries/html-ui-kit/src/nav/nav-input.ts

@@ -0,0 +1,145 @@
+// ============================================================================
+// 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 type { GamepadSource } from "@downdraft/engine/input/local-player-manager";
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+import type { NavAction, NavDirection } from "./nav-controller";
+
+export interface NavInputOptions {
+  /** Stick magnitude that counts as a direction press (default 0.5). */
+  stickThreshold?: number;
+  /** Release threshold — must be < stickThreshold for stable edges (default 0.35). */
+  stickRelease?: number;
+  /** ms before a held direction repeats (default 400). */
+  repeatDelayMs?: number;
+  /** ms between repeats while held (default 130). */
+  repeatIntervalMs?: number;
+  /** Edge hook for every button transition (mapped nav buttons included) —
+   *  lets apps bind unmapped buttons (SELECT-mode toggles, etc.). */
+  onButtonEdge?: (bit: number, down: boolean) => void;
+}
+
+type DirectionState = { held: boolean; since: number; lastFire: number };
+
+/** Map W3C gamepad bit + axes → NavAction edges with repeat. Frame-driven. */
+export class PadNavDriver {
+  private src: GamepadSource;
+  private slot: number;
+  private dispatch: (a: NavAction) => void;
+  private opts: Required<Omit<NavInputOptions, "onButtonEdge">> & Pick<NavInputOptions, "onButtonEdge">;
+  private dirs = new Map<NavDirection, DirectionState>();
+  private prevBtn = 0;
+  private prevDirAxis: NavDirection | null = null;
+
+  constructor(source: GamepadSource, slot: number, dispatch: (a: NavAction) => void, opts: NavInputOptions = {}) {
+    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"] as const) {
+      this.dirs.set(d, { held: false, since: 0, lastFire: 0 });
+    }
+  }
+
+  /** Poll the pad and dispatch actions. Call once per frame. */
+  update(now = performance.now()): void {
+    const snap = this.src.read(this.slot);
+    if (!snap) { this.prevBtn = 0; this.releaseAll(); return; }
+
+    // ── Dpad buttons + stick → direction holds ──
+    const pressed = new Set<NavDirection>();
+    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: NavDirection | null): NavDirection | null => {
+      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: number) => (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;
+  }
+
+  private releaseAll(): void {
+    for (const st of this.dirs.values()) st.held = false;
+    this.prevDirAxis = null;
+  }
+}
+
+const KEY_ACTIONS: Record<number, NavAction> = {
+  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: Record<string, NavAction> = {
+  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: number | string, shiftKey = false): NavAction | null {
+  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/libraries/html-ui-kit/src/nav/osk.ts

@@ -0,0 +1,153 @@
+// ============================================================================
+// 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 type { HtmlUiHost, UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+import { kitStyleTag } from "../theme";
+import { NavController, type NavAction } from "./nav-controller";
+
+export interface OskOptions {
+  /** Screen-space size for bottom anchoring. */
+  screenW: number;
+  screenH: number;
+  /** Panel height in CSS px (default 190). */
+  height?: number;
+  /** Initial text shown in the preview row (read from the field if unset). */
+  value?: string;
+  onDone?(text: string): void;
+  onCancel?(): void;
+}
+
+export interface OskSession {
+  /** Route nav actions here while open; returns false once closed. */
+  dispatch(action: NavAction): boolean;
+  /** Current text as last read from the target field. */
+  text(): string;
+  close(commit: boolean): void;
+}
+
+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: string, wide = false): string {
+  return `<div class="osk-key${wide ? " osk-wide" : ""}" data-action="osk:key" data-key="${k}">${k}</div>`;
+}
+
+function oskHtml(): string {
+  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: HtmlUiHost,
+  target: UiPanelHandle,
+  targetNode: number | string,
+  opts: OskOptions,
+): OskSession {
+  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: string) => {
+    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: OskSession = {
+    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;
+}