claude-artifact-framework 0.2.1 → 0.3.0

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

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/theme.js

@@ -0,0 +1,148 @@
+// 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)} }
+`;
+}