claude-artifact-framework 0.9.0 → 0.10.0

package/README.md

@@ -347,7 +347,8 @@ ArtifactKit.createApp({
     { output: (d) => [{ label: "Palabras", value: countWords(d.nota), big: true }] },
   ],
   sidebar: [
-    { chat: {
+    { title: "Asistente",
+      chat: {
         system: (d) => "Sos un copiloto de escritura. Nota actual: " + (d.nota || ""),
         tools: {
           reescribir_nota: {
@@ -361,6 +362,9 @@ ArtifactKit.createApp({
 })
 ```
 
+Give the chat block a `title` (like every other block) — a chat card that
+opens straight into a bubble is the one block on screen without a heading.
+
 `main` is required; `sidebar` is optional. Both take the same blocks as
 `panel`. The panes sit side by side and stack on narrow screens. One chat
 block per app — the conversation persists under `data.chat` and there is
@@ -390,6 +394,44 @@ 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`; `chat` blocks and `file`
+fields are not supported there (both are app-wide, not per-document) and
+throw at creation.
+
 ### 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

@@ -507,7 +507,7 @@ function Bubble({ m }) {
     dangerouslySetInnerHTML: { __html: renderMarkdown(m.content) }
   });
 }
-function ChatPanel({ cfg, ctx }) {
+function ChatPanel({ cfg, ctx, title }) {
   const c = cfg;
   const [draft, setDraft] = useState("");
   const [busy, setBusy] = useState(false);
@@ -578,6 +578,9 @@ Continue with this information. If you have everything you need, answer in natur
     createElement(
       "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 ? createElement("h2", { className: "caf-block-title" }, title) : null,
       c.greeting ? createElement("div", { className: "caf-msg caf-msg-assistant", dangerouslySetInnerHTML: { __html: renderMarkdown(c.greeting) } }) : null,
       log.map((m, i) => createElement(Bubble, { key: i, m })),
       live !== null ? createElement("div", { className: "caf-msg caf-msg-assistant caf-msg-live", dangerouslySetInnerHTML: { __html: renderMarkdown(live || "\u2026") } }) : null,
@@ -1008,7 +1011,7 @@ var BLOCKS = {
   chart: ChartBlock,
   timer: TimerBlock,
   actions: ActionsBlock,
-  chat: ({ spec, ctx }) => createElement(ChatPanel, { cfg: spec.chat, ctx }),
+  chat: ({ spec, ctx }) => createElement(ChatPanel, { cfg: spec.chat, ctx, title: spec.title }),
   custom: CustomBlock
 };
 var BLOCK_NAMES = Object.keys(BLOCKS);
@@ -1351,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\`.`);
@@ -1529,6 +1533,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: [...] }` \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 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 \u2014 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 \u2014 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) {
@@ -1606,6 +1640,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) {
@@ -1755,7 +1792,124 @@ 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);
+    });
+    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);
+    })
+  };
+  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}"]`);
@@ -1884,7 +2038,9 @@ var 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 \u2014 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);
@@ -1918,7 +2074,9 @@ var 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;
@@ -1943,7 +2101,8 @@ var 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 \u2014 the pair
    must read as a pair regardless of container width. */
@@ -2036,7 +2195,19 @@ var 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; }