claude-artifact-framework 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.11.0",
+  "version": "0.12.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

@@ -13,7 +13,7 @@ import { createElement as h, useState, useEffect, hasReact, getReact } from "rea
 import { createAppState } from "./appState.js";
 import { themeCss, seriesColors } from "./theme.js";
 import { BLOCKS, BLOCK_NAMES, FIELD_TYPES } from "./blocks.js";
-import { RecordsLayout } from "./records.js";
+import { RecordsLayout, RecordsBlock } from "./records.js";
 import { StepsLayout } from "./steps.js";
 import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
@@ -26,6 +26,8 @@ const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "col
 const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents"];
 
 const DOCUMENTS_KEYS = ["label", "title", "blocks", "empty"];
+const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
+const ITEMS_KEYS = ["label", "fields", "empty"];
 
 // An unknown field type used to fall through silently to a text input — the
 // exact quiet degradation the framework exists to prevent (a blind-tested
@@ -95,12 +97,12 @@ function checkBlocks(blocks) {
       throw new Error(`claude-artifact-framework: blocks[${i}] must be an object like { fields: [...] }.`);
     }
     const keys = Object.keys(block).filter((k) => !RESERVED.includes(k));
-    const known = keys.filter((k) => BLOCK_NAMES.includes(k) || k === "tabs");
+    const known = keys.filter((k) => BLOCK_NAMES.includes(k) || k === "tabs" || k === "records");
     if (known.length === 0) {
       throw new Error(
         `claude-artifact-framework: blocks[${i}] has no recognised block type (found: ${
           keys.join(", ") || "nothing"
-        }). Valid block types: ${BLOCK_NAMES.join(", ")}.`
+        }). Valid block types: ${[...BLOCK_NAMES, "tabs", "records"].join(", ")}.`
       );
     }
     if (known.length > 1) {
@@ -113,6 +115,7 @@ function checkBlocks(blocks) {
     checkFields(block.fields, `blocks[${i}]`);
     if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
     if (known[0] === "chat") checkChatConfig(block.chat, `blocks[${i}].chat`);
+    if (known[0] === "records") checkRecordsSpec(block.records, `blocks[${i}].records`, true);
     if (known[0] === "tabs") {
       const tabs = block.tabs;
       if (!Array.isArray(tabs) || tabs.length === 0) {
@@ -204,12 +207,14 @@ function validate(spec) {
       }
       checkBlocks(spec.sidebar);
     }
-    const chats = flattenBlocks([...spec.main, ...(spec.sidebar || [])]).filter((b) => b && b.chat);
+    const wsFlat = flattenBlocks([...spec.main, ...(spec.sidebar || [])]);
+    const chats = wsFlat.filter((b) => b && b.chat);
     if (chats.length > 1) {
       throw new Error(
         "claude-artifact-framework: only one chat block per app — the conversation persists under data.chat and there is exactly one."
       );
     }
+    checkRecordsBlockKeys(wsFlat);
     return layout;
   }
   if (layout === "documents") {
@@ -232,77 +237,110 @@ function validate(spec) {
     // Inside documents both chat and file are PER DOCUMENT: the scoped ctx
     // gives each document its own data.chat and its own ctx.files. One chat
     // block in the declaration = one conversation per document.
-    const chats = flattenBlocks(d.blocks).filter((b) => b && b.chat);
+    const docFlat = flattenBlocks(d.blocks);
+    const chats = docFlat.filter((b) => b && b.chat);
     if (chats.length > 1) {
       throw new Error(
         "claude-artifact-framework: only one chat block per document — each document's conversation persists under its own data.chat and there is exactly one."
       );
     }
+    checkRecordsBlockKeys(docFlat);
     return layout;
   }
   if (layout === "records") {
-    const r = spec.records;
-    if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
+    checkRecordsSpec(spec.records, "records", false);
+    if (spec.blocks) {
+      checkBlocks(spec.blocks);
+      if (flattenBlocks(spec.blocks).some((b) => b && b.records)) {
+        throw new Error(
+          'claude-artifact-framework: a records BLOCK below a records LAYOUT is ambiguous — the layout already owns the collection. Use panel/workspace/documents to embed records blocks.'
+        );
+      }
+    }
+    return layout;
+  }
+  checkBlocks(spec.blocks || []);
+  checkRecordsBlockKeys(flattenBlocks(spec.blocks || []));
+  return layout;
+}
+
+// The records declaration is validated identically as a layout and as a
+// block; only the block form takes `key` (where the collection lives in the
+// enclosing pool — required for two collections to coexist).
+function checkRecordsSpec(r, where, allowKey) {
+  if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
+    throw new Error(
+      `claude-artifact-framework: ${where} needs \`records: { fields: [...] }\` — the same field declarations the fields block uses.`
+    );
+  }
+  const valid = allowKey ? [...RECORDS_KEYS, "key"] : RECORDS_KEYS;
+  const unknownR = Object.keys(r).filter((k) => !valid.includes(k));
+  if (unknownR.length) {
+    throw new Error(
+      `claude-artifact-framework: ${where} has unknown keys (${unknownR.join(", ")}). Valid keys: ${valid.join(", ")}.`
+    );
+  }
+  if (allowKey && r.key !== undefined && (typeof r.key !== "string" || !r.key)) {
+    throw new Error(`claude-artifact-framework: ${where}.key must be a non-empty string naming the collection in data.`);
+  }
+  checkFields(r.fields, where);
+  if (r.fields.some((f) => f.type === "file") || (r.items && r.items.fields.some((f) => f.type === "file"))) {
+    throw new Error(
+      'claude-artifact-framework: `file` fields live in the flat data pool (panel blocks or steps) — they are not supported inside records or items.'
+    );
+  }
+  const seen = new Set();
+  for (const f of r.fields) {
+    if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records — the framework assigns it.');
+    if (seen.has(f.key)) throw new Error(`claude-artifact-framework: duplicate ${where} field key "${f.key}".`);
+    seen.add(f.key);
+  }
+  if (r.actions) checkActions(r.actions, `${where}.actions`);
+  if (r.items) {
+    const unknownI = Object.keys(r.items).filter((k) => !ITEMS_KEYS.includes(k));
+    if (unknownI.length) {
       throw new Error(
-        'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
+        `claude-artifact-framework: ${where}.items has unknown keys (${unknownI.join(", ")}). Valid keys: ${ITEMS_KEYS.join(", ")}.`
       );
     }
-    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) {
+    if (!Array.isArray(r.items.fields) || r.items.fields.length === 0) {
+      throw new Error(`claude-artifact-framework: ${where}.items needs \`fields: [...]\` — the same field declarations as everywhere else.`);
+    }
+    checkFields(r.items.fields, `${where}.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 ${where} 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" || (r.items && key === "items")) {
       throw new Error(
-        `claude-artifact-framework: records has unknown keys (${unknownR.join(", ")}). Valid keys: ${RECORDS_KEYS.join(", ")}.`
+        `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
       );
     }
-    checkFields(r.fields, "records");
-    if (r.fields.some((f) => f.type === "file") || (r.items && r.items.fields.some((f) => f.type === "file"))) {
+    if (typeof c !== "function" && typeof (c && c.value) !== "function") {
       throw new Error(
-        'claude-artifact-framework: `file` fields live in the flat data pool (panel blocks or steps) — they are not supported inside records or items.'
+        `claude-artifact-framework: compute "${key}" must be a function of the record, or { label, format, value: (r) => ... }.`
       );
     }
-    const seen = new Set();
-    for (const f of r.fields) {
-      if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records — the framework assigns it.');
-      if (seen.has(f.key)) throw new Error(`claude-artifact-framework: duplicate records field key "${f.key}".`);
-      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" || (r.items && key === "items")) {
-        throw new Error(
-          `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
-        );
-      }
-      if (typeof c !== "function" && typeof (c && c.value) !== "function") {
-        throw new Error(
-          `claude-artifact-framework: compute "${key}" must be a function of the record, or { label, format, value: (r) => ... }.`
-        );
-      }
+  }
+}
+
+// Two records blocks writing the same collection would silently fight.
+function checkRecordsBlockKeys(flatBlocks) {
+  const seen = new Set();
+  for (const b of flatBlocks) {
+    if (!b || !b.records) continue;
+    const k = b.records.key || "records";
+    if (seen.has(k)) {
+      throw new Error(
+        `claude-artifact-framework: two records blocks share the collection key "${k}" — give each a distinct \`key\`.`
+      );
     }
-    return layout;
+    seen.add(k);
   }
-  checkBlocks(spec.blocks || []);
-  return layout;
 }
 
 // Fields declare their own initial value, so the data shape is derived from
@@ -339,6 +377,12 @@ function defaultsFrom(spec) {
       }
     }
   }
+  for (const b of allBlocks) {
+    if (b && b.records) {
+      const k = b.records.key || "records";
+      if (!Array.isArray(data[k])) data[k] = [];
+    }
+  }
   return data;
 }
 
@@ -408,8 +452,8 @@ function TabsBlock({ spec, ctx }) {
   );
 }
 
-const ALL_BLOCKS = { ...BLOCKS, tabs: TabsBlock };
-const ALL_NAMES = [...BLOCK_NAMES, "tabs"];
+const ALL_BLOCKS = { ...BLOCKS, tabs: TabsBlock, records: RecordsBlock };
+const ALL_NAMES = [...BLOCK_NAMES, "tabs", "records"];
 
 function Block({ block, ctx }) {
   // `when` hides a block entirely — the primitive under conditional UIs.
@@ -516,6 +560,10 @@ function docDefaults(dspec) {
         data[field.key] = field.value !== undefined ? field.value : field.type === "check" ? false : "";
       }
     }
+    if (block.records) {
+      const k = block.records.key || "records";
+      if (!Array.isArray(data[k])) data[k] = [];
+    }
   }
   return data;
 }
@@ -965,6 +1013,7 @@ const BASE_CSS = `
 .caf-doc-close:hover { color: var(--caf-danger); }
 .caf-doc-add { font-size: 1rem; font-weight: 650; }
 .caf-empty .caf-btn { margin-top: 0.6rem; }
+.caf-records-block { display: flex; flex-direction: column; gap: 1rem; min-width: 0; }
 .caf-chevron-closed { transform: rotate(-90deg); }
 .caf-block-fill { border: none; background: transparent; padding: 0; overflow: auto; min-height: 320px; }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }

package/src/records.js

@@ -18,7 +18,7 @@
 // in data — restoring it on reload is correct, and deleting the open record
 // simply falls back to the list.
 
-import { createElement as h, useState } from "react";
+import { createElement as h, useState, useEffect } from "react";
 import { Field, formatValue } from "./blocks.js";
 
 // Computed fields are derived at render time and never stored, so they can't
@@ -87,6 +87,17 @@ function Summary({ spec, records }) {
 function ListScreen({ spec, ctx }) {
   const label = spec.label || "item";
   const [query, setQuery] = useState("");
+  // Records can land in the collection without the framework's Add button —
+  // a chat tool, an author action, hand-written `data`. Assigning ids is the
+  // framework's job (it's reserved), so complete any record missing one;
+  // otherwise its row can never open a detail screen.
+  useEffect(() => {
+    if ((ctx.data.records || []).some((r) => r && !r.id)) {
+      ctx.update((d) => {
+        for (const r of d.records || []) if (r && !r.id) r.id = makeId();
+      });
+    }
+  });
   let records = ctx.data.records.map((r) => withComputed(spec, r));
   if (spec.sort) records = records.slice().sort(spec.sort);
   const total = records.length;
@@ -297,6 +308,55 @@ function ItemsEditor({ spec, ctx, record }) {
   );
 }
 
+// The block form of records: the same list/detail/summary machinery embedded
+// wherever panel blocks go (panel, workspace panes, documents, tabs). The
+// collection lives in the enclosing data pool under `key` (default
+// "records"), so inside `documents` each document gets its own collection
+// for free. The open record is view state under a per-collection key —
+// list/detail navigation without touching the app-level screen stack.
+function aliasRecords(d, key) {
+  if (key === "records") return d;
+  // The internal machinery reads and writes `d.records`; alias it onto the
+  // author's collection key while leaving every other property untouched
+  // (author actions receive this same object and see the real pool).
+  return new Proxy(d, {
+    get: (t, p, r) => (p === "records" ? t[key] : Reflect.get(t, p, r)),
+    set: (t, p, v) => Reflect.set(t, p === "records" ? key : p, v),
+    has: (t, p) => (p === "records" ? key in t : p in t),
+  });
+}
+
+export function RecordsBlock({ spec, ctx }) {
+  const rspec = spec.records;
+  const key = rspec.key || "records";
+  const arr = Array.isArray(ctx.data[key]) ? ctx.data[key] : [];
+  const stateKey = "caf:rec:" + key;
+  const openId = ctx.view.tabs ? ctx.view.tabs[stateKey] : undefined;
+
+  const scoped = {
+    ...ctx,
+    data: { ...ctx.data, records: arr },
+    update: (fn) => ctx.update((d) => fn(aliasRecords(d, key))),
+    go: (_screen, id) => ctx.setTab(stateKey, id),
+    back: () => ctx.setTab(stateKey, undefined),
+  };
+
+  // A deleted or stale open record falls back to the list, never a blank pane.
+  const record = openId ? arr.find((r) => r.id === openId) : null;
+
+  return h(
+    "div",
+    { className: "caf-records-block" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    record
+      ? h(DetailScreen, { key: "d", spec: rspec, ctx: scoped, record })
+      : [
+          h(Summary, { key: "s", spec: rspec, records: arr.map((r) => withComputed(rspec, r)) }),
+          h(ListScreen, { key: "l", spec: rspec, ctx: scoped }),
+        ]
+  );
+}
+
 export function RecordsLayout({ spec, ctx }) {
   const rspec = spec.records;