claude-artifact-framework 0.2.1 → 0.3.0

package/src/app.js

@@ -0,0 +1,271 @@
+// app.js — createApp: the whole framework's entry point.
+//
+// Returns a React component, so an artifact is `export default createApp({…})`
+// with no mounting ceremony.
+//
+// Lifecycle, and deliberately only four stages:
+//   hydrate  read data + view from storage, merge over declared defaults
+//   mount    first render already holding real data, so there's no flash
+//   run      update() -> batched notify -> render, persistence debounced apart
+//   error    a boundary per block: one broken block shows its error, the rest live
+
+import { createElement as h, useState, useEffect, hasReact, getReact } from "react";
+import { createAppState } from "./appState.js";
+import { themeCss } from "./theme.js";
+import { BLOCKS, BLOCK_NAMES } from "./blocks.js";
+import { RecordsLayout } from "./records.js";
+
+const LAYOUTS = ["panel", "records"];
+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.
+function validate(spec) {
+  const layout = spec.layout || "panel";
+  if (!LAYOUTS.includes(layout)) {
+    throw new Error(
+      `claude-artifact-framework: unknown layout "${layout}". Valid layouts: ${LAYOUTS.join(", ")}.`
+    );
+  }
+  if (layout === "records") {
+    const r = spec.records;
+    if (!r || !Array.isArray(r.fields) || r.fields.length === 0) {
+      throw new Error(
+        'claude-artifact-framework: layout "records" needs `records: { fields: [...] }` — the same field declarations the fields block uses.'
+      );
+    }
+    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`.");
+      if (f.key === "id") throw new Error('claude-artifact-framework: "id" is reserved on records — 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);
+    }
+    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\`.`
+      );
+    }
+  });
+  return layout;
+}
+
+// Fields declare their own initial value, so the data shape is derived from
+// the declaration instead of being restated in a separate object. That removes
+// the key as an invention point: it is written exactly once.
+function defaultsFrom(spec) {
+  const data = { ...(spec.data || {}) };
+  if ((spec.layout || "panel") === "records" && !Array.isArray(data.records)) {
+    data.records = [];
+  }
+  for (const block of spec.blocks || []) {
+    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 : "";
+      }
+    }
+  }
+  return data;
+}
+
+// Built on first use, not at module scope: `extends React.Component` needs a
+// real React, and at load time the host may not have handed one over yet.
+let BlockBoundary = null;
+
+function boundary(React) {
+  if (!BlockBoundary) {
+    BlockBoundary = class extends React.Component {
+      constructor(props) {
+        super(props);
+        this.state = { error: null };
+      }
+      static getDerivedStateFromError(error) {
+        return { error };
+      }
+      render() {
+        if (this.state.error) {
+          return h(
+            "div",
+            { className: "caf-block caf-block-error" },
+            h("strong", null, "This section failed to render"),
+            h("code", null, String(this.state.error.message || this.state.error))
+          );
+        }
+        return this.props.children;
+      }
+    };
+  }
+  return BlockBoundary;
+}
+
+function Block({ block, ctx }) {
+  const name = Object.keys(block).find((k) => BLOCK_NAMES.includes(k));
+  const Component = BLOCKS[name];
+  return h(boundary(ctx.React), null, h(Component, { spec: block, ctx }));
+}
+
+function Panel({ spec, ctx }) {
+  return h(
+    "div",
+    { className: "caf-panel" },
+    (spec.blocks || []).map((block, i) =>
+      h(
+        "section",
+        { key: i, className: block.wide ? "caf-slot caf-slot-wide" : "caf-slot" },
+        h(Block, { block, ctx })
+      )
+    )
+  );
+}
+
+const LAYOUT_COMPONENTS = { panel: Panel, records: RecordsLayout };
+
+export function createApp(spec = {}) {
+  const layout = validate(spec);
+  const state = createAppState(defaultsFrom(spec));
+  const css = themeCss(spec.theme && spec.theme.seed) + BASE_CSS;
+
+  return function App() {
+    if (!hasReact()) {
+      throw new Error(
+        "claude-artifact-framework: React not found. Hand it over once, before rendering:\n\n" +
+          '  import React from "react";\n' +
+          "  ArtifactKit.useReact(React);\n"
+      );
+    }
+    const [, force] = useState(0);
+    useEffect(() => {
+      const unsubscribe = state.subscribe(() => force((n) => n + 1));
+      // Hydration can finish before this effect runs — its notify() then lands
+      // on zero listeners and nothing ever re-renders. Re-check on subscribe,
+      // so a mount that raced hydration still leaves the loading screen.
+      if (state.isHydrated()) force((n) => n + 1);
+      return unsubscribe;
+    }, []);
+
+    const ctx = {
+      React: getReact(),
+      data: state.getData(),
+      view: state.getView(),
+      update: state.update,
+      go: state.go,
+      back: state.back,
+    };
+
+    const Layout = LAYOUT_COMPONENTS[layout];
+
+    return h(
+      "div",
+      { className: "caf-root" },
+      h("style", { dangerouslySetInnerHTML: { __html: css } }),
+      h(
+        "header",
+        { className: "caf-header" },
+        spec.title ? h("h1", null, spec.title) : null,
+        spec.subtitle ? h("p", null, spec.subtitle) : null
+      ),
+      state.isHydrated()
+        ? h(Layout, { spec, ctx })
+        : h("div", { className: "caf-block caf-loading" }, "Loading…")
+    );
+  };
+}
+
+const BASE_CSS = `
+.caf-root {
+  --caf-radius: 10px;
+  box-sizing: border-box;
+  min-height: 100vh;
+  padding: 2rem 1.25rem 4rem;
+  background: var(--caf-bg);
+  color: var(--caf-text);
+  font-family: -apple-system, "Segoe UI", "Helvetica Neue", Arial, sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+.caf-root *, .caf-root *::before, .caf-root *::after { box-sizing: inherit; }
+.caf-header { max-width: 760px; margin: 0 auto 1.5rem; }
+.caf-header h1 { margin: 0; font-size: 1.5rem; font-weight: 650; letter-spacing: -0.01em; text-wrap: balance; }
+.caf-header p { margin: 0.4rem 0 0; color: var(--caf-muted); font-size: 0.95rem; line-height: 1.5; }
+.caf-panel { max-width: 760px; margin: 0 auto; display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; }
+.caf-slot { grid-column: span 2; min-width: 0; }
+@media (min-width: 720px) { .caf-slot { grid-column: span 1; } .caf-slot-wide { grid-column: span 2; } }
+.caf-block {
+  background: var(--caf-surface);
+  border: 1px solid var(--caf-border);
+  border-radius: var(--caf-radius);
+  padding: 1.1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.8rem;
+  height: 100%;
+}
+.caf-block-title { margin: 0; font-size: 0.95rem; font-weight: 650; }
+.caf-field { display: flex; flex-direction: column; gap: 0.3rem; }
+.caf-field label { font-size: 0.78rem; font-weight: 600; color: var(--caf-muted); letter-spacing: 0.02em; }
+.caf-field input, .caf-field select, .caf-field textarea {
+  font: inherit; font-size: 0.95rem; padding: 0.5rem 0.6rem;
+  border-radius: 7px; border: 1px solid var(--caf-border);
+  background: var(--caf-sunken); color: var(--caf-text); width: 100%;
+}
+.caf-field input:focus-visible, .caf-field select:focus-visible, .caf-field textarea:focus-visible,
+.caf-row:focus-visible { outline: 2px solid var(--caf-accent); outline-offset: 1px; }
+.caf-field input[aria-invalid="true"] { border-color: var(--caf-danger); }
+.caf-check { display: flex; align-items: center; gap: 0.5rem; font-size: 0.9rem; }
+.caf-hint { color: var(--caf-muted); font-size: 0.75rem; }
+.caf-error { color: var(--caf-danger); font-size: 0.75rem; font-weight: 600; }
+.caf-output-grid { display: flex; flex-direction: column; gap: 0.7rem; }
+.caf-stat { display: flex; align-items: baseline; justify-content: space-between; gap: 1rem; }
+.caf-stat-label { color: var(--caf-muted); font-size: 0.82rem; }
+.caf-stat-value { font-size: 1rem; font-weight: 600; font-variant-numeric: tabular-nums; }
+.caf-stat-big { flex-direction: column; align-items: flex-start; gap: 0.15rem; padding-bottom: 0.4rem; border-bottom: 1px solid var(--caf-border); }
+.caf-stat-big .caf-stat-value { font-size: 1.9rem; font-weight: 680; letter-spacing: -0.02em; color: var(--caf-accent); }
+.caf-list { padding: 0.4rem; gap: 0; }
+.caf-row {
+  font: inherit; text-align: left; cursor: pointer;
+  display: flex; flex-direction: column; gap: 0.15rem;
+  padding: 0.65rem 0.7rem; border: none; border-radius: 7px;
+  background: transparent; color: inherit; width: 100%;
+}
+.caf-row:hover { background: var(--caf-sunken); }
+.caf-row-title { font-size: 0.92rem; font-weight: 550; }
+.caf-row-sub { font-size: 0.78rem; color: var(--caf-muted); }
+.caf-panel-single { grid-template-columns: 1fr; }
+.caf-panel-single .caf-slot, .caf-panel-single > * { grid-column: span 1; }
+.caf-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 0.6rem; padding: 0.3rem 0.3rem 0.5rem; }
+.caf-count { font-size: 0.8rem; color: var(--caf-muted); font-variant-numeric: tabular-nums; }
+.caf-btn {
+  font: inherit; font-size: 0.85rem; font-weight: 600; cursor: pointer;
+  padding: 0.45rem 0.8rem; border-radius: 7px;
+  border: 1px solid var(--caf-border); background: var(--caf-sunken); color: var(--caf-text);
+}
+.caf-btn:hover { filter: brightness(0.97); }
+.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-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); }
+.caf-block-error code { font-size: 0.78rem; color: var(--caf-muted); word-break: break-word; }
+`;

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,215 @@
+// 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 } 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 }) {
+  const body = typeof spec.text === "function" ? spec.text() : 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
+      )
+    )
+  );
+}
+
+// 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,
+  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";