claude-artifact-framework 0.2.1 → 0.3.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.3.0/dist/index.global.js"></script>
 <script>
   const { storage, createStore, createPersistedStore, createSharedStore } = ArtifactKit;
 </script>
@@ -27,13 +27,102 @@ 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.3.0/dist/index.esm.js";
 </script>
 ```
 
-Pin a version (`@0.2.0`) for reproducible artifacts, or drop the version
+Pin a version (`@0.3.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.
+
 ## `storage`
 
 Thin wrapper over `window.storage`, the persistence API Claude injects into a