claude-artifact-framework 0.16.0 → 0.18.0

package/README.md

@@ -168,6 +168,18 @@ ArtifactKit.createApp({
 Field keys must be unique across all steps (they share one data pool); a
 duplicate throws at creation, as does an unknown step key.
 
+A result step can end on more than stats: give it `blocks` and any block
+set (a chart of the answers, explanatory text, a list) renders under the
+result grid:
+
+```js
+{ title: "Resultado",
+  result: (d) => [{ label: "Libre por mes", value: libre(d), format: "money", big: true }],
+  blocks: [{ title: "Distribución", chart: (d) => ({ type: "donut", format: "money", items: porRubro(d) }) }] }
+```
+
+`blocks` on a non-result step throws.
+
 ### The `chart` block — bar, line, donut
 
 Same vocabulary as `output` (items of `{ label, value }` plus an optional
@@ -343,12 +355,13 @@ blocks: [
 ```
 
 Action keys: `label`, `run`, optional `when` (hides the button when false)
-and `kind` (`"primary"` / `"danger"`). Row actions receive
-`(record, data, viewerId)`, block actions `(data, viewerId)`. Stopping
-early is fine (`run: (r) => ...`), but **never skip a middle argument**:
-`run: (r, viewerId)` reads `data` as your viewer id and breaks silently —
-if you need `viewerId`, name everything before it: `run: (r, d, viewerId)`.
-Changes persist like any other update.
+and `kind` (`"primary"` / `"danger"`). Row actions — `when` and `run`
+alike — receive `(record, data, viewerId)`; block actions
+`(data, viewerId)`. Stopping early is fine (`run: (r) => ...`), and the
+framework matches the viewer id **by name**: a second parameter literally
+named `viewerId` receives the viewer id even though `data` was skipped —
+`run: (r, viewerId) => ...` works as written. Still, prefer the full
+order: `run: (r, d, viewerId)`. Changes persist like any other update.
 Give the constructive action `kind: "primary"` — a "Vote"/"Add"/"Done" left
 as the neutral default reads weaker than a `"danger"` next to it. And a
 smell to avoid: **a number that changes by pressing is an `action`, not an
@@ -422,6 +435,30 @@ The active tab and each accordion's open/closed state are framework-owned
 view state — they survive reload, per viewer. Tabs cannot nest inside tabs;
 `when` must be a function; both throw otherwise.
 
+**When tabs ARE the app** — one tabs block as the whole UI, 4-5 sections
+the user hops between on a phone — declare bottom navigation:
+
+```js
+ArtifactKit.createApp({
+  title: "Mi Gym",
+  mobile: { nav: "bottom" },
+  blocks: [
+    { tabs: [
+      { label: "Hoy", icon: "💪", blocks: [...] },
+      { label: "Progreso", icon: "📈", blocks: [...] },
+      // ...up to ~5 sections
+    ], wide: true },
+  ],
+})
+```
+
+On a phone the first top-level tabs block's bar pins to the bottom of the
+screen (icons above labels, every section visible and thumb-reachable);
+on desktop nothing changes. Measured reason to bother: a top tab bar with
+5 sections overflows sideways at phone width and silently hides the last
+sections behind a scroll nobody sees. Declaring `mobile: { nav: "bottom" }`
+without a top-level tabs block throws.
+
 ### The `machine` — declared phases instead of hand-rolled state logic
 
 If your app has **phases** — a game (choosing → comparing → won), a turn
@@ -832,7 +869,8 @@ Everything an app can declare, in one place.
 
 **Top-level keys**: `title`, `subtitle`, `theme: { seed }`, `layout`, `blocks`,
 `records`, `steps`, `chat`, `main`, `sidebar` (workspace panes), `documents`,
-`data`, `shared`, `libs`. Anything else throws.
+`data`, `shared`, `libs`, `machine`, `brand`, `mobile: { nav: "bottom" }`.
+Anything else throws.
 
 **Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
 list), `steps` (wizard), `chat` (conversation with Claude), `workspace`
@@ -968,8 +1006,9 @@ The rules that decide whether a generated app works, all in one place
    or `ctx.files`.
 5. **Phases belong to the `machine`** — never track game/process phases
    with hand-rolled flags and `setTimeout`; `ctx.send` is the only door.
-6. **Never skip a middle positional argument** — `run: (r, d, viewerId)`,
-   never `run: (r, viewerId)`.
+6. **Row callbacks are `(record, data, viewerId)`** — `when` and `run`
+   alike. Prefer the full order; a second parameter literally named
+   `viewerId` is matched by name and still gets the viewer id.
 7. **One `big: true` per screen** — it marks THE result, not every stat.
 8. **The constructive action takes `kind: "primary"`**; a counter changed
    by pressing is an `action`, not an editable `number` field.

package/dist/index.esm.js

@@ -1070,6 +1070,19 @@ function recordDefaults(fields) {
 function makeId() {
   return "r" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
 }
+var rowCallLegacy = /* @__PURE__ */ new WeakMap();
+function rowCall(fn, rec, data, viewerId) {
+  let legacy = rowCallLegacy.get(fn);
+  if (legacy === void 0) {
+    const src = String(fn);
+    const arrow = src.match(/^\s*(?:async\s+)?([\w$]+)\s*=>/);
+    const parens = src.match(/^[^(]*\(([^)]*)\)/);
+    const params = arrow ? [arrow[1]] : parens ? parens[1].split(",").map((s) => s.trim().split(/[=\s:]/)[0]) : [];
+    legacy = /viewer|voter|usuario|user/i.test(params[1] || "");
+    rowCallLegacy.set(fn, legacy);
+  }
+  return legacy ? fn(rec, viewerId) : fn(rec, data, viewerId);
+}
 function Avatar({ title, ctx }) {
   const initials = String(title).split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase() || "?";
   let hash = 0;
@@ -1174,7 +1187,7 @@ function ListScreen({ spec, ctx }) {
         spec.actions ? createElement(
           "div",
           { className: "caf-row-actions" },
-          spec.actions.filter((a) => !a.when || a.when(rec, ctx.viewerId)).map(
+          spec.actions.filter((a) => !a.when || rowCall(a.when, rec, ctx.data, ctx.viewerId)).map(
             (a) => createElement(
               "button",
               {
@@ -1183,7 +1196,7 @@ function ListScreen({ spec, ctx }) {
                 className: a.kind === "danger" ? "caf-btn caf-btn-danger caf-btn-sm" : "caf-btn caf-btn-sm",
                 onClick: () => ctx.update((d) => {
                   const live = d.records.find((x) => x.id === rec.id);
-                  if (live) a.run(live, d, ctx.viewerId);
+                  if (live) rowCall(a.run, live, d, ctx.viewerId);
                 })
               },
               a.label
@@ -1354,23 +1367,31 @@ function stepErrors(step, data) {
 }
 function ResultScreen({ step, ctx }) {
   const items = step.result(ctx.data) || [];
+  const Block2 = ctx._Block;
   return createElement(
     "div",
-    { className: "caf-block caf-output" },
-    step.title ? createElement("h2", { className: "caf-block-title" }, step.title) : null,
+    { className: "caf-steps-result" },
     createElement(
       "div",
-      { className: "caf-output-grid" },
-      items.map(
-        (item, i) => createElement(
-          "div",
-          { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
-          createElement("span", { className: "caf-stat-label" }, item.label),
-          createElement("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
-          item.hint ? createElement("small", { className: "caf-hint" }, item.hint) : null
+      { className: "caf-block caf-output" },
+      step.title ? createElement("h2", { className: "caf-block-title" }, step.title) : null,
+      createElement(
+        "div",
+        { className: "caf-output-grid" },
+        items.map(
+          (item, i) => createElement(
+            "div",
+            { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
+            createElement("span", { className: "caf-stat-label" }, item.label),
+            createElement("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+            item.hint ? createElement("small", { className: "caf-hint" }, item.hint) : null
+          )
         )
       )
     ),
+    // A result can end on more than stats: any declared blocks (charts,
+    // text, lists) render under the grid with full block services.
+    (step.blocks || []).map((b, i) => createElement(Block2, { key: "rb" + i, block: b, ctx })),
     createElement(
       "div",
       { className: "caf-step-nav" },
@@ -1438,7 +1459,8 @@ var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "colla
 var BRAND_KEYS = ["logo", "footer"];
 var BANNER_KEYS = ["image", "title", "subtitle"];
 var IMAGE_KEYS = ["src", "caption", "fit", "height"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand"];
+var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents", "machine", "brand", "mobile"];
+var MOBILE_KEYS = ["nav"];
 var MACHINE_KEYS = ["key", "initial", "states", "events"];
 var MACHINE_STATE_KEYS = ["after"];
 var MACHINE_AFTER_KEYS = ["seconds", "then", "do"];
@@ -1641,6 +1663,14 @@ function checkMachine(m) {
     }
   }
 }
+function findNavTabs(spec) {
+  for (const list of [spec.blocks, spec.main]) {
+    if (!Array.isArray(list)) continue;
+    const found = list.find((b) => b && Array.isArray(b.tabs));
+    if (found) return found;
+  }
+  return null;
+}
 function validate(spec) {
   const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
   if (unknownTop.length) {
@@ -1665,6 +1695,22 @@ function validate(spec) {
       throw new Error("claude-artifact-framework: `libs` must be an array of https:// script URLs.");
     }
   }
+  if (spec.mobile !== void 0) {
+    const unknownM = Object.keys(spec.mobile || {}).filter((k) => !MOBILE_KEYS.includes(k));
+    if (unknownM.length) {
+      throw new Error(
+        `claude-artifact-framework: mobile has unknown keys (${unknownM.join(", ")}). Valid keys: ${MOBILE_KEYS.join(", ")}.`
+      );
+    }
+    if (spec.mobile.nav !== void 0 && spec.mobile.nav !== "bottom") {
+      throw new Error('claude-artifact-framework: mobile.nav only accepts "bottom" (omit `mobile` for the default top tab bar).');
+    }
+    if (spec.mobile.nav === "bottom" && !findNavTabs(spec)) {
+      throw new Error(
+        'claude-artifact-framework: mobile.nav: "bottom" moves a top-level `tabs` block\'s bar to the bottom of the phone screen \u2014 this spec has no top-level tabs block (in `blocks` or `main`) to move.'
+      );
+    }
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
@@ -1676,7 +1722,7 @@ function validate(spec) {
     if (!Array.isArray(steps) || steps.length === 0) {
       throw new Error('claude-artifact-framework: layout "steps" needs `steps: [...]` with at least one step.');
     }
-    const STEP_KEYS = ["title", "text", "fields", "result"];
+    const STEP_KEYS = ["title", "text", "fields", "result", "blocks"];
     const seen = /* @__PURE__ */ new Set();
     steps.forEach((st, i) => {
       if (!st || typeof st !== "object") {
@@ -1691,6 +1737,12 @@ function validate(spec) {
       if (!st.fields && !st.text && !st.result) {
         throw new Error(`claude-artifact-framework: steps[${i}] needs \`fields\`, \`text\`, or \`result\`.`);
       }
+      if (st.blocks !== void 0) {
+        if (typeof st.result !== "function") {
+          throw new Error(`claude-artifact-framework: steps[${i}].blocks only renders on a result step \u2014 add \`result\` or move the blocks to the step's fields.`);
+        }
+        checkBlocks(st.blocks);
+      }
       checkFields(st.fields, `steps[${i}]`);
       for (const f of st.fields || []) {
         if (seen.has(f.key)) {
@@ -1946,17 +1998,18 @@ function boundary(React2) {
   }
   return BlockBoundary;
 }
-function TabsBlock({ spec, ctx }) {
+function TabsBlock({ spec, ctx, bottomNav }) {
   const tabs = spec.tabs;
   const key = tabs.map((t) => t.label).join("|");
   const stored = ctx.view.tabs ? ctx.view.tabs[key] : void 0;
   const active = Math.min(stored === void 0 ? 0 : stored, tabs.length - 1);
+  const bottom = !!bottomNav && ctx.viewport === "mobile";
   return createElement(
     "div",
     { className: "caf-tabs" },
     createElement(
       "div",
-      { className: "caf-tabbar", role: "tablist" },
+      { className: bottom ? "caf-tabbar caf-tabbar-bottom" : "caf-tabbar", role: "tablist" },
       tabs.map(
         (t, i) => createElement(
           "button",
@@ -1968,7 +2021,7 @@ function TabsBlock({ spec, ctx }) {
             className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
             onClick: () => ctx.setTab(key, i)
           },
-          t.icon ? `${t.icon} ${t.label}` : t.label
+          bottom && t.icon ? [createElement("span", { key: "i", className: "caf-tab-ico", "aria-hidden": true }, t.icon), createElement("span", { key: "l", className: "caf-tab-lbl" }, t.label)] : t.icon ? `${t.icon} ${t.label}` : t.label
         )
       )
     ),
@@ -1984,13 +2037,14 @@ var ALL_NAMES = [...BLOCK_NAMES, "tabs", "records"];
 function Block({ block, ctx }) {
   if (typeof block.when === "function" && !block.when(ctx.data)) return null;
   if (block.state !== void 0 && ctx.machine && ctx.data[ctx.machine.key || "fase"] !== block.state) return null;
+  const bottomNav = ctx._navTabs !== void 0 && ctx._navTabs === block;
   if (block.icon && typeof block.title === "string") block = { ...block, title: `${block.icon} ${block.title}` };
   const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
   const Component2 = ALL_BLOCKS[name];
   const inner = createElement(
     boundary(ctx.React),
     null,
-    createElement(Component2, { spec: block.collapsible ? { ...block, title: void 0 } : block, ctx })
+    createElement(Component2, { spec: block.collapsible ? { ...block, title: void 0 } : block, ctx, bottomNav })
   );
   if (!block.collapsible) return inner;
   const key = typeof block.title === "string" && block.title ? block.title : name;
@@ -2194,7 +2248,10 @@ function DocumentsLayout({ spec, ctx }) {
     { className: "caf-documents" },
     createElement(DocTabbar, { docs, active, dspec, types, close, onAdd, label, ctx }),
     typePicker,
-    createElement(Panel, { spec: { blocks: aspec.blocks }, ctx: scoped })
+    // Keyed by document id: switching tabs REMOUNTS the pane, so DOM-held
+    // state can't leak across documents. Measured: the native file input
+    // kept showing the previous document's filename.
+    createElement(Panel, { key: active.id, spec: { blocks: aspec.blocks }, ctx: scoped })
   );
 }
 function DocTabbar({ docs, active, dspec, types, close, onAdd, label, ctx }) {
@@ -2376,6 +2433,9 @@ function createApp(spec = {}) {
       toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
       viewport: narrow ? "mobile" : "desktop",
+      _navTabs: narrow && spec.mobile && spec.mobile.nav === "bottom" ? findNavTabs(spec) : null,
+      _Block: Block,
+      // for layouts in other modules (steps) that render blocks
       machine: spec.machine || null,
       send: spec.machine ? (eventName, payload) => runMachineEvent(spec.machine, state.update, eventName, payload) : () => {
         throw new Error("claude-artifact-framework: ctx.send() needs a `machine` declared at the top level.");
@@ -2392,7 +2452,7 @@ function createApp(spec = {}) {
       "div",
       // The layout class lets shared CSS follow the active container width —
       // e.g. the header must share the workspace's wider axis, not panel's.
-      { className: `caf-root caf-layout-${layout}` },
+      { className: `caf-root caf-layout-${layout}${ctx._navTabs ? " caf-has-bottomnav" : ""}` },
       createElement("style", { dangerouslySetInnerHTML: { __html: css } }),
       createElement(
         "header",
@@ -2410,7 +2470,13 @@ function createApp(spec = {}) {
         { className: "caf-block caf-block-error" },
         createElement("strong", null, "A library failed to load"),
         createElement("code", null, libsError)
-      ) : !state.isHydrated() || libsState === "loading" ? createElement("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries\u2026" : "Loading\u2026") : createElement(Layout, { spec, ctx }),
+      ) : !state.isHydrated() || libsState === "loading" ? createElement("div", { className: "caf-block caf-loading" }, libsState === "loading" ? "Loading libraries\u2026" : "Loading\u2026") : (
+        // The same containment blocks get, one level up: a crash inside a
+        // layout (a throwing sort, a bad row callback) shows a named error
+        // under the header instead of killing the whole app. Measured: an
+        // unhandled row-action throw once blanked an entire blind app.
+        createElement(boundary(ctx.React), null, createElement(Layout, { spec, ctx }))
+      ),
       spec.brand && spec.brand.footer ? createElement("footer", { className: "caf-footer" }, spec.brand.footer) : null
     );
   };
@@ -2533,6 +2599,7 @@ var BASE_CSS = `
 .caf-timer-controls { display: flex; gap: 0.6rem; }
 .caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
 .caf-steps-progress { display: flex; flex-direction: column; gap: 0.35rem; margin-bottom: 0.2rem; }
+.caf-steps-result { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-steps-fill { transition: width 0.25s ease; }
 .caf-step-text { margin: 0; color: var(--caf-muted); font-size: 0.92rem; line-height: 1.55; }
 .caf-step-nav { display: flex; justify-content: space-between; gap: 0.6rem; margin-top: 0.4rem; }
@@ -2662,6 +2729,27 @@ var BASE_CSS = `
 /* Never-clip guarantee: content inside a custom block that is wider than the
    phone (column grids, week views) must scroll, not disappear off-screen. */
 .caf-custom { overflow-x: auto; }
+/* mobile.nav: "bottom" \u2014 the app-shell tab bar pinned to the thumb zone.
+   Tabs share the width evenly so every section stays visible; the root
+   reserves space so the bar never covers the end of the content. */
+.caf-has-bottomnav { padding-bottom: 76px; }
+.caf-tabbar-bottom {
+  position: fixed; bottom: 0; left: 0; right: 0; z-index: 40;
+  gap: 0; margin: 0; overflow-x: visible;
+  background: var(--caf-surface); border-top: 1px solid var(--caf-border); border-bottom: none;
+  padding: 0.25rem 0.4rem calc(0.3rem + env(safe-area-inset-bottom, 0px));
+  box-shadow: 0 -1px 6px rgba(0, 0, 0, 0.07);
+}
+.caf-tabbar-bottom .caf-tab {
+  flex: 1 1 0; min-width: 0; min-height: 48px;
+  display: flex; flex-direction: column; align-items: center; justify-content: center;
+  gap: 0.15rem; padding: 0.25rem 0.2rem; margin-bottom: 0;
+  font-size: 0.66rem; border-bottom: none;
+  overflow: hidden; text-overflow: ellipsis;
+}
+.caf-tabbar-bottom .caf-tab-ico { font-size: 1.25rem; line-height: 1; }
+.caf-tabbar-bottom .caf-tab-lbl { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.caf-tabbar-bottom .caf-tab-active, .caf-tabbar-bottom .caf-tab-active:hover { border-bottom-color: transparent; }
 /* Touch devices get tappable framework controls regardless of the spec. */
 @media (pointer: coarse) {
   .caf-btn, .caf-tab, .caf-field input, .caf-field select { min-height: 44px; }