claude-artifact-framework 0.3.0 → 0.4.0

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,
 };
 

package/src/steps.js

@@ -0,0 +1,106 @@
+// steps.js — the wizard layout: quizzes, assessments, staged calculators,
+// long forms, onboarding.
+//
+// The author declares the sequence; next/back/progress/result are
+// framework-owned. Three rules keep it un-breakable:
+//
+//   one data pool   step fields write into the same flat `data` every other
+//                   block uses, so a result step is just a function of data —
+//                   no "collect answers" plumbing to half-build.
+//   gated next      Next is disabled while any field on the CURRENT step is
+//                   invalid; earlier steps are already valid by construction,
+//                   later ones aren't the user's problem yet.
+//   resumable       the current step lives in view state, so a reload lands
+//                   on the step the user was on, holding their answers.
+
+import { createElement as h } from "react";
+import { Field, validateField, formatValue } from "./blocks.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 h(
+    "div",
+    { className: "caf-block caf-output" },
+    step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+    h(
+      "div",
+      { className: "caf-output-grid" },
+      items.map((item, i) =>
+        h(
+          "div",
+          { key: item.label ?? i, className: item.big ? "caf-stat caf-stat-big" : "caf-stat" },
+          h("span", { className: "caf-stat-label" }, item.label),
+          h("span", { className: "caf-stat-value" }, formatValue(item.value, item.format)),
+          item.hint ? h("small", { className: "caf-hint" }, item.hint) : null
+        )
+      )
+    ),
+    h(
+      "div",
+      { className: "caf-step-nav" },
+      h("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(0) }, "Start over")
+    )
+  );
+}
+
+export 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 h(
+    "div",
+    { className: "caf-panel caf-panel-single" },
+    h(
+      "div",
+      { className: "caf-steps-progress" },
+      h("span", { className: "caf-hint" }, isResult ? "Result" : `Step ${i + 1} of ${steps.length}`),
+      h(
+        "div",
+        { className: "caf-bar-track" },
+        h("div", { className: "caf-bar-fill caf-steps-fill", style: { width: `${((i + 1) / steps.length) * 100}%` } })
+      )
+    ),
+    isResult
+      ? h(ResultScreen, { step, ctx })
+      : h(
+          "div",
+          { className: "caf-block caf-fields" },
+          step.title ? h("h2", { className: "caf-block-title" }, step.title) : null,
+          step.text ? h("p", { className: "caf-step-text" }, typeof step.text === "function" ? step.text(ctx.data) : step.text) : null,
+          (step.fields || []).map((field) =>
+            h(Field, {
+              key: field.key,
+              field,
+              value: ctx.data[field.key],
+              onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
+            })
+          ),
+          h(
+            "div",
+            { className: "caf-step-nav" },
+            i > 0
+              ? h("button", { type: "button", className: "caf-btn", onClick: () => ctx.setStep(i - 1) }, "‹ Back")
+              : h("span"),
+            !isLast
+              ? h(
+                  "button",
+                  {
+                    type: "button",
+                    className: "caf-btn caf-btn-primary",
+                    disabled: stepErrors(step, ctx.data),
+                    onClick: () => ctx.setStep(i + 1),
+                  },
+                  "Next ›"
+                )
+              : null
+          )
+        )
+  );
+}

package/src/theme.js

@@ -146,3 +146,12 @@ export function themeCss(seed) {
 :root[data-theme="light"] { ${vars(p.light)} }
 `;
 }
+
+// Categorical series colors for charts, derived from the seed by golden-angle
+// hue rotation, so any number of segments stays distinguishable. Mid-tone
+// lightness reads on both the light and dark surface.
+export 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));
+}