claude-artifact-framework 0.3.0 → 0.4.0

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.3.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.4.0/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.3.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.4.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.3.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.4.0`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
 ### Inside a React artifact
@@ -123,6 +123,58 @@ persistence path as everything else. `id` is assigned by the framework and
 reserved. Optional: `title(r)` / `subtitle(r)` for rows, `sort(a, b)`,
 `summary(records)` for stats above the list, `empty` for the empty-state text.
 
+### The `steps` layout — wizards, quizzes, staged calculators
+
+Declare the sequence; next/back/progress/result are framework-owned. Step
+fields write into the same flat `data` pool, so the result step is just a
+function of data. Next is gated on the current step's validation; the current
+step survives a reload.
+
+```js
+ArtifactKit.createApp({
+  title: "Quiz de riesgo",
+  layout: "steps",
+  steps: [
+    { title: "Tu edad",   fields: [{ key: "edad", type: "number", required: true, min: 18 }] },
+    { title: "Tu perfil", fields: [{ key: "perfil", type: "select", required: true, options: ["conservador", "moderado", "agresivo"] }] },
+    { title: "Resultado", result: (d) => [{ label: "Puntaje", value: score(d), big: true }] },
+  ],
+});
+```
+
+Field keys must be unique across all steps (they share one data pool); a
+duplicate throws at creation, as does an unknown step key.
+
+### The `chart` block — bar, line, donut
+
+Same vocabulary as `output` (items of `{ label, value }` plus an optional
+`format`), so declaring one teaches nothing new. Colors derive from the theme
+seed by golden-angle rotation — a chart can't clash with the app it lives in.
+
+```js
+blocks: [
+  { chart: (d) => ({ type: "bar", format: "money", items: monthlyTotals(d) }), title: "Ventas", wide: true },
+  { chart: { type: "donut", items: [{ label: "Comida", value: 45 }, { label: "Otros", value: 55 }] } },
+]
+```
+
+### The `timer` block — countdowns that persist their effects
+
+The interval is framework-owned and cleaned up on unmount (a leaked
+`setInterval` is a classic half-built artifact bug). The countdown itself is
+deliberately ephemeral; what you declare is what happens when it finishes —
+`onDone` runs through `update()`, so its effects persist like any other change.
+
+```js
+blocks: [
+  { timer: { minutes: 25, label: "Focus", onDone: (d) => { d.completados = (d.completados || 0) + 1; } } },
+  { output: (d) => [{ label: "Pomodoros", value: d.completados || 0, big: true }] },
+]
+```
+
+`text` blocks also accept a function of data — `{ text: (d) => "Hola " + d.nombre }` —
+with the same contract as `output`.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a

package/dist/index.esm.js

@@ -342,6 +342,11 @@ function themeCss(seed) {
 :root[data-theme="light"] { ${vars(p.light)} }
 `;
 }
+function seriesColors(seed, n) {
+  const [h0, s0] = rgbToHsl(hexToRgb(seed || "#3b6ef6"));
+  const s = clamp(s0, 45, 70);
+  return Array.from({ length: n }, (_, i) => hsl((h0 + i * 137.5) % 360, s, 52));
+}
 
 // src/blocks.js
 function formatValue(value, format) {
@@ -476,8 +481,8 @@ function OutputBlock({ spec, ctx }) {
     )
   );
 }
-function TextBlock({ spec }) {
-  const body = typeof spec.text === "function" ? spec.text() : spec.text;
+function TextBlock({ spec, ctx }) {
+  const body = typeof spec.text === "function" ? spec.text(ctx.data) : spec.text;
   return createElement(
     "div",
     { className: "caf-block caf-text" },
@@ -509,6 +514,161 @@ function ListBlock({ spec, ctx }) {
     )
   );
 }
+var CHART_TYPES = ["bar", "line", "donut"];
+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 createElement("div", { className: "caf-block caf-empty" }, spec.empty || "No data to chart yet.");
+  }
+  const type = c.type || "bar";
+  if (!CHART_TYPES.includes(type)) {
+    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 createElement(
+    "div",
+    { className: "caf-block caf-chart" },
+    spec.title ? createElement("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 createElement(
+    "div",
+    { className: "caf-bars" },
+    items.map(
+      (it, i) => createElement(
+        "div",
+        { key: it.label ?? i, className: "caf-bar-row" },
+        createElement("span", { className: "caf-bar-label" }, it.label),
+        createElement(
+          "div",
+          { className: "caf-bar-track" },
+          createElement("div", {
+            className: "caf-bar-fill",
+            style: { width: `${Math.max(2, (Number(it.value) || 0) / max * 100)}%`, background: colors[i] }
+          })
+        ),
+        createElement("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 createElement(
+    "div",
+    { className: "caf-line" },
+    createElement(
+      "svg",
+      { viewBox: `0 0 ${W} ${H}`, className: "caf-line-svg", preserveAspectRatio: "none", "aria-hidden": "true" },
+      [0.25, 0.5, 0.75].map(
+        (f) => createElement("line", { key: f, x1: 0, x2: W, y1: H * f, y2: H * f, className: "caf-line-grid" })
+      ),
+      createElement("polyline", { points: pts.map((p) => p.join(",")).join(" "), className: "caf-line-path" }),
+      createElement("circle", { cx: last[0], cy: last[1], r: 1.6, className: "caf-line-dot" })
+    ),
+    createElement(
+      "div",
+      { className: "caf-line-meta" },
+      createElement("span", { className: "caf-hint" }, String(items[0].label ?? "")),
+      createElement("span", { className: "caf-line-last" }, formatValue(values[values.length - 1], c.format)),
+      createElement("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;
+  let offset = 25;
+  const segments = items.map((it, i) => {
+    const pct = (Number(it.value) || 0) / total * 100;
+    const seg = createElement("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 createElement(
+    "div",
+    { className: "caf-donut" },
+    createElement("svg", { viewBox: "0 0 42 42", className: "caf-donut-svg", "aria-hidden": "true" }, segments),
+    createElement(
+      "div",
+      { className: "caf-donut-legend" },
+      items.map(
+        (it, i) => createElement(
+          "div",
+          { key: it.label ?? i, className: "caf-legend-row" },
+          createElement("span", { className: "caf-legend-swatch", style: { background: colors[i] } }),
+          createElement("span", { className: "caf-legend-label" }, it.label),
+          createElement("span", { className: "caf-legend-value" }, formatValue(it.value, c.format))
+        )
+      )
+    )
+  );
+}
+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)), 1e3);
+    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 createElement(
+    "div",
+    { className: "caf-block caf-timer" },
+    spec.title ? createElement("h2", { className: "caf-block-title" }, spec.title) : null,
+    t.label ? createElement("span", { className: "caf-hint" }, t.label) : null,
+    createElement("div", { className: done ? "caf-timer-time caf-timer-done" : "caf-timer-time" }, done ? t.doneText || "Done!" : `${mm}:${ss}`),
+    createElement("div", { className: "caf-bar-track" }, createElement("div", { className: "caf-bar-fill caf-timer-fill", style: { width: `${left / total * 100}%` } })),
+    createElement(
+      "div",
+      { className: "caf-timer-controls" },
+      createElement(
+        "button",
+        { type: "button", className: "caf-btn caf-btn-primary", disabled: done, onClick: () => setRunning((r) => !r) },
+        running ? "Pause" : "Start"
+      ),
+      createElement("button", { type: "button", className: "caf-btn", onClick: () => {
+        setRunning(false);
+        setLeft(total);
+      } }, "Reset")
+    )
+  );
+}
 function CustomBlock({ spec, ctx }) {
   const rendered = spec.custom(ctx);
   if (typeof rendered === "string") {
@@ -521,6 +681,8 @@ var BLOCKS = {
   output: OutputBlock,
   text: TextBlock,
   list: ListBlock,
+  chart: ChartBlock,
+  timer: TimerBlock,
   custom: CustomBlock
 };
 var BLOCK_NAMES = Object.keys(BLOCKS);
@@ -644,8 +806,91 @@ function RecordsLayout({ spec, ctx }) {
   );
 }
 
+// src/steps.js
+function stepErrors(step, data) {
+  return (step.fields || []).some((f) => validateField(f, data[f.key]) !== null);
+}
+function ResultScreen({ step, ctx }) {
+  const items = step.result(ctx.data) || [];
+  return createElement(
+    "div",
+    { className: "caf-block caf-output" },
+    step.title ? createElement("h2", { className: "caf-block-title" }, step.title) : null,
+    createElement(
+      "div",
+      { className: "caf-output-grid" },
+      items.map(
+        (item, i) => createElement(
+          "div",
+          { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
+          createElement("span", { className: "caf-stat-label" }, item.label),
+          createElement("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+          item.hint ? createElement("small", { className: "caf-hint" }, item.hint) : null
+        )
+      )
+    ),
+    createElement(
+      "div",
+      { className: "caf-step-nav" },
+      createElement("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(0) }, "Start over")
+    )
+  );
+}
+function StepsLayout({ spec, ctx }) {
+  const steps = spec.steps;
+  const i = Math.min(Math.max(ctx.view.step || 0, 0), steps.length - 1);
+  const step = steps[i];
+  const isResult = typeof step.result === "function";
+  const isLast = i === steps.length - 1;
+  return createElement(
+    "div",
+    { className: "caf-panel caf-panel-single" },
+    createElement(
+      "div",
+      { className: "caf-steps-progress" },
+      createElement("span", { className: "caf-hint" }, isResult ? "Result" : `Step ${i + 1} of ${steps.length}`),
+      createElement(
+        "div",
+        { className: "caf-bar-track" },
+        createElement("div", { className: "caf-bar-fill caf-steps-fill", style: { width: `${(i + 1) / steps.length * 100}%` } })
+      )
+    ),
+    isResult ? createElement(ResultScreen, { step, ctx }) : createElement(
+      "div",
+      { className: "caf-block caf-fields" },
+      step.title ? createElement("h2", { className: "caf-block-title" }, step.title) : null,
+      step.text ? createElement("p", { className: "caf-step-text" }, typeof step.text === "function" ? step.text(ctx.data) : step.text) : null,
+      (step.fields || []).map(
+        (field) => createElement(Field, {
+          key: field.key,
+          field,
+          value: ctx.data[field.key],
+          onChange: (v) => ctx.update((d) => {
+            d[field.key] = v;
+          })
+        })
+      ),
+      createElement(
+        "div",
+        { className: "caf-step-nav" },
+        i > 0 ? createElement("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(i - 1) }, "\u2039 Back") : createElement("span"),
+        !isLast ? createElement(
+          "button",
+          {
+            type: "button",
+            className: "caf-btn caf-btn-primary",
+            disabled: stepErrors(step, ctx.data),
+            onClick: () => ctx.setStep(i + 1)
+          },
+          "Next \u203A"
+        ) : null
+      )
+    )
+  );
+}
+
 // src/app.js
-var LAYOUTS = ["panel", "records"];
+var LAYOUTS = ["panel", "records", "steps"];
 var RESERVED = ["title", "empty", "wide", "onSelect", "subtitle"];
 function validate(spec) {
   const layout = spec.layout || "panel";
@@ -654,6 +899,38 @@ function validate(spec) {
       `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 = /* @__PURE__ */ 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 \u2014 keys share one data pool and must be unique.`
+          );
+        }
+        seen.add(f.key);
+      }
+    });
+    return layout;
+  }
   if (layout === "records") {
     const r = spec.records;
     if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
@@ -700,7 +977,7 @@ function defaultsFrom(spec) {
   if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
     data.records = [];
   }
-  for (const block of spec.blocks || []) {
+  for (const block of [...spec.blocks || [], ...spec.steps || []]) {
     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 : "";
@@ -753,7 +1030,7 @@ function Panel({ spec, ctx }) {
     )
   );
 }
-var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout };
+var LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout, steps: StepsLayout };
 function createApp(spec = {}) {
   const layout = validate(spec);
   const state = createAppState(defaultsFrom(spec));
@@ -776,7 +1053,9 @@ function createApp(spec = {}) {
       view: state.getView(),
       update: state.update,
       go: state.go,
-      back: state.back
+      back: state.back,
+      setStep: (n) => state.setView({ step: n }),
+      colors: (n) => seriesColors(spec.theme && spec.theme.seed, n)
     };
     const Layout = LAYOUT_COMPONENTS[layout];
     return createElement(
@@ -864,6 +1143,37 @@ var 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-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); }