claude-artifact-framework 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-artifact-framework",
-  "version": "0.9.0",
+  "version": "0.10.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,36 @@ 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);
+    const flat = flattenBlocks(d.blocks);
+    if (flat.some((b) => b && b.chat)) {
+      throw new Error(
+        'claude-artifact-framework: a chat block inside "documents" is not supported — the conversation store is app-wide, not per document.'
+      );
+    }
+    if (flat.some((b) => (b.fields || []).some((f) => f.type === "file"))) {
+      throw new Error(
+        'claude-artifact-framework: `file` fields live in the flat data pool — they are not supported inside documents (the live File cannot be scoped per document).'
+      );
+    }
+    return layout;
+  }
   if (layout === "records") {
     const r = spec.records;
     if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
@@ -294,6 +326,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 +505,146 @@ 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);
+    });
+    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);
+      }),
+  };
+
+  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.
@@ -617,7 +791,9 @@ const BASE_CSS = `
 }
 .caf-block-title { margin: 0; font-size: 0.78rem; font-weight: 650; text-transform: uppercase; letter-spacing: 0.06em; color: var(--caf-muted); }
 .caf-field { display: flex; flex-direction: column; gap: 0.3rem; }
-.caf-field label { font-size: 0.72rem; font-weight: 500; color: var(--caf-muted); letter-spacing: 0.02em; }
+/* A full size+weight step below .caf-block-title — the uppercase alone was
+   not enough to tell "card title" from "field label" at a glance. */
+.caf-field label { font-size: 0.68rem; font-weight: 500; color: var(--caf-muted); }
 .caf-field input, .caf-field select, .caf-field textarea {
   font: inherit; font-size: 0.95rem; padding: 0.5rem 0.6rem;
   border-radius: var(--caf-control-radius); border: 1px solid var(--caf-border);
@@ -651,7 +827,9 @@ const BASE_CSS = `
 .caf-row-sub { font-size: 0.78rem; color: var(--caf-muted); }
 .caf-panel-single { grid-template-columns: 1fr; }
 .caf-panel-single .caf-slot, .caf-panel-single > * { grid-column: span 1; }
-.caf-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 0.6rem; padding: 0.3rem 0.3rem 0.5rem; }
+/* Bottom padding matches the inter-row rhythm so the toolbar doesn't sit
+   closer to the first row than rows sit to each other. */
+.caf-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 0.6rem; padding: 0.3rem 0.3rem 0.75rem; }
 .caf-count { font-size: 0.8rem; color: var(--caf-muted); font-variant-numeric: tabular-nums; }
 .caf-btn {
   font: inherit; font-size: 0.85rem; font-weight: 600; cursor: pointer;
@@ -676,7 +854,8 @@ const BASE_CSS = `
 .caf-line-meta { display: flex; justify-content: space-between; align-items: baseline; gap: 0.6rem; }
 .caf-line-last { font-weight: 650; font-variant-numeric: tabular-nums; color: var(--caf-accent); }
 .caf-donut { display: flex; align-items: center; gap: 1.1rem; flex-wrap: wrap; }
-.caf-donut-svg { width: 110px; height: 110px; flex: none; transform: rotate(0.001deg); }
+/* -3px optical correction: a circle beside flush-left text reads indented. */
+.caf-donut-svg { width: 110px; height: 110px; flex: none; transform: rotate(0.001deg); margin-left: -3px; }
 .caf-donut-seg { fill: none; stroke-width: 6; }
 /* Capped width keeps each value NEXT TO its label in wide cards — the pair
    must read as a pair regardless of container width. */
@@ -769,7 +948,19 @@ const BASE_CSS = `
 .caf-collapse-head { box-shadow: 0 1px 2px rgba(0, 0, 0, 0.08); }
 .caf-collapse-head:hover { filter: brightness(0.97); }
 .caf-collapse-head:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
-.caf-chevron { transition: transform 0.15s ease; color: var(--caf-muted); }
+/* 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; }

package/src/blocks.js

@@ -464,7 +464,7 @@ export const BLOCKS = {
   chart: ChartBlock,
   timer: TimerBlock,
   actions: ActionsBlock,
-  chat: ({ spec, ctx }) => h(ChatPanel, { cfg: spec.chat, ctx }),
+  chat: ({ spec, ctx }) => h(ChatPanel, { cfg: spec.chat, ctx, title: spec.title }),
   custom: CustomBlock,
 };
 

package/src/chat.js

@@ -171,7 +171,7 @@ function Bubble({ m }) {
 // The embeddable core: everything the chat layout does, as a single column
 // that can live in a workspace sidebar (or any block slot) as well as fill
 // the whole app. One conversation per app — it persists under data.chat.
-export function ChatPanel({ cfg, ctx }) {
+export function ChatPanel({ cfg, ctx, title }) {
   const c = cfg;
   const [draft, setDraft] = useState("");
   const [busy, setBusy] = useState(false);
@@ -250,6 +250,9 @@ export function ChatPanel({ cfg, ctx }) {
     h(
       "div",
       { className: "caf-block caf-chat-log" },
+      // Every other block opens with its title label — a chat card that
+      // starts straight at a bubble was the one heading-less block on screen.
+      title ? h("h2", { className: "caf-block-title" }, title) : null,
       c.greeting
         ? h("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } })
         : null,