claude-artifact-framework 0.5.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Utilities for building apps inside Claude Artifacts: platform storage, chat tool-calling loops, and other primitives verified against the real runtime.",
   "type": "module",
   "main": "./dist/index.esm.js",

package/src/app.js

@@ -36,7 +36,31 @@ function checkFields(fields, where) {
         `claude-artifact-framework: field "${f.key}" in ${where} has unknown type "${f.type}". Valid types: ${FIELD_TYPES.join(", ")}.`
       );
     }
+    if (f.type === "select" && f.options !== undefined && !Array.isArray(f.options) && typeof f.options !== "function") {
+      throw new Error(
+        `claude-artifact-framework: field "${f.key}" in ${where}: \`options\` must be an array or a function of data returning one.`
+      );
+    }
+  }
+}
+
+const ACTION_KEYS = ["label", "run", "when", "kind"];
+
+function checkActions(actions, where) {
+  if (!Array.isArray(actions)) {
+    throw new Error(`claude-artifact-framework: ${where} must be an array of { label, run }.`);
   }
+  actions.forEach((a, i) => {
+    if (!a || typeof a.label !== "string" || typeof a.run !== "function") {
+      throw new Error(`claude-artifact-framework: ${where}[${i}] needs a \`label\` string and a \`run\` function.`);
+    }
+    const unknown = Object.keys(a).filter((k) => !ACTION_KEYS.includes(k));
+    if (unknown.length) {
+      throw new Error(
+        `claude-artifact-framework: ${where}[${i}] has unknown keys (${unknown.join(", ")}). Valid keys: ${ACTION_KEYS.join(", ")}.`
+      );
+    }
+  });
 }
 
 function checkBlocks(blocks) {
@@ -64,6 +88,7 @@ function checkBlocks(blocks) {
       );
     }
     checkFields(block.fields, `blocks[${i}]`);
+    if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
   });
 }
 
@@ -141,7 +166,7 @@ function validate(spec) {
         'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
       );
     }
-    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute"];
+    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
     const unknownR = Object.keys(r).filter((k) => !RECORDS_KEYS.includes(k));
     if (unknownR.length) {
       throw new Error(
@@ -156,8 +181,28 @@ function validate(spec) {
       seen.add(f.key);
     }
     if (spec.blocks) checkBlocks(spec.blocks);
+    if (r.actions) checkActions(r.actions, "records.actions");
+    if (r.items) {
+      const ITEMS_KEYS = ["label", "fields", "empty"];
+      const unknownI = Object.keys(r.items).filter((k) => !ITEMS_KEYS.includes(k));
+      if (unknownI.length) {
+        throw new Error(
+          `claude-artifact-framework: records.items has unknown keys (${unknownI.join(", ")}). Valid keys: ${ITEMS_KEYS.join(", ")}.`
+        );
+      }
+      if (!Array.isArray(r.items.fields) || r.items.fields.length === 0) {
+        throw new Error("claude-artifact-framework: records.items needs `fields: [...]` — the same field declarations as everywhere else.");
+      }
+      checkFields(r.items.fields, "records.items");
+      for (const f of r.items.fields) {
+        if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on items — the framework assigns it.');
+      }
+      if (seen.has("items") || r.fields.some((f) => f.key === "items")) {
+        throw new Error('claude-artifact-framework: a records field cannot be named "items" when `items` is declared — that key holds the child collection.');
+      }
+    }
     for (const [key, c] of Object.entries(r.compute || {})) {
-      if (seen.has(key) || key === "id") {
+      if (seen.has(key) || key === "id" || (r.items && key === "items")) {
         throw new Error(
           `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
         );
@@ -449,6 +494,22 @@ const BASE_CSS = `
 .caf-search:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-computed { border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
 .caf-records-blocks { margin-top: 1rem; }
+.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: 0.3rem 0.6rem; border-radius: 6px; }
+.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; }
+.caf-item-row .caf-field label { font-size: 0.68rem; }
+.caf-item-remove { flex: none; margin-bottom: 0.15rem; }
+.caf-empty-sm { padding: 0.6rem; font-size: 0.82rem; }
+.caf-actions-row { display: flex; flex-wrap: wrap; gap: 0.6rem; }
+.caf-code { background: var(--caf-sunken); border-radius: 6px; padding: 0.55rem 0.7rem; font-size: 0.8rem; overflow-x: auto; margin: 0.3rem 0; font-family: ui-monospace, monospace; }
+.caf-msg code { background: color-mix(in srgb, currentColor 12%, transparent); border-radius: 4px; padding: 0.05rem 0.3rem; font-size: 0.85em; font-family: ui-monospace, monospace; }
+.caf-md-h { display: block; margin-top: 0.3rem; }
+.caf-md-li { display: block; padding-left: 1rem; position: relative; }
+.caf-md-li::before { content: "•"; position: absolute; left: 0.2rem; opacity: 0.6; }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }
 .caf-block-error { border-color: var(--caf-danger); gap: 0.4rem; }
 .caf-block-error strong { font-size: 0.9rem; color: var(--caf-danger); }

package/src/blocks.js

@@ -49,7 +49,7 @@ export function validateField(field, value) {
   return null;
 }
 
-export function Field({ field, value, onChange }) {
+export function Field({ field, value, onChange, data }) {
   const error = validateField(field, value);
   const id = `caf-f-${field.key}`;
   const numeric = field.type === "number" || field.type === "money" || field.type === "percent";
@@ -79,11 +79,14 @@ export function Field({ field, value, onChange }) {
   if (field.type === "textarea") {
     control = h("textarea", { ...common, rows: field.rows || 3 });
   } else if (field.type === "select") {
+    // Options may be declared as a function of the app data, for selects
+    // whose choices come from what the user has entered elsewhere.
+    const options = typeof field.options === "function" ? field.options(data) || [] : field.options || [];
     control = h(
       "select",
       common,
       h("option", { value: "" }, field.placeholder || "Select…"),
-      (field.options || []).map((opt) => {
+      options.map((opt) => {
         const val = typeof opt === "string" ? opt : opt.value;
         const label = typeof opt === "string" ? opt : opt.label;
         return h("option", { key: val, value: val }, label);
@@ -126,6 +129,7 @@ export function FieldsBlock({ spec, ctx }) {
       h(Field, {
         key: field.key,
         field,
+        data: ctx.data,
         value: ctx.data[field.key],
         onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
       })
@@ -170,13 +174,18 @@ export function TextBlock({ spec, ctx }) {
 
 export function ListBlock({ spec, ctx }) {
   const rows = (typeof spec.list === "function" ? spec.list(ctx.data) : spec.list) || [];
+  // `title` follows the same convention as every other block: a string is the
+  // block heading. A function is the per-row title. Both are supported —
+  // making list the odd one out was an API inconsistency a blind test caught.
+  const heading = typeof spec.title === "string" ? spec.title : null;
+  const rowTitle = typeof spec.title === "function" ? spec.title : (r) => r.title ?? r.name ?? r.label ?? r.text ?? String(r);
   if (!rows.length) {
     return h("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing here yet.");
   }
-  const title = spec.title || ((r) => r.title ?? r.name ?? r.label ?? String(r));
   return h(
     "div",
     { className: "caf-block caf-list" },
+    heading ? h("h2", { className: "caf-block-title" }, heading) : null,
     rows.map((row, i) =>
       h(
         "button",
@@ -186,7 +195,7 @@ export function ListBlock({ spec, ctx }) {
           type: "button",
           onClick: spec.onSelect ? () => spec.onSelect(row, ctx) : undefined,
         },
-        h("span", { className: "caf-row-title" }, title(row)),
+        h("span", { className: "caf-row-title" }, rowTitle(row)),
         spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(row)) : null
       )
     )
@@ -365,6 +374,39 @@ export function TimerBlock({ spec, ctx }) {
   );
 }
 
+// Declarative buttons that mutate data — the one-tap interactions (counters,
+// check-ins, +1s) that previously forced an escape to custom code.
+export function ActionsBlock({ spec, ctx }) {
+  const actions = spec.actions || [];
+  const visible = actions.filter((a) => !a.when || a.when(ctx.data));
+  return h(
+    "div",
+    { className: "caf-block caf-actions" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    h(
+      "div",
+      { className: "caf-actions-row" },
+      visible.map((a) =>
+        h(
+          "button",
+          {
+            key: a.label,
+            type: "button",
+            className:
+              a.kind === "danger"
+                ? "caf-btn caf-btn-danger"
+                : a.kind === "primary"
+                ? "caf-btn caf-btn-primary"
+                : "caf-btn",
+            onClick: () => ctx.update((d) => a.run(d)),
+          },
+          a.label
+        )
+      )
+    )
+  );
+}
+
 // The escape hatch. Receives the same ctx every built-in block gets, so a
 // custom block keeps persistence, theming, navigation and the error boundary.
 export function CustomBlock({ spec, ctx }) {
@@ -382,6 +424,7 @@ export const BLOCKS = {
   list: ListBlock,
   chart: ChartBlock,
   timer: TimerBlock,
+  actions: ActionsBlock,
   custom: CustomBlock,
 };
 

package/src/chat.js

@@ -125,6 +125,29 @@ function runTools(calls, tools, ctx) {
   });
 }
 
+// Claude answers in markdown; showing raw asterisks makes every chat app
+// look broken. Minimal renderer: HTML is escaped FIRST, then a small set of
+// markdown forms is layered on, so model output can never inject markup.
+const escHtml = (t) => String(t).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+
+export function renderMarkdown(text) {
+  const codeBlocks = [];
+  let t = String(text).replace(/```[a-z]*\n?([\s\S]*?)```/g, (m, code) => {
+    codeBlocks.push(code.replace(/\n$/, ""));
+    return "\u0000" + (codeBlocks.length - 1) + "\u0000";
+  });
+  t = escHtml(t);
+  t = t.replace(/`([^`]+)`/g, "<code>$1</code>");
+  t = t.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+  t = t.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+  t = t.replace(/^#{1,3} (.+)$/gm, '<strong class="caf-md-h">$1</strong>');
+  t = t.replace(/^[-•*] (.+)$/gm, '<span class="caf-md-li">$1</span>');
+  t = t.replace(/^\d+\. (.+)$/gm, '<span class="caf-md-li caf-md-num">$1</span>');
+  t = t.replace(/\n/g, "<br>");
+  t = t.replace(/\u0000(\d+)\u0000/g, (m, i) => '<pre class="caf-code">' + escHtml(codeBlocks[Number(i)]) + "</pre>");
+  return t;
+}
+
 function Bubble({ m }) {
   if (m.role === "tools") {
     return h("div", { className: "caf-msg-tools" }, `used: ${m.tools.join(", ")}`);
@@ -138,7 +161,11 @@ function Bubble({ m }) {
       h("span", { className: "caf-hint" }, "Your message is kept — send again to retry.")
     );
   }
-  return h("div", { className: m.role === "user" ? "caf-msg caf-msg-user" : "caf-msg caf-msg-assistant" }, m.content);
+  if (m.role === "user") return h("div", { className: "caf-msg caf-msg-user" }, m.content);
+  return h("div", {
+    className: "caf-msg caf-msg-assistant",
+    dangerouslySetInnerHTML: { __html: renderMarkdown(m.content) },
+  });
 }
 
 export function ChatLayout({ spec, ctx }) {
@@ -220,9 +247,13 @@ export function ChatLayout({ spec, ctx }) {
     h(
       "div",
       { className: "caf-block caf-chat-log" },
-      c.greeting ? h("div", { className: "caf-msg caf-msg-assistant" }, c.greeting) : null,
+      c.greeting
+        ? h("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } })
+        : null,
       log.map((m, i) => h(Bubble, { key: i, m })),
-      live !== null ? h("div", { className: "caf-msg caf-msg-assistant caf-msg-live" }, live || "…") : null,
+      live !== null
+        ? h("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "…") } })
+        : null,
       busy && live === null ? h("div", { className: "caf-msg-tools" }, "thinking…") : null,
       h("div", { ref: endRef })
     ),

package/src/records.js

@@ -99,6 +99,7 @@ function ListScreen({ spec, ctx }) {
 
   function add() {
     const rec = { id: makeId(), ...recordDefaults(spec.fields) };
+    if (spec.items) rec.items = [];
     ctx.update((d) => {
       d.records = [...d.records, rec];
     });
@@ -134,15 +135,42 @@ function ListScreen({ spec, ctx }) {
         ? h("div", { className: "caf-empty" }, spec.empty || `No ${label}s yet. Add the first one.`)
         : records.map((rec) =>
             h(
-              "button",
-              {
-                key: rec.id,
-                type: "button",
-                className: "caf-row",
-                onClick: () => ctx.go("record", rec.id),
-              },
-              h("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
-              spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+              "div",
+              { key: rec.id, className: "caf-row-wrap" },
+              h(
+                "button",
+                {
+                  type: "button",
+                  className: "caf-row",
+                  onClick: () => ctx.go("record", rec.id),
+                },
+                h("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
+                spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+              ),
+              spec.actions
+                ? h(
+                    "div",
+                    { className: "caf-row-actions" },
+                    spec.actions
+                      .filter((a) => !a.when || a.when(rec))
+                      .map((a) =>
+                        h(
+                          "button",
+                          {
+                            key: a.label,
+                            type: "button",
+                            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);
+                              }),
+                          },
+                          a.label
+                        )
+                      )
+                  )
+                : null
             )
           )
   );
@@ -171,6 +199,7 @@ function DetailScreen({ spec, ctx, record }) {
       h(Field, {
         key: field.key,
         field,
+        data: ctx.data,
         value: record[field.key],
         onChange: (v) =>
           ctx.update((d) => {
@@ -179,6 +208,7 @@ function DetailScreen({ spec, ctx, record }) {
           }),
       })
     ),
+    spec.items ? h(ItemsEditor, { spec, ctx, record }) : null,
     spec.compute
       ? h(
           "div",
@@ -197,6 +227,76 @@ function DetailScreen({ spec, ctx, record }) {
   );
 }
 
+// The child collection edits INLINE on the parent's detail screen — one
+// navigation level, no child screens. That bounds the feature honestly: items
+// are for small rows (2-4 fields), not for records that deserve their own
+// detail view.
+function ItemsEditor({ spec, ctx, record }) {
+  const ispec = spec.items;
+  const label = ispec.label || "item";
+
+  function mutate(fn) {
+    ctx.update((d) => {
+      const rec = d.records.find((r) => r.id === record.id);
+      if (!rec) return;
+      if (!Array.isArray(rec.items)) rec.items = [];
+      fn(rec);
+    });
+  }
+
+  const items = Array.isArray(record.items) ? record.items : [];
+
+  return h(
+    "div",
+    { className: "caf-items" },
+    h(
+      "div",
+      { className: "caf-toolbar" },
+      h("span", { className: "caf-count" }, `${items.length} ${label}${items.length === 1 ? "" : "s"}`),
+      h(
+        "button",
+        {
+          type: "button",
+          className: "caf-btn caf-btn-sm",
+          onClick: () => mutate((rec) => rec.items.push({ id: makeId(), ...recordDefaults(ispec.fields) })),
+        },
+        `Add ${label}`
+      )
+    ),
+    items.length === 0
+      ? h("div", { className: "caf-empty caf-empty-sm" }, ispec.empty || `No ${label}s yet.`)
+      : items.map((item) =>
+          h(
+            "div",
+            { key: item.id, className: "caf-item-row" },
+            ispec.fields.map((field) =>
+              h(Field, {
+                key: field.key,
+                field,
+                data: ctx.data,
+                value: item[field.key],
+                onChange: (v) =>
+                  mutate((rec) => {
+                    const it = rec.items.find((x) => x.id === item.id);
+                    if (it) it[field.key] = v;
+                  }),
+              })
+            ),
+            h(
+              "button",
+              {
+                type: "button",
+                className: "caf-btn caf-btn-danger caf-btn-sm caf-item-remove",
+                "aria-label": `Remove ${label}`,
+                onClick: () => mutate((rec) => { rec.items = rec.items.filter((x) => x.id !== item.id); }),
+              },
+              "✕"
+            )
+          )
+        )
+  );
+}
+
 export function RecordsLayout({ spec, ctx }) {
   const rspec = spec.records;
 

package/src/steps.js

@@ -78,6 +78,7 @@ export function StepsLayout({ spec, ctx }) {
             h(Field, {
               key: field.key,
               field,
+              data: ctx.data,
               value: ctx.data[field.key],
               onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
             })