claude-artifact-framework 0.5.0 → 0.5.1

package/README.md

@@ -12,7 +12,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.1/dist/index.global.js"></script>
 <script>
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
@@ -27,11 +27,11 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.5.1/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.5.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.5.1`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -254,6 +254,43 @@ ArtifactKit.createApp({
   that haven't been persisted yet. View state (which screen is open) stays
   personal per viewer.
 
+## 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.
+
+**Layouts** (`layout:`): `panel` (default — grid of blocks), `records` (CRUD
+list), `steps` (wizard), `chat` (conversation with Claude). Each requires its
+matching key (`blocks` / `records` / `steps` / `chat`).
+
+**Block types** (entries of `blocks`): `fields`, `output`, `text`, `list`,
+`chart`, `timer`, `custom`. 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`.
+
+**Field types** (`type:` on any field): `text` (default), `textarea`,
+`number`, `money`, `percent`, `check` (checkbox), `date`, `select` (needs
+`options`). Other field keys: `key` (required), `label`, `value` (initial),
+`required`, `min`, `max`, `step`, `placeholder`, `hint`, `rows`, `options`.
+An unknown `type` throws naming the valid ones.
+
+**`records` keys**: `label`, `fields`, `title(r)`, `subtitle(r)`, `sort(a,b)`,
+`summary(all)`, `empty`, `search`, `compute`. `id` is framework-assigned and
+reserved.
+
+**`steps` keys** (per step): `title`, `text`, `fields`, `result(d)`. Field
+keys must be unique across steps.
+
+**`chat` keys**: `system` (string or `(d) => string`), `greeting`,
+`placeholder`, `tools`, `model`, `maxTokens`. Each tool:
+`{ description, input, run(input, ctx) }`.
+
+**Formats** (`format:` on output/chart/compute items): `money`, `percent`,
+`number`, `date`.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a

package/dist/index.esm.js

@@ -373,6 +373,7 @@ function seriesColors(seed, n) {
 }
 
 // src/blocks.js
+var FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
 function formatValue(value, format) {
   if (value === null || value === void 0 || value === "") return "\u2014";
   const n = Number(value);
@@ -1165,6 +1166,41 @@ Continue with this information. If you have everything you need, answer in natur
 var LAYOUTS = ["panel", "records", "steps", "chat"];
 var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
 var TOP_KEYS = ["title", "subtitle", "theme", "layout", "blocks", "records", "steps", "chat", "data", "shared"];
+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\`.`);
+    if (f.type !== void 0 && !FIELD_TYPES.includes(f.type)) {
+      throw new Error(
+        `claude-artifact-framework: field "${f.key}" in ${where} has unknown type "${f.type}". Valid types: ${FIELD_TYPES.join(", ")}.`
+      );
+    }
+  }
+}
+function checkBlocks(blocks) {
+  if (!Array.isArray(blocks)) {
+    throw new Error("claude-artifact-framework: `blocks` must be an array.");
+  }
+  blocks.forEach((block, i) => {
+    if (!block || typeof block !== "object") {
+      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));
+    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(", ")}.`
+      );
+    }
+    if (known.length > 1) {
+      throw new Error(
+        `claude-artifact-framework: blocks[${i}] declares more than one block type (${known.join(
+          ", "
+        )}). Split them into separate entries of \`blocks\`.`
+      );
+    }
+    checkFields(block.fields, `blocks[${i}]`);
+  });
+}
 function validate(spec) {
   const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
   if (unknownTop.length) {
@@ -1198,8 +1234,8 @@ function validate(spec) {
       if (!st.fields && !st.text && !st.result) {
         throw new Error(`claude-artifact-framework: steps[${i}] needs \`fields\`, \`text\`, or \`result\`.`);
       }
+      checkFields(st.fields, `steps[${i}]`);
       for (const f of st.fields || []) {
-        if (!f || !f.key) throw new Error(`claude-artifact-framework: every field in steps[${i}] needs a \`key\`.`);
         if (seen.has(f.key)) {
           throw new Error(
             `claude-artifact-framework: field key "${f.key}" appears in more than one step \u2014 keys share one data pool and must be unique.`
@@ -1246,13 +1282,14 @@ function validate(spec) {
         `claude-artifact-framework: records has unknown keys (${unknownR.join(", ")}). Valid keys: ${RECORDS_KEYS.join(", ")}.`
       );
     }
+    checkFields(r.fields, "records");
     const seen = /* @__PURE__ */ new Set();
     for (const f of r.fields) {
-      if (!f || !f.key) throw new Error("claude-artifact-framework: every records field needs a `key`.");
       if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records \u2014 the framework assigns it.');
       if (seen.has(f.key)) throw new Error(`claude-artifact-framework: duplicate records field key "${f.key}".`);
       seen.add(f.key);
     }
+    if (spec.blocks) checkBlocks(spec.blocks);
     for (const [key, c] of Object.entries(r.compute || {})) {
       if (seen.has(key) || key === "id") {
         throw new Error(
@@ -1267,29 +1304,7 @@ function validate(spec) {
     }
     return layout;
   }
-  const blocks = spec.blocks || [];
-  if (!Array.isArray(blocks)) {
-    throw new Error("claude-artifact-framework: `blocks` must be an array.");
-  }
-  blocks.forEach((block, i) => {
-    if (!block || typeof block !== "object") {
-      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));
-    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(", ")}.`
-      );
-    }
-    if (known.length > 1) {
-      throw new Error(
-        `claude-artifact-framework: blocks[${i}] declares more than one block type (${known.join(
-          ", "
-        )}). Split them into separate entries of \`blocks\`.`
-      );
-    }
-  });
+  checkBlocks(spec.blocks || []);
   return layout;
 }
 function defaultsFrom(spec) {
@@ -1353,7 +1368,26 @@ function Panel({ spec, ctx }) {
     )
   );
 }
-var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout, steps: StepsLayout, chat: ChatLayout };
+function RecordsWithBlocks({ spec, ctx }) {
+  const detailOpen = ctx.view.screen === "record" && (ctx.data.records || []).some((r) => r.id === ctx.view.arg);
+  return createElement(
+    "div",
+    null,
+    createElement(RecordsLayout, { spec, ctx }),
+    !detailOpen && Array.isArray(spec.blocks) && spec.blocks.length ? createElement(
+      "div",
+      { className: "caf-panel caf-records-blocks" },
+      spec.blocks.map(
+        (block, i) => createElement(
+          "section",
+          { key: i, className: block.wide ? "caf-slot caf-slot-wide" : "caf-slot" },
+          createElement(Block, { block, ctx })
+        )
+      )
+    ) : null
+  );
+}
+var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsWithBlocks, steps: StepsLayout, chat: ChatLayout };
 function createApp(spec = {}) {
   const layout = validate(spec);
   const state = createAppState(defaultsFrom(spec), { shared: Boolean(spec.shared) });
@@ -1516,6 +1550,7 @@ var BASE_CSS = `
 }
 .caf-search:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-computed { border-top: 1px solid var(--caf-border); padding-top: 0.7rem; }
+.caf-records-blocks { margin-top: 1rem; }
 .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); }