claude-artifact-framework 0.3.0 → 0.5.0

package/src/app.js

@@ -11,23 +11,87 @@
 
 import { createElement as h, useState, useEffect, hasReact, getReact } from "react";
 import { createAppState } from "./appState.js";
-import { themeCss } from "./theme.js";
+import { themeCss, seriesColors } from "./theme.js";
 import { BLOCKS, BLOCK_NAMES } from "./blocks.js";
 import { RecordsLayout } from "./records.js";
+import { StepsLayout } from "./steps.js";
+import { ChatLayout, CHAT_KEYS } from "./chat.js";
 
-const LAYOUTS = ["panel", "records"];
+const LAYOUTS = ["panel", "records", "steps", "chat"];
 const RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
 
 // 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"];
+
 function validate(spec) {
+  const unknownTop = Object.keys(spec).filter((k) => !TOP_KEYS.includes(k));
+  if (unknownTop.length) {
+    throw new Error(
+      `claude-artifact-framework: unknown top-level keys (${unknownTop.join(", ")}). Valid keys: ${TOP_KEYS.join(", ")}.`
+    );
+  }
   const layout = spec.layout || "panel";
   if (!LAYOUTS.includes(layout)) {
     throw new Error(
       `claude-artifact-framework: unknown layout "${layout}". Valid layouts: ${LAYOUTS.join(", ")}.`
     );
   }
+  if (layout === "steps") {
+    const steps = spec.steps;
+    if (!Array.isArray(steps) || steps.length === 0) {
+      throw new Error('claude-artifact-framework: layout "steps" needs `steps: [...]` with at least one step.');
+    }
+    const STEP_KEYS = ["title", "text", "fields", "result"];
+    const seen = new Set();
+    steps.forEach((st, i) => {
+      if (!st || typeof st !== "object") {
+        throw new Error(`claude-artifact-framework: steps[${i}] must be an object.`);
+      }
+      const unknown = Object.keys(st).filter((k) => !STEP_KEYS.includes(k));
+      if (unknown.length) {
+        throw new Error(
+          `claude-artifact-framework: steps[${i}] has unknown keys (${unknown.join(", ")}). Valid keys: ${STEP_KEYS.join(", ")}.`
+        );
+      }
+      if (!st.fields && !st.text && !st.result) {
+        throw new Error(`claude-artifact-framework: steps[${i}] needs \`fields\`, \`text\`, or \`result\`.`);
+      }
+      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 — keys share one data pool and must be unique.`
+          );
+        }
+        seen.add(f.key);
+      }
+    });
+    return layout;
+  }
+  if (layout === "chat") {
+    const c = spec.chat;
+    if (!c || (typeof c.system !== "string" && typeof c.system !== "function")) {
+      throw new Error(
+        'claude-artifact-framework: layout "chat" needs `chat: { system: "..." }` (a string or a function of data).'
+      );
+    }
+    const unknown = Object.keys(c).filter((k) => !CHAT_KEYS.includes(k));
+    if (unknown.length) {
+      throw new Error(
+        `claude-artifact-framework: chat has unknown keys (${unknown.join(", ")}). Valid keys: ${CHAT_KEYS.join(", ")}.`
+      );
+    }
+    for (const [name, tool] of Object.entries(c.tools || {})) {
+      if (!tool || typeof tool.description !== "string" || typeof tool.run !== "function") {
+        throw new Error(
+          `claude-artifact-framework: chat tool "${name}" needs a \`description\` string and a \`run(input, ctx)\` function.`
+        );
+      }
+    }
+    return layout;
+  }
   if (layout === "records") {
     const r = spec.records;
     if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
@@ -35,6 +99,13 @@ function validate(spec) {
         'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
       );
     }
+    const RECORDS_KEYS = ["label", "fields", "title", "subtitle", "sort", "summary", "empty", "search", "compute"];
+    const unknownR = Object.keys(r).filter((k) => !RECORDS_KEYS.includes(k));
+    if (unknownR.length) {
+      throw new Error(
+        `claude-artifact-framework: records has unknown keys (${unknownR.join(", ")}). Valid keys: ${RECORDS_KEYS.join(", ")}.`
+      );
+    }
     const seen = new Set();
     for (const f of r.fields) {
       if (!f || !f.key) throw new Error("claude-artifact-framework: every records field needs a `key`.");
@@ -42,6 +113,18 @@ function validate(spec) {
       if (seen.has(f.key)) throw new Error(`claude-artifact-framework: duplicate records field key "${f.key}".`);
       seen.add(f.key);
     }
+    for (const [key, c] of Object.entries(r.compute || {})) {
+      if (seen.has(key) || key === "id") {
+        throw new Error(
+          `claude-artifact-framework: compute key "${key}" collides with a field key — computed values are derived, never stored.`
+        );
+      }
+      if (typeof c !== "function" && typeof (c && c.value) !== "function") {
+        throw new Error(
+          `claude-artifact-framework: compute "${key}" must be a function of the record, or { label, format, value: (r) => ... }.`
+        );
+      }
+    }
     return layout;
   }
   const blocks = spec.blocks || [];
@@ -80,7 +163,10 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
-  for (const block of spec.blocks || []) {
+  if ((spec.layout || "panel") === "chat" && !data.chat) {
+    data.chat = { api: [], log: [] };
+  }
+  for (const block of [...(spec.blocks || []), ...(spec.steps || [])]) {
     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 : "";
@@ -140,11 +226,11 @@ function Panel({ spec, ctx }) {
   );
 }
 
-const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout };
+const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout, steps: StepsLayout, chat: ChatLayout };
 
 export function createApp(spec = {}) {
   const layout = validate(spec);
-  const state = createAppState(defaultsFrom(spec));
+  const state = createAppState(defaultsFrom(spec), { shared: Boolean(spec.shared) });
   const css = themeCss(spec.theme && spec.theme.seed) + BASE_CSS;
 
   return function App() {
@@ -172,6 +258,8 @@ export function createApp(spec = {}) {
       update: state.update,
       go: state.go,
       back: state.back,
+      setStep: (n) => state.setView({ step: n }),
+      colors: (n) => seriesColors(spec.theme && spec.theme.seed, n),
     };
 
     const Layout = LAYOUT_COMPONENTS[layout];
@@ -264,6 +352,56 @@ const BASE_CSS = `
 .caf-btn:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
 .caf-btn-primary { background: var(--caf-accent); border-color: var(--caf-accent); color: var(--caf-accentText); }
 .caf-btn-danger { background: transparent; border-color: var(--caf-danger); color: var(--caf-danger); }
+.caf-bars { display: flex; flex-direction: column; gap: 0.55rem; }
+.caf-bar-row { display: grid; grid-template-columns: minmax(60px, 30%) 1fr auto; align-items: center; gap: 0.6rem; }
+.caf-bar-label { font-size: 0.82rem; color: var(--caf-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.caf-bar-track { height: 8px; border-radius: 4px; background: var(--caf-sunken); overflow: hidden; }
+.caf-bar-fill { height: 100%; border-radius: 4px; background: var(--caf-accent); }
+.caf-bar-value { font-size: 0.82rem; font-weight: 600; font-variant-numeric: tabular-nums; }
+.caf-line-svg { width: 100%; height: 110px; display: block; }
+.caf-line-grid { stroke: var(--caf-border); stroke-width: 0.3; }
+.caf-line-path { fill: none; stroke: var(--caf-accent); stroke-width: 1.1; stroke-linejoin: round; stroke-linecap: round; }
+.caf-line-dot { fill: var(--caf-accent); }
+.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); }
+.caf-donut-seg { fill: none; stroke-width: 6; }
+.caf-donut-legend { display: flex; flex-direction: column; gap: 0.4rem; min-width: 0; flex: 1; }
+.caf-legend-row { display: flex; align-items: center; gap: 0.5rem; font-size: 0.84rem; }
+.caf-legend-swatch { width: 10px; height: 10px; border-radius: 3px; flex: none; }
+.caf-legend-label { color: var(--caf-muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.caf-legend-value { margin-left: auto; font-weight: 600; font-variant-numeric: tabular-nums; }
+.caf-timer { align-items: center; text-align: center; }
+.caf-timer .caf-bar-track { width: 100%; }
+.caf-timer-time { font-size: 2.6rem; font-weight: 700; font-variant-numeric: tabular-nums; letter-spacing: 0.02em; }
+.caf-timer-done { color: var(--caf-accent); }
+.caf-timer-fill { transition: width 0.9s linear; }
+.caf-timer-controls { display: flex; gap: 0.6rem; }
+.caf-btn:disabled { opacity: 0.45; cursor: not-allowed; }
+.caf-steps-progress { display: flex; flex-direction: column; gap: 0.35rem; margin-bottom: 0.2rem; }
+.caf-steps-fill { transition: width 0.25s ease; }
+.caf-step-text { margin: 0; color: var(--caf-muted); font-size: 0.92rem; line-height: 1.55; }
+.caf-step-nav { display: flex; justify-content: space-between; gap: 0.6rem; margin-top: 0.4rem; }
+.caf-chat-log { min-height: 320px; max-height: 62vh; overflow-y: auto; gap: 0.55rem; }
+.caf-msg { max-width: 85%; padding: 0.55rem 0.75rem; border-radius: 12px; font-size: 0.92rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word; }
+.caf-msg-user { align-self: flex-end; background: var(--caf-accent); color: var(--caf-accentText); border-bottom-right-radius: 4px; }
+.caf-msg-assistant { align-self: flex-start; background: var(--caf-sunken); border-bottom-left-radius: 4px; }
+.caf-msg-live::after { content: "▍"; opacity: 0.6; }
+.caf-msg-tools { align-self: flex-start; font-size: 0.74rem; color: var(--caf-muted); padding: 0.15rem 0.55rem; border: 1px solid var(--caf-border); border-radius: 999px; }
+.caf-msg-error { align-self: stretch; max-width: none; display: flex; flex-direction: column; gap: 0.2rem; background: transparent; border: 1px solid var(--caf-danger); }
+.caf-msg-error strong { color: var(--caf-danger); font-size: 0.85rem; }
+.caf-chat-input { display: flex; gap: 0.6rem; margin-top: 0.8rem; }
+.caf-chat-input input { flex: 1; font: inherit; font-size: 0.95rem; padding: 0.55rem 0.7rem; border-radius: 8px; border: 1px solid var(--caf-border); background: var(--caf-surface); color: var(--caf-text); }
+.caf-chat-input input:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
+.caf-search {
+  font: inherit; font-size: 0.9rem; width: 100%;
+  padding: 0.5rem 0.65rem; margin: 0 0 0.3rem;
+  border-radius: 7px; border: 1px solid var(--caf-border);
+  background: var(--caf-sunken); color: var(--caf-text);
+}
+.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-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); }

package/src/appState.js

@@ -44,10 +44,20 @@ function debounce(fn, ms) {
   };
 }
 
-export function createAppState(defaults, { debounceMs = 400 } = {}) {
+// With `shared: true` the DATA pool lives in the shared storage scope, so
+// every viewer of a published artifact converges on the same data (polled,
+// last-write-wins). View state — navigation, selection, the open record —
+// stays personal ALWAYS: two people looking at the same list should not
+// fight over which screen is open.
+export function createAppState(defaults, { debounceMs = 400, shared = false, pollMs = 2500 } = {}) {
+  const dataStore = shared ? storage.shared : storage;
   let data = structuredCloneish(defaults);
   let view = { ...EMPTY_VIEW };
   let hydrated = false;
+  // Counts update() calls so a poll never overwrites edits that haven't been
+  // persisted yet: remote state only applies when we owe storage nothing.
+  let writes = 0;
+  let persistedWrites = 0;
   const listeners = new Set();
 
   // Notification is batched to a microtask: three mutations in a row produce
@@ -63,12 +73,32 @@ export function createAppState(defaults, { debounceMs = 400 } = {}) {
     });
   }
 
-  const persistData = debounce(() => storage.set(DATA_KEY, data), debounceMs);
+  const persistData = debounce(() => {
+    const at = writes;
+    Promise.resolve(dataStore.set(DATA_KEY, data)).then(() => {
+      persistedWrites = Math.max(persistedWrites, at);
+    }).catch(() => {});
+  }, debounceMs);
   const persistView = debounce(() => storage.set(VIEW_KEY, view), debounceMs);
 
+  if (shared) {
+    setInterval(async () => {
+      if (!hydrated || writes > persistedWrites) return; // local edits in flight win
+      try {
+        const remote = await dataStore.get(DATA_KEY, undefined);
+        if (remote !== undefined && JSON.stringify(remote) !== JSON.stringify(data)) {
+          data = mergeDefaults(defaults, remote);
+          notify();
+        }
+      } catch {
+        // a failed poll just means we try again next tick
+      }
+    }, pollMs);
+  }
+
   const ready = (async () => {
     const [storedData, storedView] = await Promise.all([
-      storage.get(DATA_KEY, undefined),
+      dataStore.get(DATA_KEY, undefined),
       storage.get(VIEW_KEY, undefined),
     ]);
     if (storedData !== undefined) data = mergeDefaults(defaults, storedData);
@@ -82,6 +112,7 @@ export function createAppState(defaults, { debounceMs = 400 } = {}) {
     // Handlers may either mutate the draft or return a replacement.
     if (result !== undefined) data = result;
     data = { ...data };
+    writes++;
     persistData();
     notify();
   }

package/src/blocks.js

@@ -10,7 +10,7 @@
 
 // Bound lazily rather than snapshotted as `React.createElement`, because this
 // runs at module load — before the host has had a chance to hand React over.
-import { createElement as h } from "react";
+import { createElement as h, useState, useEffect } from "react";
 
 const FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
 
@@ -158,8 +158,8 @@ export function OutputBlock({ spec, ctx }) {
   );
 }
 
-export function TextBlock({ spec }) {
-  const body = typeof spec.text === "function" ? spec.text() : spec.text;
+export function TextBlock({ spec, ctx }) {
+  const body = typeof spec.text === "function" ? spec.text(ctx.data) : spec.text;
   return h(
     "div",
     { className: "caf-block caf-text" },
@@ -193,6 +193,178 @@ export function ListBlock({ spec, ctx }) {
   );
 }
 
+const CHART_TYPES = ["bar", "line", "donut"];
+
+// Charts share the output block's vocabulary — items of { label, value } plus
+// an optional format — so declaring one teaches nothing new. Colors come from
+// ctx.colors(n), derived from the theme seed, so a chart can't clash with the
+// app it lives in.
+export function ChartBlock({ spec, ctx }) {
+  const c = typeof spec.chart === "function" ? spec.chart(ctx.data) : spec.chart;
+  const items = (c && c.items) || [];
+  if (!items.length) {
+    return h("div", { className: "caf-block caf-empty" }, spec.empty || "No data to chart yet.");
+  }
+  const type = c.type || "bar";
+  if (!CHART_TYPES.includes(type)) {
+    // Thrown, not swallowed: the block boundary turns this into a visible,
+    // named error instead of an empty pane.
+    throw new Error(`unknown chart type "${type}". Valid types: ${CHART_TYPES.join(", ")}.`);
+  }
+  const colors = ctx.colors(items.length);
+  const body =
+    type === "bar" ? barChart(items, c, colors) : type === "line" ? lineChart(items, c) : donutChart(items, c, colors);
+  return h(
+    "div",
+    { className: "caf-block caf-chart" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    body
+  );
+}
+
+function barChart(items, c, colors) {
+  const max = Math.max(...items.map((it) => Number(it.value) || 0), 0) || 1;
+  return h(
+    "div",
+    { className: "caf-bars" },
+    items.map((it, i) =>
+      h(
+        "div",
+        { key: it.label ?? i, className: "caf-bar-row" },
+        h("span", { className: "caf-bar-label" }, it.label),
+        h(
+          "div",
+          { className: "caf-bar-track" },
+          h("div", {
+            className: "caf-bar-fill",
+            style: { width: `${Math.max(2, ((Number(it.value) || 0) / max) * 100)}%`, background: colors[i] },
+          })
+        ),
+        h("span", { className: "caf-bar-value" }, formatValue(it.value, c.format))
+      )
+    )
+  );
+}
+
+function lineChart(items, c) {
+  const values = items.map((it) => Number(it.value) || 0);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const span = max - min || 1;
+  const W = 100;
+  const H = 36;
+  const pts = values.map((v, i) => [
+    values.length === 1 ? W / 2 : (i / (values.length - 1)) * W,
+    H - 3 - ((v - min) / span) * (H - 6),
+  ]);
+  const last = pts[pts.length - 1];
+  return h(
+    "div",
+    { className: "caf-line" },
+    h(
+      "svg",
+      { viewBox: `0 0 ${W} ${H}`, className: "caf-line-svg", preserveAspectRatio: "none", "aria-hidden": "true" },
+      [0.25, 0.5, 0.75].map((f) =>
+        h("line", { key: f, x1: 0, x2: W, y1: H * f, y2: H * f, className: "caf-line-grid" })
+      ),
+      h("polyline", { points: pts.map((p) => p.join(",")).join(" "), className: "caf-line-path" }),
+      h("circle", { cx: last[0], cy: last[1], r: 1.6, className: "caf-line-dot" })
+    ),
+    h(
+      "div",
+      { className: "caf-line-meta" },
+      h("span", { className: "caf-hint" }, String(items[0].label ?? "")),
+      h("span", { className: "caf-line-last" }, formatValue(values[values.length - 1], c.format)),
+      h("span", { className: "caf-hint" }, String(items[items.length - 1].label ?? ""))
+    )
+  );
+}
+
+function donutChart(items, c, colors) {
+  const total = items.reduce((s, it) => s + (Number(it.value) || 0), 0) || 1;
+  const R = 15.9155; // circumference ≈ 100, so dash lengths are percentages
+  let offset = 25;   // start at 12 o'clock
+  const segments = items.map((it, i) => {
+    const pct = ((Number(it.value) || 0) / total) * 100;
+    const seg = h("circle", {
+      key: it.label ?? i,
+      cx: 21, cy: 21, r: R,
+      className: "caf-donut-seg",
+      stroke: colors[i],
+      strokeDasharray: `${pct} ${100 - pct}`,
+      strokeDashoffset: offset,
+    });
+    offset -= pct;
+    return seg;
+  });
+  return h(
+    "div",
+    { className: "caf-donut" },
+    h("svg", { viewBox: "0 0 42 42", className: "caf-donut-svg", "aria-hidden": "true" }, segments),
+    h(
+      "div",
+      { className: "caf-donut-legend" },
+      items.map((it, i) =>
+        h(
+          "div",
+          { key: it.label ?? i, className: "caf-legend-row" },
+          h("span", { className: "caf-legend-swatch", style: { background: colors[i] } }),
+          h("span", { className: "caf-legend-label" }, it.label),
+          h("span", { className: "caf-legend-value" }, formatValue(it.value, c.format))
+        )
+      )
+    )
+  );
+}
+
+// The interval is framework-owned and cleaned up on unmount — a leaked
+// setInterval is one of the classic half-built artifact bugs. The countdown
+// itself is deliberately ephemeral (local state); what the author declares is
+// what happens WHEN it finishes: onDone runs through update(), so its effects
+// persist like any other change.
+export function TimerBlock({ spec, ctx }) {
+  const t = spec.timer || {};
+  const total = Math.max(1, Math.round((t.minutes || 0) * 60 + (t.seconds || 0)) || 300);
+  const [left, setLeft] = useState(total);
+  const [running, setRunning] = useState(false);
+
+  useEffect(() => {
+    if (!running) return;
+    const id = setInterval(() => setLeft((prev) => Math.max(0, prev - 1)), 1000);
+    return () => clearInterval(id);
+  }, [running]);
+
+  useEffect(() => {
+    if (left === 0 && running) {
+      setRunning(false);
+      if (typeof t.onDone === "function") ctx.update((d) => t.onDone(d));
+    }
+  }, [left, running]);
+
+  const mm = String(Math.floor(left / 60)).padStart(2, "0");
+  const ss = String(left % 60).padStart(2, "0");
+  const done = left === 0;
+
+  return h(
+    "div",
+    { className: "caf-block caf-timer" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    t.label ? h("span", { className: "caf-hint" }, t.label) : null,
+    h("div", { className: done ? "caf-timer-time caf-timer-done" : "caf-timer-time" }, done ? (t.doneText || "Done!") : `${mm}:${ss}`),
+    h("div", { className: "caf-bar-track" }, h("div", { className: "caf-bar-fill caf-timer-fill", style: { width: `${(left / total) * 100}%` } })),
+    h(
+      "div",
+      { className: "caf-timer-controls" },
+      h(
+        "button",
+        { type: "button", className: "caf-btn caf-btn-primary", disabled: done, onClick: () => setRunning((r) => !r) },
+        running ? "Pause" : "Start"
+      ),
+      h("button", { type: "button", className: "caf-btn", onClick: () => { setRunning(false); setLeft(total); } }, "Reset")
+    )
+  );
+}
+
 // The escape hatch. Receives the same ctx every built-in block gets, so a
 // custom block keeps persistence, theming, navigation and the error boundary.
 export function CustomBlock({ spec, ctx }) {
@@ -208,6 +380,8 @@ export const BLOCKS = {
   output: OutputBlock,
   text: TextBlock,
   list: ListBlock,
+  chart: ChartBlock,
+  timer: TimerBlock,
   custom: CustomBlock,
 };