claude-artifact-framework 0.9.1 → 0.11.0

package/package.json

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

@@ -17,13 +17,15 @@ import { RecordsLayout } from "./records.js";
 import { StepsLayout } from "./steps.js";
 import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
-const LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
+const LAYOUTS = ["panel", "records", "steps", "chat", "workspace", "documents"];
 const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
 
 // Frontier models still invent identifiers a few percent of the time, so an
 // unknown name has to fail loudly and name the alternatives rather than
 // 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"];
+const TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents"];
+
+const DOCUMENTS_KEYS = ["label", "title", "blocks", "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
@@ -210,6 +212,34 @@ function validate(spec) {
     }
     return layout;
   }
+  if (layout === "documents") {
+    const d = spec.documents;
+    if (!d || !Array.isArray(d.blocks) || d.blocks.length === 0) {
+      throw new Error(
+        'claude-artifact-framework: layout "documents" needs `documents: { blocks: [...] }` — the blocks every document repeats, each with its own data.'
+      );
+    }
+    const unknownD = Object.keys(d).filter((k) => !DOCUMENTS_KEYS.includes(k));
+    if (unknownD.length) {
+      throw new Error(
+        `claude-artifact-framework: documents has unknown keys (${unknownD.join(", ")}). Valid keys: ${DOCUMENTS_KEYS.join(", ")}.`
+      );
+    }
+    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 chats = flattenBlocks(d.blocks).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."
+      );
+    }
+    return layout;
+  }
   if (layout === "records") {
     const r = spec.records;
     if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
@@ -294,6 +324,9 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
+  if ((spec.layout || "panel") === "documents" && !Array.isArray(data.docs)) {
+    data.docs = [];
+  }
   const allBlocks = flattenBlocks([...(spec.blocks || []), ...(spec.main || []), ...(spec.sidebar || [])]);
   const hasChat = (spec.layout || "panel") === "chat" || allBlocks.some((b) => b && b.chat);
   if (hasChat && !data.chat) {
@@ -470,7 +503,152 @@ function WorkspaceLayout({ spec, ctx }) {
   );
 }
 
-const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout };
+// documents — N parallel instances of the same mini-app, one per top tab.
+// Each document owns a full data pool; the blocks are declared once and see
+// ONLY the active document's data through a scoped ctx. Which document is
+// open lives in view state (personal, survives reload); the documents
+// themselves live in data.docs.
+function docDefaults(dspec) {
+  const data = {};
+  for (const block of flattenBlocks(dspec.blocks)) {
+    for (const field of block.fields || []) {
+      if (field && field.key !== undefined && !(field.key in data)) {
+        data[field.key] = field.value !== undefined ? field.value : field.type === "check" ? false : "";
+      }
+    }
+  }
+  return data;
+}
+
+function docId() {
+  return "d" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+const DOC_TAB_KEY = "caf:doc";
+
+function docTitle(dspec, data) {
+  if (dspec.title) {
+    try {
+      const t = dspec.title(data);
+      if (t !== undefined && t !== null && t !== "") return String(t);
+    } catch {
+      /* fall through to the default below */
+    }
+  }
+  // Default: the first text-ish field — same convention records uses.
+  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)";
+}
+
+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);
+
+  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) };
+    ctx.update((d) => {
+      d.docs = [...(d.docs || []), doc];
+    });
+    ctx.setTab(DOC_TAB_KEY, doc.id);
+  }
+
+  function close(id) {
+    const idx = docs.findIndex((doc) => doc.id === id);
+    ctx.update((d) => {
+      d.docs = d.docs.filter((doc) => doc.id !== id);
+    });
+    delete ctx.files["doc:" + id];
+    if (active && active.id === id) {
+      const next = docs[idx + 1] || docs[idx - 1];
+      if (next) ctx.setTab(DOC_TAB_KEY, next.id);
+    }
+  }
+
+  if (!active) {
+    return h(
+      "div",
+      { className: "caf-panel caf-panel-single" },
+      h(
+        "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}`)
+      )
+    );
+  }
+
+  // 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).
+  const activeData = { ...defaults, ...active.data };
+  const scoped = {
+    ...ctx,
+    data: activeData,
+    update: (fn) =>
+      ctx.update((d) => {
+        const doc = (d.docs || []).find((x) => x.id === active.id);
+        if (doc) fn(doc.data);
+      }),
+    // Live File objects scoped per document: each doc gets its own sub-map,
+    // so two documents with the same file field never collide. Like the flat
+    // pool, the File itself is memory-only — metadata survives reload, the
+    // file is re-picked per document.
+    files: (ctx.files["doc:" + active.id] = ctx.files["doc:" + active.id] || {}),
+  };
+
+  return h(
+    "div",
+    { className: "caf-documents" },
+    h(
+      "div",
+      { className: "caf-tabbar", role: "tablist" },
+      docs.map((doc) =>
+        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),
+            },
+            "✕"
+          )
+        )
+      ),
+      h("button", { type: "button", className: "caf-tab caf-doc-add", "aria-label": `New ${label}`, onClick: add }, "+")
+    ),
+    h(Panel, { spec: { blocks: dspec.blocks }, ctx: scoped })
+  );
+}
+
+const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout, documents: DocumentsLayout };
 
 // Deduped by src: two apps (or re-mounts) asking for the same lib share one
 // tag, mirroring how the PDF annotator loads pdf.js by hand.
@@ -777,6 +955,16 @@ const BASE_CSS = `
 /* Accent chevron: the one interaction cue that distinguishes a collapsible
    header from a static card title without breaking their shared typography. */
 .caf-chevron { transition: transform 0.15s ease; color: var(--caf-accent); }
+.caf-documents { max-width: 760px; margin: 0 auto; display: flex; flex-direction: column; gap: 1rem; }
+.caf-doc-tab { display: inline-flex; align-items: center; }
+.caf-doc-tab .caf-tab { padding-right: 0.35rem; max-width: 180px; overflow: hidden; text-overflow: ellipsis; }
+.caf-doc-close {
+  font: inherit; font-size: 0.7rem; cursor: pointer; border: none; background: none;
+  color: var(--caf-muted); padding: 0.2rem 0.45rem 0.2rem 0.1rem; line-height: 1;
+}
+.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-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; }