claude-artifact-framework 0.12.0 → 0.13.1

package/package.json

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

@@ -25,7 +25,7 @@ const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "col
 // silently rendering nothing — a blank pane is indistinguishable from a bug.
 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 DOCUMENTS_KEYS = ["label", "title", "blocks", "empty", "types"];
 const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute", "items", "actions"];
 const ITEMS_KEYS = ["label", "fields", "empty"];
 
@@ -219,9 +219,14 @@ function validate(spec) {
   }
   if (layout === "documents") {
     const d = spec.documents;
-    if (!d || !Array.isArray(d.blocks) || d.blocks.length === 0) {
+    if (!d || typeof d !== "object" || (!d.blocks && !d.types)) {
       throw new Error(
-        'claude-artifact-framework: layout "documents" needs `documents: { blocks: [...] }` — the blocks every document repeats, each with its own data.'
+        'claude-artifact-framework: layout "documents" needs `documents: { blocks: [...] }` (every document repeats the same blocks) or `documents: { types: {...} }` (each document is one of several kinds).'
+      );
+    }
+    if (d.blocks && d.types) {
+      throw new Error(
+        "claude-artifact-framework: documents takes `blocks` (uniform documents) OR `types` (typed documents) — not both."
       );
     }
     const unknownD = Object.keys(d).filter((k) => !DOCUMENTS_KEYS.includes(k));
@@ -233,18 +238,47 @@ function validate(spec) {
     if (d.title !== undefined && typeof d.title !== "function") {
       throw new Error("claude-artifact-framework: documents.title must be a function of the document's data returning the tab label.");
     }
-    checkBlocks(d.blocks);
     // 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 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."
-      );
+    const checkDocBlocks = (blocks, where) => {
+      checkBlocks(blocks);
+      const flat = flattenBlocks(blocks);
+      if (flat.filter((b) => b && b.chat).length > 1) {
+        throw new Error(
+          `claude-artifact-framework: only one chat block per document (${where}) — each document's conversation persists under its own data.chat and there is exactly one.`
+        );
+      }
+      checkRecordsBlockKeys(flat);
+    };
+    if (d.blocks) {
+      if (!Array.isArray(d.blocks) || d.blocks.length === 0) {
+        throw new Error("claude-artifact-framework: documents.blocks must be a non-empty array of blocks.");
+      }
+      checkDocBlocks(d.blocks, "documents.blocks");
+    } else {
+      const names = Object.keys(d.types || {});
+      if (!names.length) {
+        throw new Error("claude-artifact-framework: documents.types needs at least one type, e.g. `types: { nota: { blocks: [...] } }`.");
+      }
+      for (const name of names) {
+        const t = d.types[name];
+        const TYPE_KEYS = ["label", "title", "blocks", "empty"];
+        const unknownT = Object.keys(t || {}).filter((k) => !TYPE_KEYS.includes(k));
+        if (unknownT.length) {
+          throw new Error(
+            `claude-artifact-framework: documents.types.${name} has unknown keys (${unknownT.join(", ")}). Valid keys: ${TYPE_KEYS.join(", ")}.`
+          );
+        }
+        if (!t || !Array.isArray(t.blocks) || t.blocks.length === 0) {
+          throw new Error(`claude-artifact-framework: documents.types.${name} needs a non-empty \`blocks\` array.`);
+        }
+        if (t.title !== undefined && typeof t.title !== "function") {
+          throw new Error(`claude-artifact-framework: documents.types.${name}.title must be a function of the document's data.`);
+        }
+        checkDocBlocks(t.blocks, `documents.types.${name}`);
+      }
     }
-    checkRecordsBlockKeys(docFlat);
     return layout;
   }
   if (layout === "records") {
@@ -574,7 +608,7 @@ function docId() {
 
 const DOC_TAB_KEY = "caf:doc";
 
-function docTitle(dspec, data) {
+function docTitle(dspec, data, untitled) {
   if (dspec.title) {
     try {
       const t = dspec.title(data);
@@ -583,35 +617,52 @@ function docTitle(dspec, data) {
       /* fall through to the default below */
     }
   }
-  // Default: the first text-ish field — same convention records uses.
+  // Default: the first text-ish field — same convention records uses. Typed
+  // documents fall back to their type label instead of "(untitled)".
   for (const block of flattenBlocks(dspec.blocks)) {
     for (const f of block.fields || []) {
       if (!f.type || f.type === "text" || f.type === "textarea" || f.type === "select") {
         const v = data[f.key];
         if (v !== "" && v !== undefined && v !== null) return String(v);
-        return "(untitled)";
+        return untitled || "(untitled)";
       }
     }
   }
-  return "(untitled)";
+  return untitled || "(untitled)";
 }
 
 function DocumentsLayout({ spec, ctx }) {
   const dspec = spec.documents;
   const label = dspec.label || "document";
   const docs = Array.isArray(ctx.data.docs) ? ctx.data.docs : [];
-  const defaults = docDefaults(dspec);
+  // Typed documents: each doc records which kind it is (`doc.type`, on the
+  // envelope — never inside the document's data) and renders ITS type's
+  // blocks. Uniform documents are the one-type degenerate case.
+  const types = dspec.types || null;
+  const typeNames = types ? Object.keys(types) : [];
+  const specFor = (doc) => (types ? types[doc.type] : dspec);
+  const typeLabel = (name) => (types[name] && types[name].label) || name;
+  const [picking, setPicking] = useState(false);
 
   const storedId = ctx.view.tabs ? ctx.view.tabs[DOC_TAB_KEY] : undefined;
   // A deleted or stale id falls back to the first document, never a blank pane.
   const active = docs.find((doc) => doc.id === storedId) || docs[0];
 
-  function add() {
-    const doc = { id: docId(), data: docDefaults(dspec) };
+  function add(typeName) {
+    const tspec = types ? types[typeName] : dspec;
+    const doc = { id: docId(), ...(types ? { type: typeName } : {}), data: docDefaults(tspec) };
     ctx.update((d) => {
       d.docs = [...(d.docs || []), doc];
     });
     ctx.setTab(DOC_TAB_KEY, doc.id);
+    setPicking(false);
+  }
+
+  // One type (or uniform) creates directly; several ask which kind first.
+  function onAdd() {
+    if (!types) return add();
+    if (typeNames.length === 1) return add(typeNames[0]);
+    setPicking((p) => !p);
   }
 
   function close(id) {
@@ -626,6 +677,16 @@ function DocumentsLayout({ spec, ctx }) {
     }
   }
 
+  const typePicker = types && picking
+    ? h(
+        "div",
+        { className: "caf-doc-typemenu" },
+        typeNames.map((name) =>
+          h("button", { key: name, type: "button", className: "caf-btn caf-btn-sm", onClick: () => add(name) }, typeLabel(name))
+        )
+      )
+    : null;
+
   if (!active) {
     return h(
       "div",
@@ -634,10 +695,37 @@ function DocumentsLayout({ spec, ctx }) {
         "div",
         { className: "caf-block caf-empty" },
         h("p", null, dspec.empty || `No ${label}s yet. Create the first one.`),
-        h("button", { type: "button", className: "caf-btn caf-btn-primary", onClick: add }, `New ${label}`)
+        types
+          ? h(
+              "div",
+              { className: "caf-doc-typemenu" },
+              typeNames.map((name) =>
+                h("button", { key: name, type: "button", className: "caf-btn caf-btn-primary", onClick: () => add(name) }, `New ${typeLabel(name)}`)
+              )
+            )
+          : h("button", { type: "button", className: "caf-btn caf-btn-primary", onClick: () => add() }, `New ${label}`)
+      )
+    );
+  }
+
+  const aspec = specFor(active);
+  // A document whose type was removed from the spec: loud, named, contained —
+  // the tab (and its ✕) stays usable, the pane explains instead of crashing.
+  if (!aspec) {
+    return h(
+      "div",
+      { className: "caf-documents" },
+      h(DocTabbar, { docs, active, dspec, types, close, onAdd, label, ctx }),
+      typePicker,
+      h(
+        "div",
+        { className: "caf-block caf-block-error" },
+        h("strong", null, `This ${label}'s type "${active.type}" no longer exists`),
+        h("code", null, `valid types: ${typeNames.join(", ")}`)
       )
     );
   }
+  const defaults = docDefaults(aspec);
 
   // Stored data merges over declared defaults, so a field added in a later
   // edit of the spec falls through to its default on older documents (B3).
@@ -660,39 +748,51 @@ function DocumentsLayout({ spec, ctx }) {
   return h(
     "div",
     { className: "caf-documents" },
-    h(
-      "div",
-      { className: "caf-tabbar", role: "tablist" },
-      docs.map((doc) =>
+    h(DocTabbar, { docs, active, dspec, types, close, onAdd, label, ctx }),
+    typePicker,
+    h(Panel, { spec: { blocks: aspec.blocks }, ctx: scoped })
+  );
+}
+
+function DocTabbar({ docs, active, dspec, types, close, onAdd, label, ctx }) {
+  const tabTitle = (doc) => {
+    const tspec = types ? types[doc.type] : dspec;
+    if (!tspec) return doc.type; // removed type: the name is the best label left
+    const merged = { ...docDefaults(tspec), ...doc.data };
+    const fallback = types ? (tspec.label || doc.type) : undefined;
+    return docTitle(tspec, merged, fallback);
+  };
+  return h(
+    "div",
+    { className: "caf-tabbar", role: "tablist" },
+    docs.map((doc) =>
+      h(
+        "span",
+        { key: doc.id, className: "caf-doc-tab" },
         h(
-          "span",
-          { key: doc.id, className: "caf-doc-tab" },
-          h(
-            "button",
-            {
-              type: "button",
-              role: "tab",
-              "aria-selected": doc.id === active.id,
-              className: doc.id === active.id ? "caf-tab caf-tab-active" : "caf-tab",
-              onClick: () => ctx.setTab(DOC_TAB_KEY, doc.id),
-            },
-            docTitle(dspec, { ...defaults, ...doc.data })
-          ),
-          h(
-            "button",
-            {
-              type: "button",
-              className: "caf-doc-close",
-              "aria-label": `Close ${label}`,
-              onClick: () => close(doc.id),
-            },
-            "✕"
-          )
+          "button",
+          {
+            type: "button",
+            role: "tab",
+            "aria-selected": doc.id === active.id,
+            className: doc.id === active.id ? "caf-tab caf-tab-active" : "caf-tab",
+            onClick: () => ctx.setTab(DOC_TAB_KEY, doc.id),
+          },
+          tabTitle(doc)
+        ),
+        h(
+          "button",
+          {
+            type: "button",
+            className: "caf-doc-close",
+            "aria-label": `Close ${label}`,
+            onClick: () => close(doc.id),
+          },
+          "✕"
         )
-      ),
-      h("button", { type: "button", className: "caf-tab caf-doc-add", "aria-label": `New ${label}`, onClick: add }, "+")
+      )
     ),
-    h(Panel, { spec: { blocks: dspec.blocks }, ctx: scoped })
+    h("button", { type: "button", className: "caf-tab caf-doc-add", "aria-label": `New ${label}`, onClick: onAdd }, "+")
   );
 }
 
@@ -1014,6 +1114,7 @@ const BASE_CSS = `
 .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-doc-typemenu { display: flex; gap: 0.5rem; flex-wrap: wrap; }
 .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; }