knobkit 0.0.1

package/src/client/app.tsx

@@ -0,0 +1,62 @@
+import "./styles.css";
+import { createElement, useCallback, useMemo, useSyncExternalStore, type ReactNode } from "react";
+import { createRoot } from "react-dom/client";
+import type { AppDecl, WidgetDecl } from "../lib/declare.js";
+import type { Path } from "../lib/bound.js";
+import type { Event } from "../lib/types.js";
+import type { Store } from "./runtime.js";
+import { VIEWS } from "./widgets/registry.js";
+
+type ByKey = Record<string, WidgetDecl>;
+
+// rebuild a widget's event constructors from the `type` strings in the decl, so a view's
+// `emit(widget.changed(v))` produces the right `{ type, payload }`.
+function rebuild(decl: WidgetDecl): Record<string, unknown> {
+  const widget: Record<string, unknown> = { type: decl.type, ...decl.props };
+  for (const [name, type] of Object.entries(decl.events)) {
+    widget[name] = (payload: unknown): Event => ({ type, payload });
+  }
+  return widget;
+}
+
+// One widget. It subscribes to its own key, so only the widget whose state (or enabled) changed
+// re-renders. The view gets `emit` (events onto the local bus) and `set` (a local state edit for its
+// own widget, e.g. an input reflecting typing — no server round-trip).
+function Field({ wd, byKey, store, emit }: { wd: WidgetDecl; byKey: ByKey; store: Store; emit: (e: Event) => void }) {
+  const subscribe = useCallback((cb: () => void) => store.subscribe(wd.key, cb), [store, wd.key]);
+  const cell = useSyncExternalStore(subscribe, () => store.cell(wd.key));
+  const widget = useMemo(() => rebuild(wd), [wd]);
+  const set = useCallback((path: Path, value: unknown) => store.applyEdit(wd.key, "set", path, value), [store, wd.key]);
+  const slot = useCallback(
+    (key: string): ReactNode => {
+      const child = byKey[key];
+      return child ? <Field key={key} wd={child} byKey={byKey} store={store} emit={emit} /> : null;
+    },
+    [byKey, store, emit],
+  );
+  const View = VIEWS[wd.type];
+  if (!View) return null;
+  return (
+    <div className={`pu-field${cell.enabled ? "" : " pu-disabled"}${cell.busy ? " pu-busy" : ""}`}>
+      {cell.busy && <div className="pu-busy-bar" role="status" aria-label="Loading" />}
+      {createElement(View, { widget, state: cell.state, enabled: cell.enabled, emit, set, slot })}
+    </div>
+  );
+}
+
+export function App({ decl, store }: { decl: AppDecl; store: Store }) {
+  const emit = (e: Event): void => store.emit(e.type, e.payload);
+  const byKey = useMemo<ByKey>(() => Object.fromEntries(decl.widgets.map((wd) => [wd.key, wd])), [decl]);
+  const rootWd = byKey[decl.root];
+  return (
+    <div className="pu-page">
+      {decl.title && <h1>{decl.title}</h1>}
+      {decl.description && <p className="pu-desc">{decl.description}</p>}
+      {rootWd && <Field wd={rootWd} byKey={byKey} store={store} emit={emit} />}
+    </div>
+  );
+}
+
+export function render(decl: AppDecl, store: Store, el: Element): void {
+  createRoot(el).render(<App decl={decl} store={store} />);
+}

package/src/client/browser-runtime.test.ts

@@ -0,0 +1,22 @@
+// @vitest-environment jsdom
+import { test, expect } from "vitest";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bundle = resolve(dirname(fileURLToPath(import.meta.url)), "../../dist/knobkit.browser.js");
+
+test.skipIf(!existsSync(bundle))("the built browser runtime mounts an app with no bundler", async () => {
+  const knobkit = (await import(/* @vite-ignore */ bundle)) as typeof import("../lib/index.js");
+
+  const box = knobkit.text();
+  const out = knobkit.json();
+  const app = knobkit.knobkit({ widgets: [box, out] }).on(box.changed, (t: string) => out.set({ typed: t }));
+
+  document.body.innerHTML = '<div id="root"></div>';
+  app.mount("#root");
+  await new Promise((r) => setTimeout(r, 50));
+
+  expect(document.querySelector("input")).not.toBeNull();
+  expect(document.querySelector("pre")).not.toBeNull();
+});

package/src/client/browser.ts

@@ -0,0 +1,3 @@
+import "./styles.css";
+import "./mount.js";
+export * from "../lib/index.js";

package/src/client/context.ts

@@ -0,0 +1,17 @@
+import { setBoundResolver, type Bound } from "../lib/bound.js";
+
+// Browser context binding for mount mode, where handlers run in-process. There is no AsyncLocalStorage
+// in the browser, so the current context is a module global set around each handler run. This is
+// correct for one in-flight handler at a time (the common case); overlapping async handlers would
+// share it.
+let current: Bound | undefined;
+setBoundResolver(() => current);
+
+export async function run(bound: Bound, fn: () => unknown): Promise<void> {
+  current = bound;
+  try {
+    await fn();
+  } finally {
+    current = undefined;
+  }
+}

package/src/client/embed.test.tsx

@@ -0,0 +1,58 @@
+// @vitest-environment jsdom
+import { test, expect } from "vitest";
+import { act } from "react";
+import { knobkit } from "../lib/knobkit.js";
+import { text, json, button, embed } from "../lib/widgets/index.js";
+import { declare } from "../lib/declare.js";
+import { mount } from "./mount.js";
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+function type(el: HTMLInputElement, value: string): void {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!;
+  setter.call(el, value);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+function countWords(box: ReturnType<typeof text>, stats: ReturnType<typeof json>) {
+  return knobkit({ widgets: [box, stats] }).on(box.changed, (t: string) =>
+    stats.set({ words: t.trim() ? t.trim().split(/\s+/).length : 0 }),
+  );
+}
+
+test("embed merges a sub-app's handlers and setups into the parent", () => {
+  const box = text();
+  const stats = json();
+  const sub = countWords(box, stats);
+  sub.setup(() => {});
+
+  const parent = knobkit({ widgets: [button({ label: "x" }), embed(sub)] });
+
+  expect(parent.handlers.has(box.changed.type)).toBe(true);
+  expect(parent.serverEvents()).toContain(box.changed.type);
+  expect(parent.setups.length).toBe(1);
+  expect(() => parent.keyFor(box)).not.toThrow();
+
+  const decl = declare(parent.config, parent.serverEvents());
+  for (const w of decl.widgets) expect(w.props.__subapp).toBeUndefined();
+  expect(decl.widgets.some((w) => w.type === "json")).toBe(true);
+});
+
+test("an embedded sub-app's handler fires through the parent store", async () => {
+  const box = text();
+  const stats = json();
+  const parent = knobkit({ widgets: embed(countWords(box, stats)) });
+  document.body.innerHTML = '<div id="root"></div>';
+
+  await act(async () => {
+    mount(parent, "#root");
+  });
+  const input = document.querySelector("input") as HTMLInputElement;
+  expect(input).not.toBeNull();
+
+  await act(async () => {
+    type(input, "hello there world");
+    await tick();
+  });
+  expect(document.querySelector("pre")!.textContent).toContain('"words": 3');
+});

package/src/client/entry.tsx

@@ -0,0 +1,25 @@
+import { io } from "socket.io-client";
+import type { AppDecl } from "../lib/declare.js";
+import type { EditOp, Path } from "../lib/bound.js";
+import { createStore, type Transport } from "./runtime.js";
+import { render } from "./app.js";
+
+// the bundled browser entry for a served app: fetch the decl, open the socket, render. A routed event
+// is sent as a tiny `request` (no state). The server applies state via `edit`/`enable`, re-emits
+// produced events via `emit`, and pulls state on demand via `read` (one attribute, answered here).
+async function boot(): Promise<void> {
+  const decl: AppDecl = await (await fetch("/api/decl")).json();
+  const socket = io({ path: "/socket.io/", transports: ["polling", "websocket"] });
+  const transport: Transport = (type, payload) => socket.emit("request", { type, payload });
+  const store = createStore(decl, transport);
+
+  socket.on("edit", (m: { key: string; op: EditOp; path: Path; value: unknown }) => store.applyEdit(m.key, m.op, m.path, m.value));
+  socket.on("enable", (m: { key: string; value: boolean }) => store.setEnabled(m.key, m.value));
+  socket.on("busy", (m: { key: string; value: boolean }) => store.setBusy(m.key, m.value));
+  socket.on("emit", (m: { type: string; payload: unknown }) => store.emit(m.type, m.payload));
+  socket.on("read", (m: { key: string; path: Path }, ack: (value: unknown) => void) => ack(store.read(m.key, m.path)));
+
+  render(decl, store, document.getElementById("root")!);
+}
+
+void boot();

package/src/client/mount.test.tsx

@@ -0,0 +1,36 @@
+// @vitest-environment jsdom
+import { test, expect } from "vitest";
+import { act } from "react";
+import { knobkit } from "../lib/knobkit.js";
+import { text, json } from "../lib/widgets/index.js";
+import { mount } from "./mount.js";
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+
+function type(el: HTMLInputElement, value: string): void {
+  const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!;
+  setter.call(el, value);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+test("mount owns state and runs on(...) handlers locally", async () => {
+  const box = text();
+  const stats = json();
+  const app = knobkit({ widgets: [box, stats] }).on(box.changed, (t: string) =>
+    stats.set({ words: t.trim() ? t.trim().split(/\s+/).length : 0 }),
+  );
+  document.body.innerHTML = '<div id="root"></div>';
+
+  await act(async () => {
+    mount(app, "#root");
+  });
+  const input = document.querySelector("input") as HTMLInputElement;
+  expect(input).not.toBeNull();
+
+  await act(async () => {
+    type(input, "hello there world");
+    await tick();
+  });
+  expect(input.value).toBe("hello there world"); // local set drove the controlled input
+  expect(document.querySelector("pre")!.textContent).toContain('"words": 3'); // local handler ran
+});

package/src/client/mount.tsx

@@ -0,0 +1,48 @@
+import "./styles.css";
+import type { Knobkit } from "../lib/knobkit.js";
+import type { Event } from "../lib/types.js";
+import { declare } from "../lib/declare.js";
+import { makeBound } from "../lib/ctx.js";
+import { createStore, type Store, type Transport } from "./runtime.js";
+import { render } from "./app.js";
+import { run } from "./context.js";
+
+const isEvent = (x: any): x is Event => x != null && typeof x.type === "string" && "payload" in x;
+
+// DOM-only, no server: the browser owns state AND runs the `on(...)` handlers locally. Same store and
+// views as serve mode; the transport invokes the knobkit's handlers in-place with a context that reads the
+// local store and applies edits to it directly. Produced events go straight back onto the store.
+export function mount(knobkit: Knobkit, selector: string): void {
+  const el = document.querySelector(selector);
+  if (!el) throw new Error(`knobkit: no element matches "${selector}"`);
+  const decl = declare(knobkit.config, knobkit.serverEvents());
+
+  let store: Store;
+  const localBound = () =>
+    makeBound({
+      read: (key, path) => Promise.resolve(store.read(key, path)),
+      edit: (key, op, path, value) => store.applyEdit(key, op, path, value),
+      enable: (key, value) => store.setEnabled(key, value),
+      busy: (key, value) => store.setBusy(key, value),
+      keyFor: (w) => knobkit.keyFor(w),
+    });
+
+  const transport: Transport = (type, payload) => {
+    const bound = localBound();
+    void (async () => {
+      for (const handler of knobkit.handlers.get(type) ?? []) {
+        await run(bound, async () => {
+          const r = await handler(payload);
+          if (isEvent(r)) store.emit(r.type, r.payload);
+        });
+      }
+    })();
+  };
+
+  store = createStore(decl, transport);
+  render(decl, store, el);
+
+  void (async () => {
+    for (const fn of knobkit.setups) await run(localBound(), fn);
+  })();
+}

package/src/client/runtime.test.ts

@@ -0,0 +1,64 @@
+import { test, expect } from "vitest";
+import { knobkit } from "../lib/knobkit.js";
+import { chat, log, text } from "../lib/widgets/index.js";
+import { declare } from "../lib/declare.js";
+import { createStore, type Transport } from "./runtime.js";
+import type { Knobkit } from "../lib/knobkit.js";
+
+function storeFor(app: Knobkit) {
+  const routed: { type: string; payload: unknown }[] = [];
+  const transport: Transport = (type, payload) => routed.push({ type, payload });
+  return { store: createStore(declare(app.config, app.serverEvents()), transport), routed };
+}
+
+test("applyEdit set/append/appendText mutate structured state by path", () => {
+  const convo = chat();
+  const lines = log();
+  const box = text();
+  const app = knobkit({ widgets: [convo, lines, box] });
+  const { store } = storeFor(app);
+
+  store.applyEdit(app.keyFor(box), "set", ["value"], "hi");
+  expect(store.read(app.keyFor(box), ["value"])).toBe("hi");
+
+  store.applyEdit(app.keyFor(lines), "append", ["lines"], "a");
+  store.applyEdit(app.keyFor(lines), "append", ["lines"], "b");
+  expect(store.read(app.keyFor(lines), ["lines"])).toEqual(["a", "b"]);
+
+  store.applyEdit(app.keyFor(convo), "append", ["messages"], { role: "assistant", content: "" });
+  store.applyEdit(app.keyFor(convo), "appendText", ["messages", -1, "content"], "hel");
+  store.applyEdit(app.keyFor(convo), "appendText", ["messages", -1, "content"], "lo");
+  expect(store.read(app.keyFor(convo), ["messages"])).toEqual([{ role: "assistant", content: "hello" }]);
+});
+
+test("an event routes to the transport only if it has a handler", () => {
+  const convo = chat();
+  const app = knobkit({ widgets: [convo] }).on(convo.sent, () => {});
+  const { store, routed } = storeFor(app);
+  store.emit(convo.sent.type, "hi");
+  expect(routed).toEqual([{ type: convo.sent.type, payload: "hi" }]);
+  store.emit(convo.recorded.type, new Float32Array()); // no handler registered
+  expect(routed).toHaveLength(1);
+});
+
+test("a disabled widget drops its own input events; enabling restores them", () => {
+  const box = text();
+  const app = knobkit({ widgets: [box] }).on(box.changed, () => {});
+  const { store, routed } = storeFor(app);
+  const key = app.keyFor(box);
+  store.setEnabled(key, false);
+  expect(store.enabled(key)).toBe(false);
+  store.emit(box.changed.type, "x");
+  expect(routed).toHaveLength(0); // dropped: authoritative
+  store.setEnabled(key, true);
+  store.emit(box.changed.type, "y");
+  expect(routed).toEqual([{ type: box.changed.type, payload: "y" }]);
+});
+
+test("read walks a path and returns undefined for a missing one", () => {
+  const convo = chat();
+  const app = knobkit({ widgets: [convo] });
+  const { store } = storeFor(app);
+  expect(store.read(app.keyFor(convo), ["messages"])).toEqual([]);
+  expect(store.read(app.keyFor(convo), ["nope"])).toBeUndefined();
+});

package/src/client/runtime.ts

@@ -0,0 +1,112 @@
+import type { AppDecl } from "../lib/declare.js";
+import type { EditOp, Path } from "../lib/bound.js";
+
+// Routes an event to its handler(s): serve emits it over the socket, mount runs the handlers in-place.
+export type Transport = (type: string, payload: unknown) => void;
+
+// A widget's renderable cell: its structured state plus its enabled/busy flags. Replaced as a unit on
+// change so a view can subscribe to one stable reference.
+export interface Cell {
+  state: unknown;
+  enabled: boolean;
+  busy: boolean;
+}
+
+export interface Store {
+  emit(type: string, payload: unknown): void;
+  applyEdit(key: string, op: EditOp, path: Path, value: unknown): void;
+  setEnabled(key: string, value: boolean): void;
+  setBusy(key: string, value: boolean): void;
+  read(key: string, path: Path): unknown;
+  cell(key: string): Cell;
+  enabled(key: string): boolean;
+  subscribe(key: string, fn: () => void): () => void;
+}
+
+function readAt(node: any, path: Path): unknown {
+  for (const p of path) {
+    if (node == null) return undefined;
+    node = Array.isArray(node) && p === -1 ? node[node.length - 1] : node[p as keyof typeof node];
+  }
+  return node;
+}
+
+// Immutably apply one structured edit at a path. -1 addresses an array's last element.
+function editAt(node: any, path: Path, op: EditOp, value: unknown): any {
+  if (path.length === 0) {
+    if (op === "set") return value;
+    if (op === "append") return [...((node as unknown[]) ?? []), value];
+    return ((node as string) ?? "") + (value as string); // appendText
+  }
+  const [head, ...rest] = path;
+  if (Array.isArray(node)) {
+    const i = head === -1 ? node.length - 1 : (head as number);
+    const copy = node.slice();
+    copy[i] = editAt(node[i], rest, op, value);
+    return copy;
+  }
+  return { ...(node as object), [head as string]: editAt(node?.[head as keyof typeof node], rest, op, value) };
+}
+
+// The browser owns all state as structured JSON, one cell per widget. The store has no per-widget
+// logic: events route to handlers (gated by enabled), edits apply generically by path, reads walk a
+// path. A change notifies only that widget's subscribers — rendering is per-key.
+export function createStore(decl: AppDecl, transport: Transport): Store {
+  const cells = new Map<string, Cell>();
+  const listeners = new Map<string, Set<() => void>>();
+  const owner = new Map<string, string>(); // an event type -> the widget key that emits it
+  const serverEvents = new Set(decl.serverEvents);
+
+  for (const w of decl.widgets) {
+    cells.set(w.key, { state: w.state, enabled: w.enabled, busy: false });
+    for (const t of Object.values(w.events)) owner.set(t, w.key);
+  }
+
+  const notify = (key: string): void => {
+    for (const fn of listeners.get(key) ?? []) fn();
+  };
+
+  const applyEdit = (key: string, op: EditOp, path: Path, value: unknown): void => {
+    const cur = cells.get(key);
+    if (!cur) return;
+    cells.set(key, { ...cur, state: editAt(cur.state, path, op, value) });
+    notify(key);
+  };
+
+  const setEnabled = (key: string, value: boolean): void => {
+    const cur = cells.get(key);
+    if (!cur || cur.enabled === value) return;
+    cells.set(key, { ...cur, enabled: value });
+    notify(key);
+  };
+
+  const setBusy = (key: string, value: boolean): void => {
+    const cur = cells.get(key);
+    if (!cur || cur.busy === value) return;
+    cells.set(key, { ...cur, busy: value });
+    notify(key);
+  };
+
+  function emit(type: string, payload: unknown): void {
+    const src = owner.get(type);
+    const c = src ? cells.get(src) : undefined;
+    if (c && (c.enabled === false || c.busy)) return; // a disabled or busy widget drops its own input events
+    if (serverEvents.has(type)) transport(type, payload);
+  }
+
+  return {
+    emit,
+    applyEdit,
+    setEnabled,
+    setBusy,
+    read: (key, path) => readAt(cells.get(key)?.state, path),
+    cell: (key) => cells.get(key)!,
+    enabled: (key) => cells.get(key)?.enabled !== false,
+    subscribe: (key, fn) => {
+      const subs = listeners.get(key) ?? new Set<() => void>();
+      subs.add(fn);
+      listeners.set(key, subs);
+      return () => subs.delete(fn);
+    },
+  };
+}

package/src/client/serve-stub.ts

@@ -0,0 +1,3 @@
+export function serve(): never {
+  throw new Error("knobkit: serve() runs a Node server and isn't available in the browser runtime; use mount()");
+}

package/src/client/styles.css

@@ -0,0 +1,131 @@
+@layer tokens, base, components;
+
+@layer tokens {
+  :root {
+    --pu-bg: #f6f7f9;
+    --pu-panel: #ffffff;
+    --pu-border: #e3e6ea;
+    --pu-text: #1c1f23;
+    --pu-muted: #6b7280;
+    --pu-accent: #2563eb;
+    --pu-accent-press: #1d4ed8;
+    --pu-radius: 12px;
+  }
+}
+
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  body {
+    margin: 0;
+    background: var(--pu-bg);
+    color: var(--pu-text);
+    font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  }
+
+  .pu-page {
+    max-width: 720px;
+    margin: 48px auto;
+    padding: 28px 28px 32px;
+    background: var(--pu-panel);
+    border: 1px solid var(--pu-border);
+    border-radius: var(--pu-radius);
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04), 0 10px 28px rgba(0, 0, 0, 0.05);
+  }
+
+  .pu-page:has(.pu-layout-row),
+  .pu-page:has(.pu-layout-grid) {
+    max-width: 1040px;
+  }
+
+  .pu-page h1 {
+    margin: 0 0 4px;
+    font-size: 24px;
+    font-weight: 650;
+    letter-spacing: -0.01em;
+  }
+
+  .pu-desc {
+    margin: 0 0 24px;
+    color: var(--pu-muted);
+  }
+
+  /* a headless widget (e.g. mic({ control: false })) renders nothing — don't leave a gap */
+  .pu-field:empty {
+    display: none;
+  }
+  /* a disabled widget: dimmed and non-interactive (the runtime also drops its input events) */
+  .pu-disabled {
+    opacity: 0.5;
+    pointer-events: none;
+  }
+  /* a busy widget: a thin indeterminate bar across its top edge (the runtime drops its input events
+     while busy). Doesn't dim or cover content, so a chat stays readable while it streams. */
+  .pu-busy {
+    position: relative;
+  }
+  .pu-busy-bar {
+    position: absolute;
+    top: 0;
+    left: 0;
+    right: 0;
+    height: 2px;
+    border-radius: 2px;
+    background: rgba(37, 99, 235, 0.15);
+    overflow: hidden;
+    z-index: 2;
+  }
+  .pu-busy-bar::after {
+    content: "";
+    position: absolute;
+    inset: 0 auto 0 0;
+    width: 40%;
+    border-radius: 2px;
+    background: var(--pu-accent);
+    animation: pu-busy-slide 1.1s ease-in-out infinite;
+  }
+  @keyframes pu-busy-slide {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(350%);
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .pu-busy-bar::after {
+      animation-duration: 2.4s;
+    }
+  }
+
+  .pu-layout {
+    display: flex;
+    gap: 18px;
+  }
+  .pu-layout-col {
+    flex-direction: column;
+  }
+  .pu-layout-row {
+    flex-direction: row;
+  }
+  .pu-layout-row > .pu-field {
+    flex: 1 1 0;
+    min-width: 0;
+  }
+  .pu-layout-grid {
+    display: grid;
+    gap: 18px;
+  }
+
+  @media (max-width: 720px) {
+    .pu-page {
+      margin: 0;
+      border: none;
+      border-radius: 0;
+      box-shadow: none;
+      min-height: 100vh;
+    }
+  }
+}

package/src/client/view.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from "react";
+import type { Path } from "../lib/bound.js";
+import type { Emit, Widget } from "../lib/types.js";
+
+// A widget's view: a pure React component that renders the widget's structured state, emits the
+// widget's events, and may `set` its own state locally (e.g. an input reflecting what's typed) without
+// a server round-trip. It lives in `client` (DOM-only); the isomorphic widget it renders lives in `lib`.
+export interface ViewProps<W extends Widget<any> = Widget<any>, S = unknown> {
+  widget: W;
+  state: S;
+  enabled: boolean;
+  emit: Emit;
+  set: (path: Path, value: unknown) => void;
+  slot: (key: string) => ReactNode;
+}
+export type WidgetView = (props: ViewProps<any, any>) => ReactNode;

package/src/client/widgets/accordion/accordion.css

@@ -0,0 +1,35 @@
+@layer components {
+  .pu-accordion {
+    border: 1px solid var(--pu-border, #e3e6ea);
+    border-radius: 8px;
+    overflow: hidden;
+  }
+  .pu-accordion-head {
+    appearance: none;
+    width: 100%;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 10px 14px;
+    background: #fafbfc;
+    border: none;
+    font: inherit;
+    font-weight: 550;
+    text-align: left;
+    cursor: pointer;
+  }
+  .pu-accordion-caret {
+    display: inline-block;
+    color: var(--pu-muted, #6b7280);
+    transition: transform 0.12s;
+  }
+  .pu-accordion-open .pu-accordion-caret {
+    transform: rotate(90deg);
+  }
+  .pu-accordion-body {
+    display: flex;
+    flex-direction: column;
+    gap: 18px;
+    padding: 16px 14px;
+  }
+}

package/src/client/widgets/accordion/index.tsx

@@ -0,0 +1,17 @@
+import "./accordion.css";
+import { useState } from "react";
+import type { ViewProps } from "../../view.js";
+
+export function AccordionView({ widget, state, slot }: ViewProps<any, { items: string[] }>) {
+  const items = state.items ?? [];
+  const [open, setOpen] = useState(widget.open !== false);
+  return (
+    <div className={`pu-accordion${open ? " pu-accordion-open" : ""}`}>
+      <button className="pu-accordion-head" aria-expanded={open} onClick={() => setOpen((o) => !o)}>
+        <span className="pu-accordion-caret">▸</span>
+        {widget.label as string}
+      </button>
+      {open && <div className="pu-accordion-body">{items.map((key) => slot(key))}</div>}
+    </div>
+  );
+}