@downdraft/engine 0.0.0 → 0.1.1

package/libraries/html-ui-kit/src/behaviors.ts

@@ -0,0 +1,250 @@
+// ============================================================================
+// behaviors.ts — bindKit(): standard interaction wiring for kit widgets.
+//
+// One handle.onEvent subscription routes every DOM event through the verb
+// table below. State changes are single setAttr mutations (CSS keys off the
+// data-* attrs); delegate callbacks let the app observe or veto behavior.
+//
+//   kit:toggle  checkbox/switch flip          → onChange(id, "toggle", on)
+//   kit:radio   radio option select           → onChange(group, "radio", i)
+//   kit:select  segmented/tab/list/table row  → onChange(id, "select", i)
+//   kit:drag    slider press+drag (self-measured via getRect)
+//                                             → onChange(id, "slider", v)
+//   kit:inc/dec number steppers               → onChange(id, "number", v)
+//   kit:open    dropdown/modal/ctx open       → onChange(id, "open", true)
+//   kit:close   backdrop/dismiss open=false   → onChange(id, "open", false)
+//   kit:choice  dropdown item pick            → onChange(id, "choice", value)
+//   kit:ctxitem context menu pick             → onAction("ctx", { value, id })
+//   kit:dismiss toast close                   → onAction("dismiss", { id })
+//   kit:node    tree expander toggle          → onAction("node", { i, open })
+//   kit:pick    tree row select               → onChange(id, "pick", path)
+//   kit:acc     accordion header toggle       → onAction("acc", { i, open })
+//   kit:press   buttons (data-verb renames)   → onAction(verb, d, ev)
+//
+// Non-action events pass through: input → onChange(id,"input",v),
+// scroll → onChange(id,"scroll",{top,left}), focus/blur/key/click/etc → onEvent.
+// ============================================================================
+
+import type { UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+import type { OsrDomEvent, DocMutation } from "@downdraft/engine/modules/html-ui";
+
+export interface KitDelegate {
+  /** State-changing widgets: toggles, selects, sliders, inputs, scrolls. */
+  onChange?(id: string, kind: string, value: unknown, ev: OsrDomEvent): void;
+  /** Command verbs: button presses, menu picks, dismissals. */
+  onAction?(verb: string, data: Record<string, string>, ev: OsrDomEvent): void;
+  /** Everything else (focus/blur/keys/clicks off kit elements). */
+  onEvent?(ev: OsrDomEvent): void;
+}
+
+export interface KitBinding {
+  dispose(): void;
+  setToggle(id: string, on: boolean): void;
+  /** Select index `i` inside a segmented/tabs/list widget (count = option n). */
+  setSelect(id: string, i: number, count: number): void;
+  setSliderValue(id: string, v: number): void;
+  setProgress(id: string, pct: number): void;
+  setOpen(id: string, open: boolean): void;
+  setInvalid(id: string, invalid: boolean): void;
+  setInputValue(id: string, v: string): void;
+  /** Show a context menu widget at doc coords; hides via kit:close. */
+  showContextMenu(id: string, x: number, y: number): void;
+}
+
+const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
+
+export function bindKit(handle: UiPanelHandle, delegate: KitDelegate = {}): KitBinding {
+  // One active slider drag at a time; rect measured on press (ev coords are
+  // doc-space CSS px, matching getRect).
+  let drag: { id: string; min: number; max: number; x0: number; w: number } | null = null;
+  // Tree row selection is a single (tree → path) map — no queryAll needed.
+  const treeSel = new Map<string, string>();
+
+  const setOn = (sel: string, on: boolean): DocMutation =>
+    ({ op: "attr", sel, name: "data-on", value: on ? "true" : "false" });
+
+  function sliderApply(d: { id: string; min: number; max: number; x0: number; w: number }, x: number) {
+    const pct = d.w > 0 ? clamp((x - d.x0) / d.w, 0, 1) : 0;
+    const v = Math.round(d.min + pct * (d.max - d.min));
+    handle.mutate([
+      { op: "attr", sel: `#${d.id}`, name: "data-value", value: String(v) },
+      { op: "style", sel: `#${d.id} [data-part="fill"]`, prop: "width", value: `${pct * 100}%` },
+      { op: "style", sel: `#${d.id} [data-part="thumb"]`, prop: "left", value: `${pct * 100}%` },
+      { op: "text", sel: `#${d.id} [data-part="value"]`, text: String(v) },
+    ]);
+    delegate.onChange?.(d.id, "slider", v, { t: "input" } as OsrDomEvent);
+  }
+
+  function route(ev: OsrDomEvent): void {
+    const d = ev.d ?? {};
+    const verb = d.action ?? "";
+    const id = d.id ?? ev.id ?? "";
+
+    // ── slider drag lifecycle ──
+    if (drag && ev.t === "pointermove") { sliderApply(drag, ev.x ?? 0); return; }
+    if (ev.t === "mouseup" && drag) { drag = null; return; }
+    if (ev.t === "mousedown" && verb === "kit:drag") {
+      const min = Number(d.min ?? 0), max = Number(d.max ?? 100);
+      handle.getRect(`#${id} [data-part="track"]`).then((r) => {
+        if (!r || !r.w) return;
+        drag = { id, min, max, x0: r.x, w: r.w };
+        sliderApply(drag, ev.x ?? r.x); // press-to-jump
+      });
+      return;
+    }
+
+    if (ev.t === "click") {
+      switch (verb) {
+        case "kit:toggle": {
+          const next = d.on !== "true";
+          handle.setAttr(`#${id}`, "data-on", next ? "true" : "false");
+          delegate.onChange?.(id, "toggle", next, ev);
+          return;
+        }
+        case "kit:radio": {
+          const i = Number(d.i ?? 0), n = Number(d.count ?? 0), g = d.group ?? id;
+          const ops: DocMutation[] = [setOn(`#${g} [data-part="opt"][data-i="${i}"]`, true)];
+          for (let k = 0; k < n; k++) {
+            if (k !== i) ops.push(setOn(`#${g} [data-part="opt"][data-i="${k}"]`, false));
+          }
+          handle.mutate(ops);
+          delegate.onChange?.(g, "radio", i, ev);
+          return;
+        }
+        case "kit:select": {
+          const i = Number(d.i ?? 0), n = Number(d.count ?? 0);
+          const ops: DocMutation[] = [setOn(`#${id} [data-i="${i}"]`, true)];
+          for (let k = 0; k < n; k++) {
+            if (k !== i) ops.push(setOn(`#${id} [data-i="${k}"]`, false));
+          }
+          handle.mutate(ops);
+          delegate.onChange?.(id, "select", i, ev);
+          return;
+        }
+        case "kit:inc": case "kit:dec": {
+          const step = Number(d.step ?? 1) * (verb === "kit:inc" ? 1 : -1);
+          handle.getAttr(`#${id}`, "value").then((raw) => {
+            const lo = d.min === "" || d.min === undefined ? -Infinity : Number(d.min);
+            const hi = d.max === "" || d.max === undefined ? Infinity : Number(d.max);
+            const v = clamp((Number(raw ?? 0) || 0) + step, lo, hi);
+            handle.setAttr(`#${id}`, "value", String(v));
+            delegate.onChange?.(id, "number", v, ev);
+          });
+          return;
+        }
+        case "kit:open":
+          handle.setAttr(`#${id}`, "data-open", d.open === "true" ? "false" : "true");
+          delegate.onChange?.(id, "open", d.open !== "true", ev);
+          return;
+        case "kit:close":
+          handle.setAttr(`#${id}`, "data-open", "false");
+          delegate.onChange?.(id, "open", false, ev);
+          return;
+        case "kit:choice": {
+          const v = d.value ?? "";
+          handle.mutate([
+            { op: "attr", sel: `#${id}`, name: "data-value", value: v },
+            { op: "attr", sel: `#${id}`, name: "data-open", value: "false" },
+            { op: "text", sel: `#${id} [data-part="label"]`, text: v },
+          ]);
+          delegate.onChange?.(id, "choice", v, ev);
+          return;
+        }
+        case "kit:ctxitem":
+          handle.setAttr(`#${id}`, "data-open", "false");
+          delegate.onAction?.("ctx", { id, value: d.value ?? "" }, ev);
+          return;
+        case "kit:dismiss":
+          handle.setStyle(`#${id}`, "display", "none");
+          delegate.onAction?.("dismiss", { id }, ev);
+          return;
+        case "kit:node": {
+          const p = d.i ?? "";
+          const open = d.open === "true" ? "false" : "true";
+          handle.mutate([
+            { op: "attr", sel: `#${id} .dd-trow[data-i="${p}"]`, name: "data-open", value: open },
+            { op: "text", sel: `#${id} .dd-trow[data-i="${p}"] .dd-caret`, text: open === "true" ? "▼" : "▶" },
+          ]);
+          delegate.onAction?.("node", { id, i: p, open }, ev);
+          return;
+        }
+        case "kit:pick": {
+          const p = d.i ?? "";
+          const prev = treeSel.get(id);
+          const ops: DocMutation[] = [setOn(`#${id} .dd-trow[data-i="${p}"]`, true)];
+          if (prev !== undefined && prev !== p) ops.push(setOn(`#${id} .dd-trow[data-i="${prev}"]`, false));
+          treeSel.set(id, p);
+          handle.mutate(ops);
+          delegate.onChange?.(id, "pick", p, ev);
+          return;
+        }
+        case "kit:acc": {
+          const i = d.i ?? "";
+          const open = d.open === "true" ? "false" : "true";
+          handle.mutate([
+            { op: "attr", sel: `#${id} .dd-as[data-i="${i}"]`, name: "data-open", value: open },
+            { op: "text", sel: `#${id} .dd-as[data-i="${i}"] .dd-caret`, text: open === "true" ? "▾" : "▸" },
+          ]);
+          delegate.onAction?.("acc", { id, i, open }, ev);
+          return;
+        }
+        case "kit:press":
+          delegate.onAction?.(d.verb ?? "press", d, ev);
+          return;
+        default:
+          break;
+      }
+    }
+
+    // ── value/event passthroughs ──
+    if (ev.t === "input") { delegate.onChange?.(id, "input", ev.v ?? "", ev); return; }
+    if (ev.t === "scroll") {
+      delegate.onChange?.(id, "scroll", { top: ev.st ?? 0, left: ev.sl ?? 0 }, ev);
+      return;
+    }
+    if (ev.t === "contextmenu") { delegate.onAction?.("contextmenu", d, ev); return; }
+    delegate.onEvent?.(ev);
+  }
+
+  const off = handle.onEvent(route);
+
+  return {
+    dispose: off,
+    setToggle: (id, onV) => { handle.setAttr(`#${id}`, "data-on", onV ? "true" : "false"); },
+    setSelect(id, i, count) {
+      const ops: DocMutation[] = [setOn(`#${id} [data-i="${i}"]`, true)];
+      for (let k = 0; k < count; k++) {
+        if (k !== i) ops.push(setOn(`#${id} [data-i="${k}"]`, false));
+      }
+      handle.mutate(ops);
+    },
+    setSliderValue(id, v) {
+      handle.getAttr(`#${id}`, "data-min").then((raw) => {
+        const min = Number(raw ?? 0);
+        handle.getAttr(`#${id}`, "data-max").then((rawMax) => {
+          const max = Number(rawMax ?? 100);
+          const pct = max > min ? clamp((v - min) / (max - min), 0, 1) : 0;
+          handle.mutate([
+            { op: "attr", sel: `#${id}`, name: "data-value", value: String(v) },
+            { op: "style", sel: `#${id} [data-part="fill"]`, prop: "width", value: `${pct * 100}%` },
+            { op: "style", sel: `#${id} [data-part="thumb"]`, prop: "left", value: `${pct * 100}%` },
+            { op: "text", sel: `#${id} [data-part="value"]`, text: String(v) },
+          ]);
+        });
+      });
+    },
+    setProgress: (id, pct) => {
+      handle.setStyle(`#${id} [data-part="fill"]`, "width", `${clamp(pct, 0, 100)}%`);
+    },
+    setOpen: (id, open) => { handle.setAttr(`#${id}`, "data-open", open ? "true" : "false"); },
+    setInvalid: (id, invalid) => { handle.setAttr(`#${id}`, "data-invalid", invalid ? "true" : "false"); },
+    setInputValue: (id, v) => { handle.setAttr(`#${id}`, "value", v); },
+    showContextMenu(id, x, y) {
+      handle.mutate([
+        { op: "attr", sel: `#${id}`, name: "data-open", value: "true" },
+        { op: "style", sel: `#${id}`, prop: "left", value: `${x}px` },
+        { op: "style", sel: `#${id}`, prop: "top", value: `${y}px` },
+      ]);
+    },
+  };
+}

package/libraries/html-ui-kit/src/components.ts

@@ -0,0 +1,309 @@
+// ============================================================================
+// components.ts — Downdraft kit widget markup builders. Every builder returns
+// an HTML string; compose them inside renderHtml()/setHtml() markup.
+//
+// Conventions understood by bindKit() (behaviors.ts):
+//   widget root : id + data-kit="<kind>"
+//   triggers    : data-action="kit:<verb>" + data-id="<widget id>"
+//   state attrs : data-on / data-open / data-selected / data-disabled
+//   parts       : data-part="<track|fill|thumb|value|opt|item|...>"
+//
+// State styling keys off data-* attributes (see theme.ts), so runtime updates
+// are single setAttr mutations — never rebuild markup for a state change.
+// ============================================================================
+
+/** Escape a string for HTML text/attr positions. */
+export function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+/** data-* attrs from a record (values escaped, `k` gets `data-` prefix). */
+export function dataAttrs(d: Record<string, string | number | boolean | undefined>): string {
+  let out = "";
+  for (const k in d) {
+    const v = d[k];
+    if (v === undefined) continue;
+    out += ` data-${k}="${esc(String(v))}"`;
+  }
+  return out;
+}
+
+const on = (v: boolean | undefined) => (v ? ` data-on="true"` : ` data-on="false"`);
+const dis = (v: boolean | undefined) => (v ? ` data-disabled="true"` : "");
+
+// ── primitives ──
+
+export interface ButtonOpts {
+  id?: string; label: string; kind?: "normal" | "accent" | "danger" | "ghost";
+  disabled?: boolean; on?: boolean;
+  /** Custom action verb; defaults to kit:press handled by onAction passthrough. */
+  action?: string; data?: Record<string, string | number>;
+}
+export function button(o: ButtonOpts): string {
+  const id = o.id ?? `btn-${o.label.replace(/\W+/g, "-").toLowerCase()}`;
+  return `<div class="dd-btn" id="${esc(id)}" data-kit="button" data-action="kit:press" data-id="${esc(id)}"` +
+    `${o.kind ? ` data-kind="${o.kind}"` : ""}${o.action ? ` data-verb="${esc(o.action)}"` : ""}` +
+    `${on(o.on)}${dis(o.disabled)}${o.data ? dataAttrs(o.data) : ""}>${esc(o.label)}</div>`;
+}
+
+export function badge(o: { label: string; kind?: "default" | "accent" | "good" | "warn" | "bad" }): string {
+  return `<div class="dd-badge" data-kind="${o.kind ?? "default"}">${esc(o.label)}</div>`;
+}
+
+export function label(text: string): string {
+  return `<div class="dd-label">${esc(text)}</div>`;
+}
+
+export function sectionLabel(text: string): string {
+  return `<div class="dd-section">${esc(text)}</div>`;
+}
+
+export function divider(): string {
+  return `<div class="dd-divider"></div>`;
+}
+
+export function spacer(px: number): string {
+  return `<div style="height:${px}px"></div>`;
+}
+
+export function panel(html: string, extraStyle = ""): string {
+  return `<div class="dd-panel" style="${extraStyle}">${html}</div>`;
+}
+
+export function row(html: string): string {
+  return `<div class="dd-row">${html}</div>`;
+}
+
+export function col(html: string): string {
+  return `<div class="dd-col">${html}</div>`;
+}
+
+// ── toggles ──
+
+export interface ToggleOpts { id: string; label?: string; on?: boolean; disabled?: boolean }
+
+export function checkbox(o: ToggleOpts): string {
+  return `<div class="dd-check" id="${esc(o.id)}" data-kit="checkbox" data-action="kit:toggle"` +
+    ` data-id="${esc(o.id)}"${on(o.on)}${dis(o.disabled)}>` +
+    `<div class="dd-box">${o.on ? "X" : ""}</div>${o.label ? `<div class="dd-lbl">${esc(o.label)}</div>` : ""}</div>`;
+}
+
+export function switchToggle(o: ToggleOpts): string {
+  return `<div class="dd-switch" id="${esc(o.id)}" data-kit="switch" data-action="kit:toggle"` +
+    ` data-id="${esc(o.id)}"${on(o.on)}${dis(o.disabled)}>` +
+    `<div class="dd-rail"><div class="dd-knob"></div></div>${o.label ? `<div class="dd-lbl">${esc(o.label)}</div>` : ""}</div>`;
+}
+
+export interface RadioOpts { id: string; options: string[]; selected?: number; disabled?: boolean }
+export function radioGroup(o: RadioOpts): string {
+  const opts = o.options.map((label, i) =>
+    `<div class="dd-opt" data-part="opt" data-action="kit:radio" data-id="${esc(o.id)}"` +
+    ` data-group="${esc(o.id)}" data-i="${i}"${on(o.selected === i)}${dis(o.disabled)}>` +
+    `<div class="dd-dot"></div><div class="dd-lbl">${esc(label)}</div></div>`).join("");
+  return `<div class="dd-radio" id="${esc(o.id)}" data-kit="radio" data-count="${o.options.length}">${opts}</div>`;
+}
+
+// ── value widgets ──
+
+export interface SliderOpts {
+  id: string; label?: string; min?: number; max?: number; value?: number;
+  showValue?: boolean; disabled?: boolean; width?: number;
+}
+export function slider(o: SliderOpts): string {
+  const min = o.min ?? 0, max = o.max ?? 100, v = o.value ?? min;
+  const pct = max > min ? ((v - min) / (max - min)) * 100 : 0;
+  const w = o.width ? ` style="width:${o.width}px"` : "";
+  return `<div class="dd-slider" id="${esc(o.id)}" data-kit="slider" data-min="${min}" data-max="${max}" data-value="${v}"${dis(o.disabled)}${w}>` +
+    (o.label || o.showValue
+      ? `<div class="dd-srow"><span>${esc(o.label ?? "")}</span><span data-part="value">${v}</span></div>`
+      : "") +
+    `<div class="dd-track" data-part="track" data-action="kit:drag" data-id="${esc(o.id)}">` +
+    `<div class="dd-fill" data-part="fill" style="width:${pct}%"></div>` +
+    `<div class="dd-thumb" data-part="thumb" style="left:${pct}%"></div></div></div>`;
+}
+
+export function progressBar(o: { id?: string; value: number; kind?: "good" | "accent" | "warn" | "bad" }): string {
+  const pct = Math.max(0, Math.min(100, o.value));
+  return `<div class="dd-progress"${o.id ? ` id="${esc(o.id)}"` : ""} data-kit="progress"` +
+    `${o.kind ? ` data-kind="${o.kind}"` : ""}><div class="dd-pfill" data-part="fill" style="width:${pct}%"></div></div>`;
+}
+
+export function spinner(o: { id?: string; size?: number } = {}): string {
+  const s = o.size ?? 18;
+  return `<div class="dd-spinner"${o.id ? ` id="${esc(o.id)}"` : ""} style="width:${s}px;height:${s}px"></div>`;
+}
+
+// ── text inputs ──
+
+export interface InputOpts {
+  id: string; label?: string; value?: string; placeholder?: string;
+  disabled?: boolean; invalid?: boolean; width?: number;
+}
+export function textInput(o: InputOpts): string {
+  const input = `<input class="dd-input" id="${esc(o.id)}" data-kit="input" data-id="${esc(o.id)}"` +
+    ` type="text" value="${esc(o.value ?? "")}"${o.placeholder ? ` placeholder="${esc(o.placeholder)}"` : ""}` +
+    `${dis(o.disabled)}${o.invalid ? ` data-invalid="true"` : ""}${o.width ? ` style="width:${o.width}px"` : ""}>`;
+  return o.label ? `<div class="dd-field"><div class="dd-lbl">${esc(o.label)}</div>${input}</div>` : input;
+}
+
+export function textArea(o: InputOpts & { rows?: number }): string {
+  const area = `<textarea class="dd-textarea" id="${esc(o.id)}" data-kit="textarea" data-id="${esc(o.id)}"` +
+    `${dis(o.disabled)}${o.invalid ? ` data-invalid="true"` : ""}${o.width ? ` style="width:${o.width}px"` : ""}` +
+    `${o.rows ? ` style="height:${o.rows * 18}px"` : ""}>${esc(o.value ?? "")}</textarea>`;
+  return o.label ? `<div class="dd-field"><div class="dd-lbl">${esc(o.label)}</div>${area}</div>` : area;
+}
+
+export interface NumberFieldOpts extends InputOpts { min?: number; max?: number; step?: number }
+export function numberField(o: NumberFieldOpts): string {
+  const v = o.value ?? "0";
+  return `<div class="dd-field"><div class="dd-lbl">${esc(o.label ?? "")}</div>` +
+    `<div class="dd-num" data-kit="number" data-id="${esc(o.id)}" data-min="${o.min ?? ""}"` +
+    ` data-max="${o.max ?? ""}" data-step="${o.step ?? 1}">` +
+    `<input class="dd-input" id="${esc(o.id)}" type="text" value="${esc(String(v))}"${o.width ? ` style="width:${o.width ?? 110}px"` : ""}${dis(o.disabled)}>` +
+    `<div class="dd-btn dd-step" data-action="kit:inc" data-id="${esc(o.id)}">+</div>` +
+    `<div class="dd-btn dd-step" data-action="kit:dec" data-id="${esc(o.id)}">−</div></div></div>`;
+}
+
+// ── pickers ──
+
+export interface SegmentedOpts { id: string; options: string[]; selected?: number; disabled?: boolean }
+export function segmented(o: SegmentedOpts): string {
+  const opts = o.options.map((label, i) =>
+    `<div class="dd-o" data-part="opt" data-action="kit:select" data-id="${esc(o.id)}"` +
+    ` data-i="${i}" data-count="${o.options.length}"${on(o.selected === i)}${dis(o.disabled)}>${esc(label)}</div>`).join("");
+  return `<div class="dd-seg" id="${esc(o.id)}" data-kit="segmented">${opts}</div>`;
+}
+
+export interface TabsOpts { id: string; tabs: string[]; selected?: number }
+export function tabs(o: TabsOpts): string {
+  const ts = o.tabs.map((t, i) =>
+    `<div class="dd-t" data-part="tab" data-action="kit:select" data-id="${esc(o.id)}"` +
+    ` data-i="${i}" data-count="${o.tabs.length}"${on(o.selected === i)}>${esc(t)}</div>`).join("");
+  return `<div class="dd-tabs" id="${esc(o.id)}" data-kit="tabs">${ts}</div>`;
+}
+
+export interface DropdownOpts {
+  id: string; options: string[]; selected?: number; placeholder?: string;
+  disabled?: boolean; width?: number;
+}
+export function dropdown(o: DropdownOpts): string {
+  const sel = o.selected !== undefined ? o.options[o.selected] : (o.placeholder ?? "Select…");
+  const items = o.options.map((opt, i) =>
+    `<div class="dd-mi" data-action="kit:choice" data-id="${esc(o.id)}" data-i="${i}"` +
+    ` data-value="${esc(opt)}"${on(o.selected === i)}>${esc(opt)}</div>`).join("");
+  return `<div class="dd-dd" id="${esc(o.id)}" data-kit="dropdown" data-value="${esc(sel ?? "")}" data-open="false"` +
+    `${o.width ? ` style="width:${o.width}px"` : ""}${dis(o.disabled)}>` +
+    `<div class="dd-ddbtn" data-action="kit:open" data-id="${esc(o.id)}">` +
+    `<span data-part="label">${esc(sel ?? "")}</span><span class="dd-caret">▾</span></div>` +
+    `<div class="dd-menu" data-part="menu">${items}</div></div>`;
+}
+
+export interface MenuItem { label: string; value?: string; sep?: boolean }
+export function menu(items: MenuItem[], actionPrefix = "kit:choice", id = ""): string {
+  const body = items.map((it) => it.sep
+    ? `<div class="dd-msep"></div>`
+    : `<div class="dd-mi" data-action="${actionPrefix}"${id ? ` data-id="${esc(id)}"` : ""}` +
+      ` data-value="${esc(it.value ?? it.label)}">${esc(it.label)}</div>`).join("");
+  return `<div class="dd-menu" data-part="menu" style="display:block;position:static">${body}</div>`;
+}
+
+// ── collections ──
+
+export interface ListOpts { id: string; items: string[]; selected?: number; height?: number }
+export function listView(o: ListOpts): string {
+  const items = o.items.map((it, i) =>
+    `<div class="dd-li" data-part="item" data-action="kit:select" data-id="${esc(o.id)}"` +
+    ` data-i="${i}" data-count="${o.items.length}"${on(o.selected === i)}>${esc(it)}</div>`).join("");
+  return `<div class="dd-list" id="${esc(o.id)}" data-kit="list" data-count="${o.items.length}"` +
+    ` style="height:${o.height ?? 120}px">${items}</div>`;
+}
+
+export function scrollView(o: { id: string; html: string; height?: number }): string {
+  return `<div class="dd-scroll" id="${esc(o.id)}" data-kit="scroll" data-id="${esc(o.id)}"` +
+    ` style="height:${o.height ?? 140}px">${o.html}</div>`;
+}
+
+export interface TableOpts { id?: string; cols: string[]; rows: string[][]; selected?: number }
+export function dataTable(o: TableOpts): string {
+  const head = `<tr>${o.cols.map((c) => `<th>${esc(c)}</th>`).join("")}</tr>`;
+  const body = o.rows.map((r, i) =>
+    `<tr${o.id ? ` data-action="kit:select" data-id="${esc(o.id)}" data-i="${i}" data-count="${o.rows.length}"` : ""}${on(o.selected === i)}>` +
+    `${r.map((c) => `<td>${esc(c)}</td>`).join("")}</tr>`).join("");
+  return `<table class="dd-table"${o.id ? ` id="${esc(o.id)}" data-kit="table"` : ""}>${head}${body}</table>`;
+}
+
+export interface TreeNode { label: string; children?: TreeNode[]; open?: boolean }
+function treeNodes(id: string, nodes: TreeNode[], path: string, selected?: string): string {
+  return nodes.map((n, i) => {
+    const p = path ? `${path}.${i}` : `${i}`;
+    const kids = n.children?.length
+      ? `<div class="dd-kids">${treeNodes(id, n.children, p, selected)}</div>` : "";
+    const caret = n.children?.length
+      ? `<div class="dd-caret" data-action="kit:node" data-id="${esc(id)}" data-i="${p}">${n.open === false ? "▶" : "▼"}</div>`
+      : `<div class="dd-caret"></div>`;
+    return `<div class="dd-trow" data-i="${p}" data-action="kit:pick" data-id="${esc(id)}"` +
+      `${on(selected === p)}${n.children?.length ? ` data-open="${n.open !== false}"` : ""}>` +
+      `${caret}<div>${esc(n.label)}</div></div>${kids}`;
+  }).join("");
+}
+export function treeView(o: { id: string; nodes: TreeNode[]; selected?: string; height?: number }): string {
+  return `<div class="dd-tree dd-list" id="${esc(o.id)}" data-kit="tree"` +
+    ` style="height:${o.height ?? 140}px">${treeNodes(o.id, o.nodes, "", o.selected)}</div>`;
+}
+
+export interface AccordionSection { title: string; html: string; open?: boolean }
+export function accordion(o: { id: string; sections: AccordionSection[] }): string {
+  const secs = o.sections.map((s, i) =>
+    `<div class="dd-as" data-i="${i}" data-open="${s.open !== false}">` +
+    `<div class="dd-ah" data-action="kit:acc" data-id="${esc(o.id)}" data-i="${i}">` +
+    `<span>${esc(s.title)}</span><span class="dd-caret">${s.open !== false ? "▾" : "▸"}</span></div>` +
+    `<div class="dd-ab">${s.html}</div></div>`).join("");
+  return `<div class="dd-acc dd-col" id="${esc(o.id)}" data-kit="accordion">${secs}</div>`;
+}
+
+// ── overlays ──
+
+export function modal(o: { id: string; title: string; html: string; open?: boolean; buttons?: string }): string {
+  return `<div class="dd-modal" id="${esc(o.id)}" data-kit="modal" data-open="${o.open ? "true" : "false"}">` +
+    `<div class="dd-backdrop" data-action="kit:close" data-id="${esc(o.id)}"></div>` +
+    `<div class="dd-dlg"><div class="dd-dtitle">${esc(o.title)}</div>${o.html}` +
+    (o.buttons ? `<div class="dd-dbtns">${o.buttons}</div>` : "") + `</div></div>`;
+}
+
+export function tooltipWrap(html: string, tip: string): string {
+  return `<div class="dd-tipwrap">${html}<div class="dd-tip">${esc(tip)}</div></div>`;
+}
+
+export function contextMenu(o: { id: string; items: MenuItem[]; x?: number; y?: number; open?: boolean }): string {
+  const items = o.items.map((it) => it.sep
+    ? `<div class="dd-msep"></div>`
+    : `<div class="dd-mi" data-action="kit:ctxitem" data-id="${esc(o.id)}"` +
+      ` data-value="${esc(it.value ?? it.label)}">${esc(it.label)}</div>`).join("");
+  return `<div class="dd-ctx" id="${esc(o.id)}" data-kit="ctxmenu" data-open="${o.open ? "true" : "false"}"` +
+    ` style="left:${o.x ?? 0}px;top:${o.y ?? 0}px">${items}</div>`;
+}
+
+export type ToastKind = "good" | "warn" | "bad" | "info";
+export interface Toast { id: string; kind?: ToastKind; message: string }
+export function toastStack(toasts: Toast[]): string {
+  const items = toasts.map((t) =>
+    `<div class="dd-toast" id="${esc(t.id)}" data-kind="${t.kind ?? "good"}"><div>${esc(t.message)}</div>` +
+    `<div class="dd-x" data-action="kit:dismiss" data-id="${esc(t.id)}">✕</div></div>`).join("");
+  return `<div class="dd-toasts" data-kit="toasts">${items}</div>`;
+}
+
+// ── misc ──
+
+export function toolbar(html: string): string {
+  return `<div class="dd-toolbar">${html}</div>`;
+}
+
+export function kvTable(rows: Array<[string, string]>): string {
+  return rows.map(([k, v]) =>
+    `<div class="dd-kv"><div class="dd-k">${esc(k)}</div><div class="dd-v">${esc(v)}</div></div>`).join("");
+}
+
+export function fieldError(msg: string, id?: string): string {
+  return `<div class="dd-err"${id ? ` id="${esc(id)}"` : ""}>${esc(msg)}</div>`;
+}

package/libraries/html-ui-kit/src/index.ts

@@ -0,0 +1,30 @@
+// ============================================================================
+// html-ui-kit — themed widget kit for the Blitz html-ui stack.
+//
+//   import * as kit from "@downdraft/engine/libraries/html-ui-kit";
+//   const handle = host.mount({ rect, html: `<html><head>${kit.kitStyleTag()}</head>
+//     <body>${kit.button({ label: "Go" })}${kit.slider({ id: "vol", value: 50 })}…` });
+//   const kb = kit.bindKit(handle, { onChange: (id, kind, v) => … });
+// ============================================================================
+
+export { bindKit } from "./behaviors";
+export type { KitBinding, KitDelegate } from "./behaviors";
+export {
+    accordion, badge, button, checkbox, col, contextMenu, dataAttrs, dataTable, divider, dropdown, esc, fieldError, kvTable, label, listView, menu, modal, numberField, panel, progressBar, radioGroup, row, scrollView, sectionLabel, segmented, slider, spacer, spinner, switchToggle, tabs, textArea, textInput, toastStack,
+    toolbar, tooltipWrap, treeView
+} from "./components";
+export type { AccordionSection, ButtonOpts, DropdownOpts, InputOpts, ListOpts, MenuItem, NumberFieldOpts, RadioOpts, SegmentedOpts, SliderOpts, TableOpts, TabsOpts, Toast, ToastKind, ToggleOpts, TreeNode } from "./components";
+export { NavController } from "./nav/nav-controller";
+export type { NavAction, NavControllerOptions, NavDirection } from "./nav/nav-controller";
+export { keyToNavAction, PadNavDriver } from "./nav/nav-input";
+export type { NavInputOptions } from "./nav/nav-input";
+export { openOsk } from "./nav/osk";
+export type { OskOptions, OskSession } from "./nav/osk";
+export { UiNavRouter } from "./nav/router";
+export type { UiNavRouterOptions } from "./nav/router";
+export { PadCursorDriver, VirtualCursor } from "./nav/vcursor";
+export type { PadCursorOptions, VirtualCursorOptions } from "./nav/vcursor";
+export { blade, commandPalette, detailPanel, mediaCard, mediaGrid, settingsRow, shelf, tvCss } from "./ten-foot";
+export type { MediaCardOpts, PaletteItem } from "./ten-foot";
+export { KIT_CSS, KIT_FONT_FAMILY, kitStyleTag } from "./theme";
+