claude-artifact-framework 0.2.1 → 0.4.0

package/README.md

@@ -12,7 +12,7 @@ mirrors npm packages automatically.
 ### As a global script (`<script>` tag)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.2.0/dist/index.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.4.0/dist/index.global.js"></script>
 <script>
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
@@ -27,13 +27,154 @@ mirrors npm packages automatically.
     createStore,
     createPersistedStore,
     createSharedStore,
-  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.2.0/dist/index.esm.js";
+  } from "https://cdn.jsdelivr.net/npm/claude-artifact-framework@0.4.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.2.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.4.0`) for reproducible artifacts, or drop the version
 (`claude-artifact-framework/dist/...`) to always get the latest release.
 
+### Inside a React artifact
+
+A React artifact loads external code the same way any artifact does — by
+injecting a classic `<script>` tag, not by importing a module URL. Hand the
+framework the React the artifact already imported, so there is only ever one
+React on the page:
+
+```jsx
+import React, { useState, useEffect } from "react";
+
+const KIT = "https://cdn.jsdelivr.net/npm/claude-artifact-framework/dist/index.global.js";
+
+function load(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(`script[src="${src}"]`)) return resolve();
+    const tag = document.createElement("script");
+    tag.src = src;
+    tag.onload = resolve;
+    tag.onerror = reject;
+    document.head.appendChild(tag);
+  });
+}
+
+export default function Artifact() {
+  const [App, setApp] = useState(null);
+
+  useEffect(() => {
+    load(KIT).then(() => {
+      ArtifactKit.useReact(React);
+      setApp(() => ArtifactKit.createApp({
+        title: "Mortgage calculator",
+        theme: { seed: "#0c8b8d" },
+        blocks: [
+          { fields: [
+            { key: "amount", label: "Amount",   type: "money",   value: 300000 },
+            { key: "rate",   label: "Rate",     type: "percent", value: 5.5 },
+            { key: "years",  label: "Term",     type: "number",  value: 30, min: 1, max: 40 },
+          ]},
+          { output: (d) => {
+            const i = d.rate / 100 / 12, n = d.years * 12;
+            const payment = d.amount * i / (1 - Math.pow(1 + i, -n));
+            return [{ label: "Monthly payment", value: payment, format: "money", big: true }];
+          }},
+        ],
+      }));
+    });
+  }, []);
+
+  return App ? <App /> : null;
+}
+```
+
+`useReact` is the one thing the framework asks for, and only because a runtime
+may keep React in a private module registry the bundle can't reach. If React is
+already on `globalThis`, it is picked up automatically and the call is a no-op.
+
+### The `records` layout — a full CRUD app from a declaration
+
+For "list of things" apps (expenses, habits, notes, todos), declare what a
+record is and the whole lifecycle — list, add, edit, delete, empty state,
+selection, persistence — is framework-owned:
+
+```js
+ArtifactKit.createApp({
+  title: "Gastos",
+  theme: { seed: "#c2410c" },
+  layout: "records",
+  records: {
+    label: "expense",
+    fields: [
+      { key: "concepto",  label: "Concepto",  type: "text", required: true },
+      { key: "monto",     label: "Monto",     type: "money", value: 0, min: 0 },
+      { key: "categoria", label: "Categoría", type: "select", options: ["comida", "transporte", "otros"] },
+    ],
+    subtitle: (r) => r.categoria || "sin categoría",
+    summary: (all) => [
+      { label: "Total",  value: all.reduce((s, r) => s + (Number(r.monto) || 0), 0), format: "money", big: true },
+      { label: "Gastos", value: all.length, format: "number" },
+    ],
+  },
+});
+```
+
+"Add" creates the record from field defaults and opens it (no draft object to
+lose); detail fields edit the record in place through the same debounced
+persistence path as everything else. `id` is assigned by the framework and
+reserved. Optional: `title(r)` / `subtitle(r)` for rows, `sort(a, b)`,
+`summary(records)` for stats above the list, `empty` for the empty-state text.
+
+### The `steps` layout — wizards, quizzes, staged calculators
+
+Declare the sequence; next/back/progress/result are framework-owned. Step
+fields write into the same flat `data` pool, so the result step is just a
+function of data. Next is gated on the current step's validation; the current
+step survives a reload.
+
+```js
+ArtifactKit.createApp({
+  title: "Quiz de riesgo",
+  layout: "steps",
+  steps: [
+    { title: "Tu edad",   fields: [{ key: "edad", type: "number", required: true, min: 18 }] },
+    { title: "Tu perfil", fields: [{ key: "perfil", type: "select", required: true, options: ["conservador", "moderado", "agresivo"] }] },
+    { title: "Resultado", result: (d) => [{ label: "Puntaje", value: score(d), big: true }] },
+  ],
+});
+```
+
+Field keys must be unique across all steps (they share one data pool); a
+duplicate throws at creation, as does an unknown step key.
+
+### The `chart` block — bar, line, donut
+
+Same vocabulary as `output` (items of `{ label, value }` plus an optional
+`format`), so declaring one teaches nothing new. Colors derive from the theme
+seed by golden-angle rotation — a chart can't clash with the app it lives in.
+
+```js
+blocks: [
+  { chart: (d) => ({ type: "bar", format: "money", items: monthlyTotals(d) }), title: "Ventas", wide: true },
+  { chart: { type: "donut", items: [{ label: "Comida", value: 45 }, { label: "Otros", value: 55 }] } },
+]
+```
+
+### The `timer` block — countdowns that persist their effects
+
+The interval is framework-owned and cleaned up on unmount (a leaked
+`setInterval` is a classic half-built artifact bug). The countdown itself is
+deliberately ephemeral; what you declare is what happens when it finishes —
+`onDone` runs through `update()`, so its effects persist like any other change.
+
+```js
+blocks: [
+  { timer: { minutes: 25, label: "Focus", onDone: (d) => { d.completados = (d.completados || 0) + 1; } } },
+  { output: (d) => [{ label: "Pomodoros", value: d.completados || 0, big: true }] },
+]
+```
+
+`text` blocks also accept a function of data — `{ text: (d) => "Hola " + d.nombre }` —
+with the same contract as `output`.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a