claude-artifact-framework 0.17.0 → 0.19.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
@@ -896,9 +909,10 @@ keys must be unique across steps.
 
 **Formats** (`format:` on output/chart/compute items): `money`, `percent`,
 `number`, `date`. `percent` expects 0–100 (pass `ratio * 100`, not the raw
-ratio). `big: true` renders an item at hero size — reserve it for the ONE
-number that is the screen's main result (a total, a final score), not for
-every stat; more than one hero per screen means no hero at all.
+ratio). `big: true` renders an item at hero size AND promotes its block to
+the screen's one feature surface (accent-tinted card) — reserve it for the
+ONE number that is the screen's main result (a total, a final score), not
+for every stat; more than one hero per screen means no hero at all.
 
 **Quick-add pattern** — a lightweight alternative to `records` when you just
 need "type something, press a button, it lands in a list":
@@ -993,8 +1007,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

@@ -761,9 +761,10 @@ function OutputBlock({ spec, ctx }) {
   if (!items.length) {
     return createElement("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
   }
+  const hero = items.some((it) => it && it.big);
   return createElement(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
     createElement(
       "div",
@@ -780,10 +781,9 @@ function OutputBlock({ spec, ctx }) {
     )
   );
 }
-function BannerBlock({ spec, ctx }) {
+function BannerBlock({ spec }) {
   const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
-  const [c1, c2] = ctx.colors(2);
-  const background = b.image ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover` : `linear-gradient(135deg, ${c1}, ${c2})`;
+  const background = b.image ? `linear-gradient(rgba(0,0,0,0.35), rgba(0,0,0,0.35)), url(${JSON.stringify(b.image)}) center / cover` : `linear-gradient(135deg, color-mix(in srgb, var(--caf-accent) 82%, #000), var(--caf-accent) 55%, color-mix(in srgb, var(--caf-accent) 72%, #fff))`;
   return createElement(
     "div",
     { className: "caf-banner", style: { background } },
@@ -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;
@@ -1087,9 +1100,10 @@ function Summary({ spec, records }) {
   if (!spec.summary) return null;
   const items = spec.summary(records) || [];
   if (!items.length) return null;
+  const hero = items.some((it) => it && it.big);
   return createElement(
     "div",
-    { className: "caf-block caf-output" },
+    { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
     createElement(
       "div",
       { className: "caf-output-grid" },
@@ -1174,7 +1188,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 +1197,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 +1368,32 @@ 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
+      // Same rule as OutputBlock: the hero (big) result gets the feature card.
+      { className: items.some((it) => it && it.big) ? "caf-block caf-output caf-block-feature" : "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 +1724,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 +1739,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 +2250,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 +2436,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.");
@@ -2414,7 +2448,9 @@ function createApp(spec = {}) {
     const logoEl = !spec.brand ? null : logo && logo.trim().startsWith("<svg") ? createElement("span", { className: "caf-logo caf-logo-svg", dangerouslySetInnerHTML: { __html: logo } }) : logo && /^https?:\/\//.test(logo) ? createElement("img", { className: "caf-logo", src: logo, alt: "" }) : logo ? createElement("span", { className: "caf-logo caf-logo-emoji", "aria-hidden": true }, logo) : createElement(
       "span",
       { className: "caf-logo caf-logo-mono", "aria-hidden": true },
-      (spec.title || "?").split(/\s+/).map((w) => w[0]).filter(Boolean).slice(0, 2).join("").toUpperCase()
+      // First letter/digit of each word — punctuation "words" like the
+      // "-" in "Caja - Camión" must not become half the monogram.
+      (spec.title || "?").split(/\s+/).map((w) => (w.match(/[\p{L}\p{N}]/u) || [])[0]).filter(Boolean).slice(0, 2).join("").toUpperCase() || "?"
     );
     return createElement(
       "div",
@@ -2438,7 +2474,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
     );
   };
@@ -2449,7 +2491,9 @@ var BASE_CSS = `
   --caf-control-radius: 7px; /* one radius for every control: buttons, inputs, rows */
   --caf-btn-pad-y: 0.45rem;
   --caf-btn-pad-x: 0.8rem;
-  --caf-num-primary: 2.1rem; /* the one size for a block's dominant number */
+  --caf-num-primary: 2.6rem; /* the one size for a block's dominant number \u2014 the largest thing on screen, bigger than the H1 */
+  --caf-accent-tint: color-mix(in srgb, var(--caf-accent) 7%, var(--caf-surface)); /* soft accent surface for the feature card */
+  --caf-block-gap: 1.75rem; /* ONE value for air between blocks, every layout (audited: workspace used a smaller gap for the same visual role) */
   box-sizing: border-box;
   min-height: 100vh;
   padding: 2rem 1.25rem 4rem;
@@ -2465,7 +2509,9 @@ var BASE_CSS = `
 .caf-header h1 { margin: 0; font-size: 1.5rem; font-weight: 650; letter-spacing: -0.01em; text-wrap: balance; }
 .caf-header p { margin: 0.4rem 0 0; color: var(--caf-muted); font-size: 0.95rem; line-height: 1.5; }
 /* Between-card air must beat within-card padding (1.1rem), or groups dissolve. */
-.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: 1.75rem 1rem; }
+/* align-items: start \u2014 a short card must not stretch to its tall neighbor's
+   height; the stretched version reads as dead air (audited). */
+.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: var(--caf-block-gap) 1rem; align-items: start; }
 .caf-slot { grid-column: span 2; min-width: 0; }
 @media (min-width: 720px) { .caf-slot { grid-column: span 1; } .caf-slot-wide { grid-column: span 2; } }
 .caf-block {
@@ -2559,8 +2605,11 @@ var BASE_CSS = `
 .caf-timer-done { color: var(--caf-accent); }
 .caf-timer-fill { transition: width 0.9s linear; }
 .caf-timer-controls { display: flex; gap: 0.6rem; }
-.caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+/* Disabled goes NEUTRAL, not pale-accent: a washed-out primary reads as
+   broken (audited on the chat Send with an empty input). */
+.caf-btn:disabled { cursor: not-allowed; background: var(--caf-sunken); color: var(--caf-muted); border-color: var(--caf-border); opacity: 1; }
 .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; }
@@ -2590,7 +2639,9 @@ var BASE_CSS = `
 .caf-row-wrap { display: flex; align-items: center; gap: 0.4rem; }
 .caf-row-wrap .caf-row { flex: 1; min-width: 0; }
 .caf-row-actions { display: flex; gap: 0.35rem; flex: none; padding-right: 0.3rem; }
-.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); }
+/* min-width keeps row actions' left edges aligned across rows even when
+   labels differ ("Hecho" vs "Desmarcar" \u2014 audited misalignment). */
+.caf-btn-sm { font-size: 0.78rem; padding: calc(var(--caf-btn-pad-y) * 0.67) calc(var(--caf-btn-pad-x) * 0.75); min-width: 76px; text-align: center; }
 .caf-items { display: flex; flex-direction: column; gap: 0.5rem; border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-item-row { display: flex; align-items: flex-end; gap: 0.5rem; }
 .caf-item-row .caf-field { flex: 1; min-width: 0; }
@@ -2604,8 +2655,8 @@ var BASE_CSS = `
 .caf-md-li { display: block; padding-left: 1rem; position: relative; }
 .caf-md-li::before { content: "\u2022"; position: absolute; left: 0.2rem; opacity: 0.6; }
 .caf-workspace { max-width: 1200px; margin: 0 auto; display: flex; gap: 1rem; align-items: flex-start; }
-.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: 1rem; }
-.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: 1rem; position: sticky; top: 1rem; }
+.caf-ws-main { flex: 1; min-width: 0; display: flex; flex-direction: column; gap: var(--caf-block-gap); }
+.caf-ws-side { width: 340px; flex: none; display: flex; flex-direction: column; gap: var(--caf-block-gap); position: sticky; top: 1rem; }
 .caf-ws-slot { min-width: 0; }
 .caf-chat-panel { display: flex; flex-direction: column; min-height: 0; }
 .caf-ws-side .caf-chat-log { max-height: calc(100vh - 220px); }
@@ -2690,6 +2741,11 @@ 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; }
+/* The one differentiated surface per screen: accent top rule + tinted bg on
+   the block holding the hero number. Everything-is-the-same-card was the
+   audited root cause of the "generic template" look. (Late in the sheet on
+   purpose \u2014 it must win over .caf-block's border/background.) */
+.caf-block-feature { border-top: 3px solid var(--caf-accent); background: var(--caf-accent-tint); }
 /* 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. */