claude-artifact-framework 0.5.2 → 0.6.0

package/README.md

@@ -12,7 +12,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.2/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.6.0/dist/index.global.js"></script>
 <script>
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
@@ -27,11 +27,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.2/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.6.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.5.2`) for reproducible artifacts, or drop the version
+Pin a version (`@0.6.0`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -254,6 +254,67 @@ ArtifactKit.createApp({
   that haven't been persisted yet. View state (which screen is open) stays
   personal per viewer.
 
+### `items` — a child collection per record
+
+For "a thing with parts": invoices with line items, recipes with
+ingredients, projects with tasks. One level deep by design; children edit
+inline on the parent's detail screen (they're for small rows, not records
+that deserve their own screen). The collection lives at `r.items` and is
+available to `compute` / `title` / `subtitle` / `summary`:
+
+```js
+records: {
+  label: "factura",
+  fields: [{ key: "cliente", type: "text", required: true }],
+  items: {
+    label: "ítem",
+    fields: [
+      { key: "concepto", type: "text" },
+      { key: "cantidad", type: "number", value: 1, min: 0 },
+      { key: "precio",   type: "money", value: 0, min: 0 },
+    ],
+  },
+  compute: {
+    total: { label: "Total c/IVA", format: "money",
+             value: (r) => (r.items || []).reduce((s, i) => s + i.cantidad * i.precio, 0) * 1.21 },
+  },
+}
+```
+
+`items` keys: `label`, `fields`, `empty`. Each child gets a framework
+`id`; a parent field can't be named `items`.
+
+### `actions` — one-tap buttons that mutate data
+
+On records rows (mark done, +1, vote — without opening the record):
+
+```js
+records: {
+  fields: [{ key: "nombre", type: "text" }, { key: "veces", type: "number", value: 0 }],
+  actions: [
+    { label: "Hecho hoy", run: (r) => { r.veces = (r.veces || 0) + 1; } },
+    { label: "Reset", kind: "danger", when: (r) => r.veces > 0, run: (r) => { r.veces = 0; } },
+  ],
+}
+```
+
+And as a block in `panel` (quick counters):
+
+```js
+blocks: [
+  { actions: [{ label: "+1 vaso de agua", kind: "primary", run: (d) => { d.agua = (d.agua || 0) + 1; } }] },
+  { output: (d) => [{ label: "Agua hoy", value: d.agua || 0, big: true }] },
+]
+```
+
+Action keys: `label`, `run`, optional `when` (hides the button when false)
+and `kind` (`"primary"` / `"danger"`). Row actions receive the record;
+block actions receive data. Changes persist like any other update.
+
+Chat bubbles render the assistant's **markdown** (bold, code, lists,
+headings) automatically — HTML is escaped first, so model output can't
+inject markup.
+
 ## API reference
 
 Everything an app can declare, in one place.
@@ -266,7 +327,7 @@ list), `steps` (wizard), `chat` (conversation with Claude). Each requires its
 matching key (`blocks` / `records` / `steps` / `chat`).
 
 **Block types** (entries of `blocks`): `fields`, `output`, `text`, `list`,
-`chart`, `timer`, `custom`. One type per entry, plus optional `title`, `empty`,
+`chart`, `timer`, `actions`, `custom`. One type per entry, plus optional `title`, `empty`,
 `wide`. In the `records` layout, `blocks` render below the list (never on the
 detail screen); their functions receive the same `data` object as everywhere
 else — the collection lives at `d.records`.
@@ -278,8 +339,8 @@ else — the collection lives at `d.records`.
 An unknown `type` throws naming the valid ones.
 
 **`records` keys**: `label`, `fields`, `title(r)`, `subtitle(r)`, `sort(a,b)`,
-`summary(all)`, `empty`, `search`, `compute`. `id` is framework-assigned and
-reserved.
+`summary(all)`, `empty`, `search`, `compute`, `items`, `actions`. `id` is
+framework-assigned and reserved on records and items alike.
 
 **`steps` keys** (per step): `title`, `text`, `fields`, `result(d)`. Field
 keys must be unique across steps.

package/dist/index.esm.js

@@ -694,6 +694,31 @@ function TimerBlock({ spec, ctx }) {
     )
   );
 }
+function ActionsBlock({ spec, ctx }) {
+  const actions = spec.actions || [];
+  const visible = actions.filter((a) => !a.when || a.when(ctx.data));
+  return createElement(
+    "div",
+    { className: "caf-block caf-actions" },
+    spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
+    createElement(
+      "div",
+      { className: "caf-actions-row" },
+      visible.map(
+        (a) => createElement(
+          "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
+        )
+      )
+    )
+  );
+}
 function CustomBlock({ spec, ctx }) {
   const rendered = spec.custom(ctx);
   if (typeof rendered === "string") {
@@ -708,6 +733,7 @@ var BLOCKS = {
   list: ListBlock,
   chart: ChartBlock,
   timer: TimerBlock,
+  actions: ActionsBlock,
   custom: CustomBlock
 };
 var BLOCK_NAMES = Object.keys(BLOCKS);
@@ -779,6 +805,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];
     });
@@ -807,15 +834,37 @@ function ListScreen({ spec, ctx }) {
     spec.search && q && records.length === 0 && total > 0 ? createElement("div", { className: "caf-empty" }, `Nothing matches "${query}".`) : null,
     records.length === 0 ? createElement("div", { className: "caf-empty" }, spec.empty || `No ${label}s yet. Add the first one.`) : records.map(
       (rec) => createElement(
-        "button",
-        {
-          key: rec.id,
-          type: "button",
-          className: "caf-row",
-          onClick: () => ctx.go("record", rec.id)
-        },
-        createElement("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
-        spec.subtitle ? createElement("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+        "div",
+        { key: rec.id, className: "caf-row-wrap" },
+        createElement(
+          "button",
+          {
+            type: "button",
+            className: "caf-row",
+            onClick: () => ctx.go("record", rec.id)
+          },
+          createElement("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
+          spec.subtitle ? createElement("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+        ),
+        spec.actions ? createElement(
+          "div",
+          { className: "caf-row-actions" },
+          spec.actions.filter((a) => !a.when || a.when(rec)).map(
+            (a) => createElement(
+              "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
       )
     )
   );
@@ -848,6 +897,7 @@ function DetailScreen({ spec, ctx, record }) {
         })
       })
     ),
+    spec.items ? createElement(ItemsEditor, { spec, ctx, record }) : null,
     spec.compute ? createElement(
       "div",
       { className: "caf-output-grid caf-computed" },
@@ -863,6 +913,66 @@ function DetailScreen({ spec, ctx, record }) {
     ) : null
   );
 }
+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 createElement(
+    "div",
+    { className: "caf-items" },
+    createElement(
+      "div",
+      { className: "caf-toolbar" },
+      createElement("span", { className: "caf-count" }, `${items.length} ${label}${items.length === 1 ? "" : "s"}`),
+      createElement(
+        "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 ? createElement("div", { className: "caf-empty caf-empty-sm" }, ispec.empty || `No ${label}s yet.`) : items.map(
+      (item) => createElement(
+        "div",
+        { key: item.id, className: "caf-item-row" },
+        ispec.fields.map(
+          (field) => createElement(Field, {
+            key: field.key,
+            field,
+            value: item[field.key],
+            onChange: (v) => mutate((rec) => {
+              const it = rec.items.find((x) => x.id === item.id);
+              if (it) it[field.key] = v;
+            })
+          })
+        ),
+        createElement(
+          "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);
+            })
+          },
+          "\u2715"
+        )
+      )
+    )
+  );
+}
 function RecordsLayout({ spec, ctx }) {
   const rspec = spec.records;
   if (ctx.view.screen === "record") {
@@ -1049,6 +1159,24 @@ function runTools(calls, tools, ctx) {
     }
   });
 }
+var escHtml = (t) => String(t).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+function renderMarkdown(text) {
+  const codeBlocks = [];
+  let t = String(text).replace(/```[a-z]*\n?([\s\S]*?)```/g, (m, code) => {
+    codeBlocks.push(code.replace(/\n$/, ""));
+    return "\0" + (codeBlocks.length - 1) + "\0";
+  });
+  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 createElement("div", { className: "caf-msg-tools" }, `used: ${m.tools.join(", ")}`);
@@ -1062,7 +1190,11 @@ function Bubble({ m }) {
       createElement("span", { className: "caf-hint" }, "Your message is kept \u2014 send again to retry.")
     );
   }
-  return createElement("div", { className: m.role === "user" ? "caf-msg caf-msg-user" : "caf-msg caf-msg-assistant" }, m.content);
+  if (m.role === "user") return createElement("div", { className: "caf-msg caf-msg-user" }, m.content);
+  return createElement("div", {
+    className: "caf-msg caf-msg-assistant",
+    dangerouslySetInnerHTML: { __html: renderMarkdown(m.content) }
+  });
 }
 function ChatLayout({ spec, ctx }) {
   const c = spec.chat;
@@ -1135,9 +1267,9 @@ Continue with this information. If you have everything you need, answer in natur
     createElement(
       "div",
       { className: "caf-block caf-chat-log" },
-      c.greeting ? createElement("div", { className: "caf-msg caf-msg-assistant" }, c.greeting) : null,
+      c.greeting ? createElement("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } }) : null,
       log.map((m, i) => createElement(Bubble, { key: i, m })),
-      live !== null ? createElement("div", { className: "caf-msg caf-msg-assistant caf-msg-live" }, live || "\u2026") : null,
+      live !== null ? createElement("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "\u2026") } }) : null,
       busy && live === null ? createElement("div", { className: "caf-msg-tools" }, "thinking\u2026") : null,
       createElement("div", { ref: endRef })
     ),
@@ -1186,6 +1318,23 @@ function checkFields(fields, where) {
     }
   }
 }
+var 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) {
   if (!Array.isArray(blocks)) {
     throw new Error("claude-artifact-framework: `blocks` must be an array.");
@@ -1209,6 +1358,7 @@ function checkBlocks(blocks) {
       );
     }
     checkFields(block.fields, `blocks[${i}]`);
+    if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
   });
 }
 function validate(spec) {
@@ -1285,7 +1435,7 @@ function validate(spec) {
         'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` \u2014 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(
@@ -1300,8 +1450,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: [...]` \u2014 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 \u2014 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 \u2014 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 \u2014 computed values are derived, never stored.`
         );
@@ -1561,6 +1731,22 @@ var 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: "\u2022"; 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); }