claude-artifact-framework 0.17.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
@@ -993,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" },
@@ -1701,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") {
@@ -1716,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)) {
@@ -2221,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 }) {
@@ -2404,6 +2434,8 @@ function createApp(spec = {}) {
       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.");
@@ -2438,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
     );
   };
@@ -2561,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; }