claude-artifact-framework 0.9.1 → 0.11.0

package/README.md

@@ -394,6 +394,74 @@ The active tab and each accordion's open/closed state are framework-owned
 view state — they survive reload, per viewer. Tabs cannot nest inside tabs;
 `when` must be a function; both throw otherwise.
 
+### The `documents` layout — parallel documents, one per top tab
+
+`tabs` are views over ONE shared data pool. When the ask is "several
+documents, each with its own state" — a multi-note editor, one budget per
+trip, one character sheet per player — that is the `documents` layout:
+declare the blocks once, and every document gets its own private copy of
+their data.
+
+```js
+ArtifactKit.createApp({
+  title: "Editor multi-documento",
+  layout: "documents",
+  documents: {
+    label: "documento",
+    title: (d) => d.nombre || "Sin título",   // tab label, live from the doc's data
+    blocks: [
+      { fields: [
+        { key: "nombre", label: "Nombre", type: "text" },
+        { key: "contenido", label: "Contenido", type: "textarea", rows: 14 },
+      ]},
+      { output: (d) => [{ label: "Palabras", value: (d.contenido || "").split(/\s+/).filter(Boolean).length }] },
+    ],
+  },
+})
+```
+
+The framework owns the whole document lifecycle: the top tab bar (one tab
+per document, live-labelled, plus a **+** tab that creates and opens a new
+document — no draft to lose, it already exists), the **✕** on each tab to
+close it (closing the open document falls back to a neighbour, never a
+blank pane), the per-document data pools (`d` inside any block, `output`,
+`custom`, or `when` is THAT document's data; `ctx.update` writes there),
+the empty state, and persistence — all documents and which one is open
+survive reload. Documents keys: `label`, `title`, `blocks`, `empty`.
+
+Inside `documents`, blocks work as in `panel` — **including `chat` and
+`file`, which become per-document**:
+
+- A `chat` block inside `documents` gives **each document its own
+  conversation**, persisted with that document (`data.chat` is scoped). Its
+  `system` function receives the document's data, so the copilot talks
+  about THIS document. One chat block per document (a second throws).
+- A `file` field inside `documents` scopes `ctx.files[key]` to the active
+  document — two documents never collide on the same field key. As
+  everywhere, the live `File` is memory-only: metadata survives reload,
+  the file is re-picked per document.
+
+That combination — one file plus one conversation per tab — is the
+multi-document annotator shape (PDFs, images, CSVs) declared in full:
+
+```js
+ArtifactKit.createApp({
+  title: "Anotador de archivos",
+  layout: "documents",
+  documents: {
+    label: "archivo",
+    title: (d) => (d.archivo && d.archivo.name) || "Sin archivo",
+    blocks: [
+      { fields: [{ key: "archivo", label: "Archivo", type: "file" }] },
+      { custom: (ctx) => { /* render ctx.files.archivo */ }, fill: true },
+      { title: "Copiloto", chat: {
+          system: (d) => "Ayudás con el archivo " + ((d.archivo && d.archivo.name) || "(ninguno)"),
+      }},
+    ],
+  },
+})
+```
+
 ### External libraries, uploaded files, full-bleed custom, viewer identity
 
 Four primitives for the custom-heavy end of the spectrum (document viewers,

package/dist/index.esm.js

@@ -1354,9 +1354,10 @@ function StepsLayout({ spec, ctx }) {
 }
 
 // src/app.js
-var LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
+var LAYOUTS = ["panel", "records", "steps", "chat", "workspace", "documents"];
 var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible", "fill"];
-var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs"];
+var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar", "libs", "documents"];
+var DOCUMENTS_KEYS = ["label", "title", "blocks", "empty"];
 function checkFields(fields, where) {
   for (const f of fields || []) {
     if (!f || !f.key) throw new Error(`claude-artifact-framework: every field in ${where} needs a \`key\`.`);
@@ -1532,6 +1533,31 @@ 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: [...] }` \u2014 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 !== void 0 && 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 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 \u2014 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) {
@@ -1609,6 +1635,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) {
@@ -1758,7 +1787,130 @@ function WorkspaceLayout({ spec, ctx }) {
     spec.sidebar && spec.sidebar.length ? createElement("div", { className: "caf-ws-side" }, render(spec.sidebar)) : null
   );
 }
-var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout };
+function docDefaults(dspec) {
+  const data = {};
+  for (const block of flattenBlocks(dspec.blocks)) {
+    for (const field of block.fields || []) {
+      if (field && field.key !== void 0 && !(field.key in data)) {
+        data[field.key] = field.value !== void 0 ? field.value : field.type === "check" ? false : "";
+      }
+    }
+  }
+  return data;
+}
+function docId() {
+  return "d" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+var DOC_TAB_KEY = "caf:doc";
+function docTitle(dspec, data) {
+  if (dspec.title) {
+    try {
+      const t = dspec.title(data);
+      if (t !== void 0 && t !== null && t !== "") return String(t);
+    } catch {
+    }
+  }
+  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 !== void 0 && 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] : void 0;
+  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 createElement(
+      "div",
+      { className: "caf-panel caf-panel-single" },
+      createElement(
+        "div",
+        { className: "caf-block caf-empty" },
+        createElement("p", null, dspec.empty || `No ${label}s yet. Create the first one.`),
+        createElement("button", { type: "button", className: "caf-btn caf-btn-primary", onClick: add }, `New ${label}`)
+      )
+    );
+  }
+  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 createElement(
+    "div",
+    { className: "caf-documents" },
+    createElement(
+      "div",
+      { className: "caf-tabbar", role: "tablist" },
+      docs.map(
+        (doc) => createElement(
+          "span",
+          { key: doc.id, className: "caf-doc-tab" },
+          createElement(
+            "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 })
+          ),
+          createElement(
+            "button",
+            {
+              type: "button",
+              className: "caf-doc-close",
+              "aria-label": `Close ${label}`,
+              onClick: () => close(doc.id)
+            },
+            "\u2715"
+          )
+        )
+      ),
+      createElement("button", { type: "button", className: "caf-tab caf-doc-add", "aria-label": `New ${label}`, onClick: add }, "+")
+    ),
+    createElement(Panel, { spec: { blocks: dspec.blocks }, ctx: scoped })
+  );
+}
+var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout, workspace: WorkspaceLayout, documents: DocumentsLayout };
 function loadScript(src) {
   return new Promise((resolve, reject) => {
     const existing = document.querySelector(`script[src="${src}"]`);
@@ -2047,6 +2199,16 @@ var 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; }