claude-artifact-framework 0.2.1 → 0.4.0

package/src/appState.js

@@ -0,0 +1,127 @@
+// appState.js — the store behind createApp.
+//
+// Two states, and the split is the point:
+//   data  domain data only. Declared by the author, persisted whole in one write.
+//   view  navigation stack, selection, current step, form drafts, pending flags.
+//         Owned by the framework, persisted under its own key, never declared
+//         and never seen by the author.
+//
+// That split is why `data` needs no zones or transient markers: nothing that
+// would be wrong to restore (an open modal, a half-typed draft) ever lives in
+// it. It also removes every storage key as an invention point — the author
+// never names one.
+
+import { storage } from "./storage.js";
+
+const DATA_KEY = "caf:data";
+const VIEW_KEY = "caf:view";
+
+const EMPTY_VIEW = { screen: null, arg: null, stack: [], step: 0, selected: null };
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+// Stored values win, but only where they exist. A field the author added
+// after data was already saved simply falls through to its declared default,
+// which is what makes additive edits need no migration at all.
+function mergeDefaults(defaults, stored) {
+  if (!isPlainObject(defaults) || !isPlainObject(stored)) {
+    return stored === undefined ? defaults : stored;
+  }
+  const out = { ...defaults };
+  for (const key of Object.keys(stored)) {
+    out[key] = isPlainObject(defaults[key]) ? mergeDefaults(defaults[key], stored[key]) : stored[key];
+  }
+  return out;
+}
+
+function debounce(fn, ms) {
+  let timer;
+  return (...args) => {
+    clearTimeout(timer);
+    timer = setTimeout(() => fn(...args), ms);
+  };
+}
+
+export function createAppState(defaults, { debounceMs = 400 } = {}) {
+  let data = structuredCloneish(defaults);
+  let view = { ...EMPTY_VIEW };
+  let hydrated = false;
+  const listeners = new Set();
+
+  // Notification is batched to a microtask: three mutations in a row produce
+  // one render, not three. Persistence is separately debounced, because
+  // writing to window.storage is async and must not run at typing speed.
+  let queued = false;
+  function notify() {
+    if (queued) return;
+    queued = true;
+    Promise.resolve().then(() => {
+      queued = false;
+      for (const fn of listeners) fn();
+    });
+  }
+
+  const persistData = debounce(() => storage.set(DATA_KEY, data), debounceMs);
+  const persistView = debounce(() => storage.set(VIEW_KEY, view), debounceMs);
+
+  const ready = (async () => {
+    const [storedData, storedView] = await Promise.all([
+      storage.get(DATA_KEY, undefined),
+      storage.get(VIEW_KEY, undefined),
+    ]);
+    if (storedData !== undefined) data = mergeDefaults(defaults, storedData);
+    if (storedView !== undefined) view = { ...EMPTY_VIEW, ...storedView };
+    hydrated = true;
+    notify();
+  })();
+
+  function update(fn) {
+    const result = fn(data);
+    // Handlers may either mutate the draft or return a replacement.
+    if (result !== undefined) data = result;
+    data = { ...data };
+    persistData();
+    notify();
+  }
+
+  function setView(patch) {
+    view = { ...view, ...patch };
+    persistView();
+    notify();
+  }
+
+  return {
+    ready,
+    isHydrated: () => hydrated,
+    getData: () => data,
+    getView: () => view,
+    update,
+    setView,
+    go(screen, arg) {
+      setView({ stack: [...view.stack, { screen: view.screen, arg: view.arg }], screen, arg });
+    },
+    back() {
+      const stack = view.stack.slice();
+      const previous = stack.pop() || { screen: null, arg: null };
+      setView({ stack, screen: previous.screen, arg: previous.arg });
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+  };
+}
+
+// Defaults come from a literal in the declaration; a shallow structural copy
+// is enough and avoids depending on structuredClone being present.
+function structuredCloneish(value) {
+  if (Array.isArray(value)) return value.map(structuredCloneish);
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = structuredCloneish(value[k]);
+    return out;
+  }
+  return value;
+}

package/src/blocks.js

@@ -0,0 +1,389 @@
+// blocks.js — the content blocks that fill a layout's slots.
+//
+// Every block is a plain React component taking (spec, ctx). Custom code from
+// the escape hatch implements exactly the same contract, which is why ejecting
+// one block never requires ejecting the app.
+//
+// Loading / empty / error are part of the contract rather than edge cases the
+// author opts into: a block that has nothing to show says so by default, so an
+// app can't ship a blank pane while it waits.
+
+// 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, useState, useEffect } from "react";
+
+const FIELD_TYPES = ["text", "textarea", "number", "money", "percent", "check", "date", "select"];
+
+export function formatValue(value, format) {
+  if (value === null || value === undefined || value === "") return "—";
+  const n = Number(value);
+  switch (format) {
+    case "money":
+      return Number.isFinite(n)
+        ? n.toLocaleString(undefined, { style: "currency", currency: "USD", maximumFractionDigits: 2 })
+        : String(value);
+    case "percent":
+      return Number.isFinite(n) ? `${n.toLocaleString(undefined, { maximumFractionDigits: 2 })}%` : String(value);
+    case "number":
+      return Number.isFinite(n) ? n.toLocaleString(undefined, { maximumFractionDigits: 2 }) : String(value);
+    case "date":
+      return value instanceof Date ? value.toLocaleDateString() : String(value);
+    default:
+      return String(value);
+  }
+}
+
+// Validation is derived from the field declaration, so the author gets it
+// without writing any: declaring a type and a range IS the validation.
+export function validateField(field, value) {
+  if (field.required && (value === "" || value === null || value === undefined)) {
+    return "Required";
+  }
+  if (value === "" || value === null || value === undefined) return null;
+  if (field.type === "number" || field.type === "money" || field.type === "percent") {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return "Must be a number";
+    if (field.min !== undefined && n < field.min) return `Must be at least ${field.min}`;
+    if (field.max !== undefined && n > field.max) return `Must be at most ${field.max}`;
+  }
+  return null;
+}
+
+export function Field({ field, value, onChange }) {
+  const error = validateField(field, value);
+  const id = `caf-f-${field.key}`;
+  const numeric = field.type === "number" || field.type === "money" || field.type === "percent";
+
+  if (field.type === "check") {
+    return h(
+      "label",
+      { className: "caf-check" },
+      h("input", {
+        id,
+        type: "checkbox",
+        checked: Boolean(value),
+        onChange: (e) => onChange(e.target.checked),
+      }),
+      h("span", null, field.label || field.key)
+    );
+  }
+
+  const common = {
+    id,
+    value: value === null || value === undefined ? "" : value,
+    "aria-invalid": error ? "true" : undefined,
+    onChange: (e) => onChange(numeric ? toNumber(e.target.value) : e.target.value),
+  };
+
+  let control;
+  if (field.type === "textarea") {
+    control = h("textarea", { ...common, rows: field.rows || 3 });
+  } else if (field.type === "select") {
+    control = h(
+      "select",
+      common,
+      h("option", { value: "" }, field.placeholder || "Select…"),
+      (field.options || []).map((opt) => {
+        const val = typeof opt === "string" ? opt : opt.value;
+        const label = typeof opt === "string" ? opt : opt.label;
+        return h("option", { key: val, value: val }, label);
+      })
+    );
+  } else {
+    control = h("input", {
+      ...common,
+      type: field.type === "date" ? "date" : numeric ? "number" : "text",
+      min: field.min,
+      max: field.max,
+      step: field.step || (field.type === "money" || field.type === "percent" ? "any" : undefined),
+      placeholder: field.placeholder,
+    });
+  }
+
+  return h(
+    "div",
+    { className: "caf-field" },
+    h("label", { htmlFor: id }, field.label || field.key),
+    control,
+    field.hint && !error ? h("small", { className: "caf-hint" }, field.hint) : null,
+    error ? h("small", { className: "caf-error" }, error) : null
+  );
+}
+
+function toNumber(raw) {
+  if (raw === "") return "";
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
+
+export function FieldsBlock({ spec, ctx }) {
+  const fields = spec.fields || [];
+  return h(
+    "div",
+    { className: "caf-block caf-fields" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    fields.map((field) =>
+      h(Field, {
+        key: field.key,
+        field,
+        value: ctx.data[field.key],
+        onChange: (v) => ctx.update((d) => { d[field.key] = v; }),
+      })
+    )
+  );
+}
+
+export function OutputBlock({ spec, ctx }) {
+  const items = typeof spec.output === "function" ? spec.output(ctx.data) : spec.output || [];
+  if (!items.length) {
+    return h("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing to show yet.");
+  }
+  return h(
+    "div",
+    { className: "caf-block caf-output" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.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
+        )
+      )
+    )
+  );
+}
+
+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" },
+    spec.title ? h("h2", { className: "caf-block-title" }, spec.title) : null,
+    h("p", null, body)
+  );
+}
+
+export function ListBlock({ spec, ctx }) {
+  const rows = (typeof spec.list === "function" ? spec.list(ctx.data) : spec.list) || [];
+  if (!rows.length) {
+    return h("div", { className: "caf-block caf-empty" }, spec.empty || "Nothing here yet.");
+  }
+  const title = spec.title || ((r) => r.title ?? r.name ?? r.label ?? String(r));
+  return h(
+    "div",
+    { className: "caf-block caf-list" },
+    rows.map((row, i) =>
+      h(
+        "button",
+        {
+          key: row.id ?? i,
+          className: "caf-row",
+          type: "button",
+          onClick: spec.onSelect ? () => spec.onSelect(row, ctx) : undefined,
+        },
+        h("span", { className: "caf-row-title" }, title(row)),
+        spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(row)) : null
+      )
+    )
+  );
+}
+
+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 }) {
+  const rendered = spec.custom(ctx);
+  if (typeof rendered === "string") {
+    return h("div", { className: "caf-block", dangerouslySetInnerHTML: { __html: rendered } });
+  }
+  return h("div", { className: "caf-block" }, rendered);
+}
+
+export const BLOCKS = {
+  fields: FieldsBlock,
+  output: OutputBlock,
+  text: TextBlock,
+  list: ListBlock,
+  chart: ChartBlock,
+  timer: TimerBlock,
+  custom: CustomBlock,
+};
+
+export const BLOCK_NAMES = Object.keys(BLOCKS);
+export { FIELD_TYPES };

package/src/index.js

@@ -4,3 +4,6 @@
 
 export { storage } from "./storage.js";
 export { createStore, createPersistedStore, createSharedStore } from "./state.js";
+export { createApp } from "./app.js";
+export { palette, themeCss, contrast } from "./theme.js";
+export { useReact, hasReact } from "./react-runtime.js";

package/src/react-runtime.js

@@ -0,0 +1,80 @@
+// react-runtime.js — how the framework gets hold of React.
+//
+// It must use the SAME React the host already loaded: a second copy on the
+// page makes every hook throw. But it must not depend on it with a static
+// `import React from "react"` either — a specifier the host can't resolve
+// kills the whole module at load time, before anything is left running to
+// report why.
+//
+// So React is resolved at runtime, from whichever of these is available:
+//
+//   1. globalThis.React   — present when the host exposes it
+//   2. useReact(React)    — the explicit hand-off
+//
+// The hand-off is one line and always available, because an artifact already
+// imports React for its own code:
+//
+//   import React from "react";
+//   ArtifactKit.useReact(React);
+//
+// Deliberately no dynamic import("react") fallback: it would need top-level
+// await, which the IIFE build can't have, and it only pays off in a runtime
+// with a native import map — which is not the way artifacts load code.
+
+let React = typeof globalThis !== "undefined" ? globalThis.React : undefined;
+
+export function useReact(instance) {
+  React = instance;
+  return instance;
+}
+
+export function hasReact() {
+  return Boolean(React);
+}
+
+// The live instance, for the few places that need React itself rather than one
+// of its functions — `class extends React.Component`, most of all.
+export function getReact() {
+  return required();
+}
+
+function required() {
+  if (!React) {
+    throw new Error(
+      "claude-artifact-framework: React not found. Hand it over once, before createApp:\n\n" +
+        '  import React from "react";\n' +
+        "  ArtifactKit.useReact(React);\n"
+    );
+  }
+  return React;
+}
+
+// Bound lazily, because modules import these at load time — which is before
+// useReact() can possibly have run.
+export const createElement = (...args) => required().createElement(...args);
+export const useState = (...args) => required().useState(...args);
+export const useEffect = (...args) => required().useEffect(...args);
+export const useMemo = (...args) => required().useMemo(...args);
+export const useRef = (...args) => required().useRef(...args);
+
+// A class component is read as a value at module scope, so it can't be
+// deferred behind a call. This stand-in is only ever constructed if React was
+// still missing at render time, and it reports the same error then.
+export const Component =
+  (React && React.Component) ||
+  class ReactMissing {
+    render() {
+      return required();
+    }
+  };
+
+// The default export mirrors `import React from "react"`, so the source files
+// can keep using React.createElement / React.useState unchanged.
+export default {
+  get createElement() { return required().createElement; },
+  get Component() { return required().Component; },
+  get useState() { return required().useState; },
+  get useEffect() { return required().useEffect; },
+  get useMemo() { return required().useMemo; },
+  get useRef() { return required().useRef; },
+};