claude-artifact-framework 0.2.1 → 0.4.0

package/src/records.js

@@ -0,0 +1,158 @@
+// records.js — the "list of things" layout: expenses, habits, notes, todos.
+//
+// The author declares what a record IS (the same field declarations the
+// fields block uses) and optionally what the collection summarises to. The
+// whole CRUD lifecycle — list, add, edit, delete, empty state, selection,
+// navigation — is framework-owned, so none of it can be half-built.
+//
+// Two deliberate choices keep the state model tiny:
+//
+//   add-then-edit   "Add" creates the record from field defaults and navigates
+//                   straight into it. There is no separate draft object, so a
+//                   half-typed record can't be lost — it already exists.
+//   edit-in-place   Detail fields write into the record directly through
+//                   update(), so persistence and re-render are the same
+//                   debounced path every other block uses.
+//
+// Which record is open lives in view state (screen "record", arg = id), never
+// in data — restoring it on reload is correct, and deleting the open record
+// simply falls back to the list.
+
+import { createElement as h } from "react";
+import { Field, formatValue } from "./blocks.js";
+
+export function recordDefaults(fields) {
+  const rec = {};
+  for (const f of fields) {
+    rec[f.key] = f.value !== undefined ? f.value : f.type === "check" ? false : "";
+  }
+  return rec;
+}
+
+// Collision-proof enough for a per-user list; no coordination needed.
+function makeId() {
+  return "r" + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+}
+
+function rowTitle(spec, rec) {
+  if (spec.title) return spec.title(rec);
+  // Default: the first text-ish field, which is what a human would label by.
+  const f = spec.fields.find((f) => !f.type || f.type === "text" || f.type === "textarea" || f.type === "select");
+  const v = f && rec[f.key];
+  return v === "" || v === undefined || v === null ? "(untitled)" : String(v);
+}
+
+function Summary({ spec, records }) {
+  if (!spec.summary) return null;
+  const items = spec.summary(records) || [];
+  if (!items.length) return null;
+  return h(
+    "div",
+    { className: "caf-block caf-output" },
+    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))
+        )
+      )
+    )
+  );
+}
+
+function ListScreen({ spec, ctx }) {
+  const label = spec.label || "item";
+  let records = ctx.data.records;
+  if (spec.sort) records = records.slice().sort(spec.sort);
+
+  function add() {
+    const rec = { id: makeId(), ...recordDefaults(spec.fields) };
+    ctx.update((d) => {
+      d.records = [...d.records, rec];
+    });
+    ctx.go("record", rec.id);
+  }
+
+  return h(
+    "div",
+    { className: "caf-block caf-list" },
+      h(
+        "div",
+        { className: "caf-toolbar" },
+        h("span", { className: "caf-count" }, `${records.length} ${label}${records.length === 1 ? "" : "s"}`),
+        h("button", { type: "button", className: "caf-btn caf-btn-primary", onClick: add }, `Add ${label}`)
+      ),
+      records.length === 0
+        ? h("div", { className: "caf-empty" }, spec.empty || `No ${label}s yet. Add the first one.`)
+        : records.map((rec) =>
+            h(
+              "button",
+              {
+                key: rec.id,
+                type: "button",
+                className: "caf-row",
+                onClick: () => ctx.go("record", rec.id),
+              },
+              h("span", { className: "caf-row-title" }, rowTitle(spec, rec)),
+              spec.subtitle ? h("span", { className: "caf-row-sub" }, spec.subtitle(rec)) : null
+            )
+          )
+  );
+}
+
+function DetailScreen({ spec, ctx, record }) {
+  const label = spec.label || "item";
+
+  function remove() {
+    ctx.update((d) => {
+      d.records = d.records.filter((r) => r.id !== record.id);
+    });
+    ctx.back();
+  }
+
+  return h(
+    "div",
+    { className: "caf-block caf-fields" },
+    h(
+      "div",
+      { className: "caf-toolbar" },
+      h("button", { type: "button", className: "caf-btn", onClick: ctx.back }, "‹ Back"),
+      h("button", { type: "button", className: "caf-btn caf-btn-danger", onClick: remove }, `Delete ${label}`)
+    ),
+    spec.fields.map((field) =>
+      h(Field, {
+        key: field.key,
+        field,
+        value: record[field.key],
+        onChange: (v) =>
+          ctx.update((d) => {
+            const rec = d.records.find((r) => r.id === record.id);
+            if (rec) rec[field.key] = v;
+          }),
+      })
+    )
+  );
+}
+
+export function RecordsLayout({ spec, ctx }) {
+  const rspec = spec.records;
+
+  if (ctx.view.screen === "record") {
+    const record = ctx.data.records.find((r) => r.id === ctx.view.arg);
+    // The open record can vanish (deleted, or stale view state from an earlier
+    // version of the data) — fall back to the list rather than a blank pane.
+    if (record) {
+      return h("div", { className: "caf-panel caf-panel-single" }, h(DetailScreen, { spec: rspec, ctx, record }));
+    }
+  }
+  return h(
+    "div",
+    { className: "caf-panel caf-panel-single" },
+    h(Summary, { spec: rspec, records: ctx.data.records }),
+    h(ListScreen, { spec: rspec, ctx })
+  );
+}

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

@@ -0,0 +1,157 @@
+// theme.js — derives a complete palette from a single seed colour.
+//
+// One token in, a full light+dark palette out, with contrast checked rather
+// than assumed. The point is that an app gets its own visual identity from
+// one line while structure stays shared, so apps built with this framework
+// don't all look alike.
+//
+// Neutrals carry a slight hue bias toward the seed instead of being pure
+// grey — a pure mid-grey reads as unconsidered.
+
+function clamp(n, lo, hi) {
+  return Math.min(hi, Math.max(lo, n));
+}
+
+function hexToRgb(hex) {
+  let h = String(hex).replace("#", "").trim();
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  const n = parseInt(h, 16);
+  if (!Number.isFinite(n)) return [59, 110, 246];
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+function rgbToHex(rgb) {
+  return "#" + rgb.map((v) => clamp(Math.round(v), 0, 255).toString(16).padStart(2, "0")).join("");
+}
+
+function rgbToHsl([r, g, b]) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+  let h = 0;
+  let s = 0;
+  if (d) {
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+    else if (max === g) h = (b - r) / d + 2;
+    else h = (r - g) / d + 4;
+    h /= 6;
+  }
+  return [h * 360, s * 100, l * 100];
+}
+
+function hslToRgb(h, s, l) {
+  h = (((h % 360) + 360) % 360) / 360;
+  s = clamp(s, 0, 100) / 100;
+  l = clamp(l, 0, 100) / 100;
+  if (!s) return [l * 255, l * 255, l * 255];
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const channel = (t) => {
+    if (t < 0) t += 1;
+    if (t > 1) t -= 1;
+    if (t < 1 / 6) return p + (q - p) * 6 * t;
+    if (t < 1 / 2) return q;
+    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+  };
+  return [channel(h + 1 / 3) * 255, channel(h) * 255, channel(h - 1 / 3) * 255];
+}
+
+function hsl(h, s, l) {
+  return rgbToHex(hslToRgb(h, s, l));
+}
+
+function luminance(rgb) {
+  const a = rgb.map((v) => {
+    v /= 255;
+    return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * a[0] + 0.7152 * a[1] + 0.0722 * a[2];
+}
+
+// WCAG contrast ratio between two hex colours, 1 (identical) to 21 (max).
+export function contrast(a, b) {
+  const la = luminance(hexToRgb(a));
+  const lb = luminance(hexToRgb(b));
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+// Walks lightness until the colour clears `min` contrast against `against`,
+// so the accent is guaranteed legible instead of merely hoped to be.
+function accentAt(h, s, against, min, from, step) {
+  for (let l = from; l >= 4 && l <= 96; l += step) {
+    const candidate = hsl(h, s, l);
+    if (contrast(candidate, against) >= min) return candidate;
+  }
+  return hsl(h, s, step < 0 ? 24 : 82);
+}
+
+export function palette(seed = "#3b6ef6") {
+  const [h, rawSat] = rgbToHsl(hexToRgb(seed));
+  const sat = clamp(rawSat, 30, 88);
+  // Neutrals keep a trace of the seed's hue: chosen, not inherited.
+  const tint = clamp(sat * 0.1, 3, 9);
+
+  const lightSurface = hsl(h, tint * 0.4, 100);
+  const darkSurface = hsl(h, tint * 1.4, 13);
+
+  return {
+    light: {
+      bg: hsl(h, tint, 96.5),
+      surface: lightSurface,
+      sunken: hsl(h, tint, 93),
+      border: hsl(h, tint, 86),
+      text: hsl(h, tint * 1.6, 11),
+      muted: hsl(h, tint * 1.2, 41),
+      accent: accentAt(h, sat, "#ffffff", 4.5, 54, -2),
+      accentText: "#ffffff",
+      danger: accentAt(2, 68, "#ffffff", 4.5, 54, -2),
+      ok: accentAt(148, 62, "#ffffff", 4.5, 44, -2),
+      warn: accentAt(38, 88, "#ffffff", 4.5, 44, -2),
+    },
+    dark: {
+      bg: hsl(h, tint * 1.5, 9),
+      surface: darkSurface,
+      sunken: hsl(h, tint * 1.5, 7),
+      border: hsl(h, tint * 1.3, 24),
+      text: hsl(h, tint * 0.6, 95),
+      muted: hsl(h, tint * 0.8, 66),
+      accent: accentAt(h, clamp(sat, 40, 80), darkSurface, 4.5, 62, 2),
+      accentText: hsl(h, tint * 2, 8),
+      danger: accentAt(2, 70, darkSurface, 4.5, 62, 2),
+      ok: accentAt(148, 55, darkSurface, 4.5, 62, 2),
+      warn: accentAt(38, 80, darkSurface, 4.5, 62, 2),
+    },
+  };
+}
+
+function vars(scheme) {
+  return Object.entries(scheme)
+    .map(([k, v]) => `--caf-${k}: ${v};`)
+    .join("");
+}
+
+// Both themes are styled through the same tokens, and the viewer's explicit
+// toggle (data-theme on the root) must beat the OS preference in both
+// directions — hence the two attribute blocks after the media query.
+export function themeCss(seed) {
+  const p = palette(seed);
+  return `
+:root { ${vars(p.light)} }
+@media (prefers-color-scheme: dark) { :root { ${vars(p.dark)} } }
+:root[data-theme="dark"] { ${vars(p.dark)} }
+: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));
+}