claude-artifact-framework 0.19.0 → 0.19.2

package/README.md

@@ -908,8 +908,10 @@ keys must be unique across steps.
 `{ description, input, run(input, ctx) }`.
 
 **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 AND promotes its block to
+`number`, `date`, `text` (explicit no-op). Anything else throws, contained
+to the block. `percent` expects 0–100 (pass `ratio * 100`, not the raw
+ratio); a computed `NaN`/`Infinity` renders as "—", never as "NaN".
+`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.
@@ -988,6 +990,40 @@ Conflict handling is last-write-wins: if two viewers change the same key
 within one poll window, whichever write reaches storage last overwrites the
 other. There is no merge/CRDT logic.
 
+## Design principles — composing a screen that reads
+
+The framework owns the CSS, but whether a screen has visual hierarchy is
+decided by choices only the SPEC can make. Every beautiful app follows
+these; every generic-looking one breaks at least two:
+
+1. **One dominant element per screen.** Exactly one `big: true` stat — the
+   screen's answer (the total, the score, the net). It automatically
+   becomes the highlighted feature card. Zero heroes reads flat; two
+   heroes read as none.
+2. **Order blocks by importance, not by data model.** First what the user
+   DOES most (the quick-add, the main fields), then the hero result, then
+   breakdowns and charts, then history. Configuration, branding text, and
+   help go LAST — or inside `collapsible: "collapsed"` — never first.
+3. **Icons: all siblings or none.** If one tab/section gets an `icon`,
+   every tab/section in that same set gets one, same style (all emoji). A
+   half-iconed set reads as an accident. Don't use emoji as bullet points
+   inside stat labels or titles that already live in an iconed set.
+4. **Pick a mid-tone, saturated seed that names the domain** — warm
+   orange/red for food, teal/blue for finance, green for health. Grays and
+   near-blacks kill the entire accent system; neons burn it.
+5. **Never duplicate what the framework already renders.** No text block
+   repeating the app's own title (the header shows it), no hand-built
+   totals when `summary`/`output` computes them, no "empty list" messages.
+6. **Group; don't multiply cards.** Related inputs belong in ONE `fields`
+   block with one title. Secondary content goes into `tabs` or a
+   collapsible. A first screen with more than ~5 cards has no hierarchy
+   left — and a block whose only content is one lonely button probably
+   belongs next to the fields it acts on.
+7. **Say state with `when`, not with more blocks.** Hide what doesn't
+   apply right now instead of stacking every possibility on screen.
+8. **Charts are support, not wallpaper.** At most two per screen; `wide:
+   true` for time series; donuts only up to ~5 slices.
+
 ## Hard rules — the short list
 
 The rules that decide whether a generated app works, all in one place

package/dist/index.esm.js

@@ -625,6 +625,7 @@ function ChatLayout({ spec, ctx }) {
 var FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select", "file"];
 function formatValue(value, format) {
   if (value === null || value === void 0 || value === "") return "\u2014";
+  if (typeof value === "number" && !Number.isFinite(value)) return "\u2014";
   const n = Number(value);
   switch (format) {
     case "money":
@@ -635,8 +636,15 @@ function formatValue(value, format) {
       return Number.isFinite(n) ? n.toLocaleString(void 0, { maximumFractionDigits: 2 }) : String(value);
     case "date":
       return value instanceof Date ? value.toLocaleDateString() : String(value);
-    default:
+    case "text":
+    // observed natural usage (round 21) — an explicit no-op
+    case void 0:
+    case null:
       return String(value);
+    default:
+      throw new Error(
+        `claude-artifact-framework: unknown format "${format}". Valid formats: money, percent, number, date, text.`
+      );
   }
 }
 function validateField(field, value) {
@@ -756,16 +764,12 @@ function FieldsBlock({ spec, ctx }) {
     )
   );
 }
-function OutputBlock({ spec, ctx }) {
-  const items = typeof spec.output === "function" ? spec.output(ctx.data) : spec.output || [];
-  if (!items.length) {
-    return createElement("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
-  }
+function StatGrid({ items, title }) {
   const hero = items.some((it) => it && it.big);
   return createElement(
     "div",
     { className: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
-    spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
+    title ? createElement("h2", { className: "caf-block-title" }, title) : null,
     createElement(
       "div",
       { className: "caf-output-grid" },
@@ -781,6 +785,13 @@ function OutputBlock({ spec, ctx }) {
     )
   );
 }
+function OutputBlock({ spec, ctx }) {
+  const items = typeof spec.output === "function" ? spec.output(ctx.data) : spec.output || [];
+  if (!items.length) {
+    return createElement("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
+  }
+  return createElement(StatGrid, { items, title: spec.title });
+}
 function BannerBlock({ spec }) {
   const b = typeof spec.banner === "string" ? { title: spec.banner } : spec.banner || {};
   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))`;
@@ -1100,23 +1111,7 @@ 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: hero ? "caf-block caf-output caf-block-feature" : "caf-block caf-output" },
-    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))
-        )
-      )
-    )
-  );
+  return createElement(StatGrid, { items });
 }
 function ListScreen({ spec, ctx }) {
   const label = spec.label || "item";
@@ -1372,25 +1367,7 @@ function ResultScreen({ step, ctx }) {
   return createElement(
     "div",
     { className: "caf-steps-result" },
-    createElement(
-      "div",
-      // 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
-          )
-        )
-      )
-    ),
+    createElement(StatGrid, { items, title: step.title }),
     // 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 })),