claude-artifact-framework 0.7.1 → 0.7.3

package/README.md

@@ -1,8 +1,16 @@
 # claude-artifact-framework
 
-Utilities for building apps inside Claude Artifacts: platform storage, reactive
-state, and other primitives verified against the real runtime. Zero
-dependencies, no build step — drop it into an artifact straight from a CDN.
+A declarative framework for building apps inside Claude Artifacts: declare
+what the app **is** — fields, records, steps, a chat with tools, a workspace
+with a copilot — and the framework owns how it works. Persistence, hydration,
+validation, empty/loading/error states, light+dark theming, navigation, and
+the Claude tool loop are construction guarantees, not authoring tasks.
+
+Five layouts (`panel`, `records`, `steps`, `chat`, `workspace`), ten block
+types, tabs/conditional/collapsible composition, shared multi-viewer data,
+and a `custom` escape hatch that keeps every framework service. Zero
+dependencies, no build step — load it straight from a CDN. The decisions and
+the evidence behind them live in [DESIGN.md](./DESIGN.md).
 
 ## Usage via CDN
 
@@ -12,8 +20,11 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.1/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.3/dist/index.global.js"></script>
 <script>
+  ArtifactKit.useReact(React); // hand over the page's React once
+  const App = ArtifactKit.createApp({ title: "Mi app", blocks: [ /* ... */ ] });
+  // lower-level utilities are also exported:
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
 ```
@@ -27,11 +38,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.1/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.7.3/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.7.1`) for reproducible artifacts, or drop the version
+Pin a version (`@0.7.3`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -172,6 +183,9 @@ blocks: [
 ]
 ```
 
+`timer` takes `minutes` and/or `seconds` (`{ seconds: 90 }` for a rest timer),
+plus optional `label` and `doneText`.
+
 `text` blocks also accept a function of data — `{ text: (d) => "Hola " + d.nombre }` —
 with the same contract as `output`.
 
@@ -350,12 +364,37 @@ ArtifactKit.createApp({
 block per app — the conversation persists under `data.chat` and there is
 exactly one.
 
+### Tabs, conditional blocks, and accordions
+
+Three in-screen navigation primitives, usable in `panel`, `workspace`, and
+below a `records` list alike:
+
+```js
+blocks: [
+  { tabs: [
+    { label: "Registrar", blocks: [{ fields: [...] }] },
+    { label: "Resumen",   blocks: [{ output: (d) => [...] }, { chart: (d) => ({...}) }] },
+  ], wide: true },
+
+  // `when` hides any block until the condition holds
+  { output: (d) => [...], when: (d) => d.records.length > 0 },
+
+  // `collapsible` needs a title; `"collapsed"` starts closed
+  { text: "Instrucciones…", title: "Ayuda", collapsible: "collapsed" },
+]
+```
+
+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.
+
 ## API reference
 
 Everything an app can declare, in one place.
 
 **Top-level keys**: `title`, `subtitle`, `theme: { seed }`, `layout`, `blocks`,
-`records`, `steps`, `chat`, `data`, `shared`. Anything else throws.
+`records`, `steps`, `chat`, `main`, `sidebar` (workspace panes), `data`,
+`shared`. Anything else throws.
 
 **Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
 list), `steps` (wizard), `chat` (conversation with Claude), `workspace`
@@ -363,7 +402,12 @@ list), `steps` (wizard), `chat` (conversation with Claude), `workspace`
 `records` / `steps` / `chat` / `main`+`sidebar`).
 
 **Block types** (entries of `blocks`, `main`, or `sidebar`): `fields`,
-`output`, `text`, `list`, `chart`, `timer`, `actions`, `chat`, `custom`. One type per entry, plus optional `title`, `empty`,
+`output`, `text`, `list`, `chart`, `timer`, `actions`, `chat`, `tabs`,
+`custom`. Any block also accepts `when: (d) => bool` (conditional
+visibility) and `collapsible: true | "collapsed"` (accordion; needs `title`).
+On every block `title` is the heading string; `list` additionally accepts a
+function as `title`, used as the per-row title (rows fall back to
+`r.title ?? r.name ?? r.label ?? r.text`). One type per entry, plus optional `title`, `empty`,
 `wide`. In the `records` layout, `blocks` render below the list (never on the
 detail screen); their functions receive the same `data` object as everywhere
 else — the collection lives at `d.records`.

package/dist/index.esm.js

@@ -134,7 +134,7 @@ var Component = React && React.Component || class ReactMissing {
 // src/appState.js
 var DATA_KEY = "caf:data";
 var VIEW_KEY = "caf:view";
-var EMPTY_VIEW = { screen: null, arg: null, stack: [], step: 0, selected: null };
+var EMPTY_VIEW = { screen: null, arg: null, stack: [], step: 0, selected: null, tabs: {}, collapsed: {} };
 function isPlainObject(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v);
 }
@@ -1317,7 +1317,7 @@ function StepsLayout({ spec, ctx }) {
 
 // src/app.js
 var LAYOUTS = ["panel", "records", "steps", "chat", "workspace"];
-var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
+var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle", "when", "collapsible"];
 var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared", "main", "sidebar"];
 function checkFields(fields, where) {
   for (const f of fields || []) {
@@ -1380,7 +1380,7 @@ function checkBlocks(blocks) {
       throw new Error(`claude-artifact-framework: blocks[${i}] must be an object like { fields: [...] }.`);
     }
     const keys = Object.keys(block).filter((k) => !RESERVED.includes(k));
-    const known = keys.filter((k) => BLOCK_NAMES.includes(k));
+    const known = keys.filter((k) => BLOCK_NAMES.includes(k) || k === "tabs");
     if (known.length === 0) {
       throw new Error(
         `claude-artifact-framework: blocks[${i}] has no recognised block type (found: ${keys.join(", ") || "nothing"}). Valid block types: ${BLOCK_NAMES.join(", ")}.`
@@ -1396,6 +1396,24 @@ function checkBlocks(blocks) {
     checkFields(block.fields, `blocks[${i}]`);
     if (known[0] === "actions") checkActions(block.actions, `blocks[${i}].actions`);
     if (known[0] === "chat") checkChatConfig(block.chat, `blocks[${i}].chat`);
+    if (known[0] === "tabs") {
+      const tabs = block.tabs;
+      if (!Array.isArray(tabs) || tabs.length === 0) {
+        throw new Error(`claude-artifact-framework: blocks[${i}].tabs needs an array of { label, blocks: [...] }.`);
+      }
+      tabs.forEach((t, j) => {
+        if (!t || typeof t.label !== "string" || !Array.isArray(t.blocks) || t.blocks.length === 0) {
+          throw new Error(`claude-artifact-framework: tabs[${j}] needs a \`label\` string and a non-empty \`blocks\` array.`);
+        }
+        if (t.blocks.some((b) => b && b.tabs)) {
+          throw new Error("claude-artifact-framework: tabs cannot nest inside tabs.");
+        }
+        checkBlocks(t.blocks);
+      });
+    }
+    if (block.when !== void 0 && typeof block.when !== "function") {
+      throw new Error(`claude-artifact-framework: blocks[${i}].when must be a function of data returning true/false.`);
+    }
   });
 }
 function validate(spec) {
@@ -1460,7 +1478,7 @@ function validate(spec) {
       }
       checkBlocks(spec.sidebar);
     }
-    const chats = [...spec.main, ...spec.sidebar || []].filter((b) => b && b.chat);
+    const chats = flattenBlocks([...spec.main, ...spec.sidebar || []]).filter((b) => b && b.chat);
     if (chats.length > 1) {
       throw new Error(
         "claude-artifact-framework: only one chat block per app \u2014 the conversation persists under data.chat and there is exactly one."
@@ -1527,12 +1545,20 @@ function validate(spec) {
   checkBlocks(spec.blocks || []);
   return layout;
 }
+function flattenBlocks(blocks) {
+  const out = [];
+  for (const b of blocks || []) {
+    out.push(b);
+    if (b && Array.isArray(b.tabs)) for (const t of b.tabs) out.push(...flattenBlocks(t.blocks));
+  }
+  return out;
+}
 function defaultsFrom(spec) {
   const data = { ...spec.data || {} };
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
-  const allBlocks = [...spec.blocks || [], ...spec.main || [], ...spec.sidebar || []];
+  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) {
     data.chat = { api: [], log: [] };
@@ -1572,10 +1598,69 @@ function boundary(React2) {
   }
   return BlockBoundary;
 }
+function TabsBlock({ spec, ctx }) {
+  const tabs = spec.tabs;
+  const key = tabs.map((t) => t.label).join("|");
+  const stored = ctx.view.tabs ? ctx.view.tabs[key] : void 0;
+  const active = Math.min(stored === void 0 ? 0 : stored, tabs.length - 1);
+  return createElement(
+    "div",
+    { className: "caf-tabs" },
+    createElement(
+      "div",
+      { className: "caf-tabbar", role: "tablist" },
+      tabs.map(
+        (t, i) => createElement(
+          "button",
+          {
+            key: t.label,
+            type: "button",
+            role: "tab",
+            "aria-selected": i === active,
+            className: i === active ? "caf-tab caf-tab-active" : "caf-tab",
+            onClick: () => ctx.setTab(key, i)
+          },
+          t.label
+        )
+      )
+    ),
+    createElement(
+      "div",
+      { className: "caf-tabs-body" },
+      tabs[active].blocks.map((b, i) => createElement(Block, { key: active + ":" + i, block: b, ctx }))
+    )
+  );
+}
+var ALL_BLOCKS = { ...BLOCKS, tabs: TabsBlock };
+var ALL_NAMES = [...BLOCK_NAMES, "tabs"];
 function Block({ block, ctx }) {
-  const name = Object.keys(block).find((k) => BLOCK_NAMES.includes(k));
-  const Component2 = BLOCKS[name];
-  return createElement(boundary(ctx.React), null, createElement(Component2, { spec: block, ctx }));
+  if (typeof block.when === "function" && !block.when(ctx.data)) return null;
+  const name = Object.keys(block).find((k) => ALL_NAMES.includes(k));
+  const Component2 = ALL_BLOCKS[name];
+  const inner = createElement(
+    boundary(ctx.React),
+    null,
+    createElement(Component2, { spec: block.collapsible ? { ...block, title: void 0 } : block, ctx })
+  );
+  if (!block.collapsible) return inner;
+  const key = typeof block.title === "string" && block.title ? block.title : name;
+  const collapsed = ctx.view.collapsed && key in ctx.view.collapsed ? ctx.view.collapsed[key] : block.collapsible === "collapsed";
+  return createElement(
+    "div",
+    { className: "caf-collapse" },
+    createElement(
+      "button",
+      {
+        type: "button",
+        className: "caf-collapse-head",
+        "aria-expanded": !collapsed,
+        onClick: () => ctx.toggleCollapsed(key, !collapsed)
+      },
+      createElement("span", null, block.title || name),
+      createElement("span", { className: collapsed ? "caf-chevron caf-chevron-closed" : "caf-chevron" }, "\u25BE")
+    ),
+    collapsed ? null : createElement("div", { className: "caf-collapse-body" }, inner)
+  );
 }
 function Panel({ spec, ctx }) {
   return createElement(
@@ -1643,6 +1728,8 @@ function createApp(spec = {}) {
       go: state.go,
       back: state.back,
       setStep: (n) => state.setView({ step: n }),
+      setTab: (key, i) => state.setView({ tabs: { ...state.getView().tabs, [key]: i } }),
+      toggleCollapsed: (key, val) => state.setView({ collapsed: { ...state.getView().collapsed, [key]: val } }),
       colors: (n) => seriesColors(spec.theme && spec.theme.seed, n)
     };
     const Layout = LAYOUT_COMPONENTS[layout];
@@ -1808,6 +1895,27 @@ var BASE_CSS = `
   .caf-workspace { flex-direction: column; align-items: stretch; }
   .caf-ws-side { width: 100%; position: static; }
 }
+.caf-tabs { display: flex; flex-direction: column; gap: 0.8rem; min-width: 0; }
+.caf-tabbar { display: flex; gap: 0.2rem; border-bottom: 1px solid var(--caf-border); overflow-x: auto; }
+.caf-tab {
+  font: inherit; font-size: 0.85rem; font-weight: 600; cursor: pointer;
+  padding: 0.45rem 0.8rem; border: none; background: none; color: var(--caf-muted);
+  border-bottom: 2px solid transparent; margin-bottom: -1px; white-space: nowrap;
+}
+.caf-tab:hover { color: var(--caf-text); }
+.caf-tab:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: -2px; }
+.caf-tab-active { color: var(--caf-accent); border-bottom-color: var(--caf-accent); }
+.caf-tabs-body { display: flex; flex-direction: column; gap: 0.8rem; }
+.caf-collapse { display: flex; flex-direction: column; gap: 0.5rem; min-width: 0; }
+.caf-collapse-head {
+  font: inherit; font-size: 0.95rem; font-weight: 650; cursor: pointer;
+  display: flex; align-items: center; justify-content: space-between; gap: 0.6rem;
+  padding: 0.7rem 1rem; border: 1px solid var(--caf-border); border-radius: var(--caf-radius);
+  background: var(--caf-surface); color: var(--caf-text); width: 100%; text-align: left;
+}
+.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); }
+.caf-chevron-closed { transform: rotate(-90deg); }
 .caf-empty, .caf-loading { color: var(--caf-muted); font-size: 0.9rem; text-align: center; padding: 1.6rem 1rem; }
 .caf-block-error { border-color: var(--caf-danger); gap: 0.4rem; }
 .caf-block-error strong { font-size: 0.9rem; color: var(--caf-danger); }