makersclaw 0.8.0 → 0.8.2

package/registry/blocks/connect-card/connect-card.jsx

@@ -0,0 +1,103 @@
+"use client";
+
+// The app's declared accounts as rows, the way the window's Settings ›
+// Connections draws them: what each is for, live or not connected, which
+// accounts meet it, and Connect (or Change). Props in, callbacks out: the
+// press goes out as onConnect(key), which useConnections turns into the
+// desk's connections panel (every provider of the kind; no agent turn),
+// or a link in a new tab outside the desk. Signing in stays the member's,
+// at the provider. Tokens only; live or not is a mark AND a word. Its own
+// width decides its layout (@container): under about 384 px the state and
+// the button go under the words.
+
+import { Button, Icon, cx } from "../../ui";
+
+/** Live or not, as a pill: a mark and a word. */
+function StatePill({ connected, waiting }) {
+  const look = connected
+    ? { icon: "circle-check", word: "Live", tone: "text-success border-success" }
+    : waiting
+      ? { icon: "loader", word: "Waiting for sign-in", tone: "text-info border-info" }
+      : { icon: "circle-dashed", word: "Not connected", tone: "text-muted-foreground border-border" };
+  return (
+    <span className={cx("inline-flex shrink-0 items-center gap-1 rounded-full border px-2 py-0.5 text-[11.5px]", look.tone)}>
+      <Icon name={look.icon} size={12} className={waiting && !connected ? "animate-spin motion-reduce:animate-none" : undefined} />
+      {look.word}
+    </span>
+  );
+}
+
+/**
+ * One declared account.
+ *
+ *   connection   { key, label, required, connected, accounts, category_label }
+ *                (a row of useConnections' `connections`)
+ *   onConnect(key)   Connect / Change; leave it out and no button is drawn
+ *   connecting   this account is being connected: the pill waits
+ *   connectLabel, changeLabel   the button's words (default "Connect", "Change")
+ */
+export function ConnectRow({ connection, onConnect, connecting = false, connectLabel = "Connect", changeLabel = "Change", className }) {
+  const c = connection ?? {};
+  const accounts = Array.isArray(c.accounts) ? c.accounts.filter(Boolean) : [];
+  const meta = [c.category_label, c.required === true ? "Needed" : c.required === false ? "Optional" : null].filter(Boolean).join(" · ");
+  return (
+    <li className={cx("grid min-w-0 gap-2 px-3.5 py-3 @sm:grid-cols-[minmax(0,1fr)_auto] @sm:items-center @sm:gap-3", className)}>
+      <div className="grid min-w-0 gap-0.5">
+        <span className="line-clamp-2 text-[13px] text-card-foreground">{c.label}</span>
+        {meta ? <span className="truncate text-xs text-muted-foreground">{meta}</span> : null}
+        {c.connected && accounts.length ? (
+          <span className="truncate text-xs text-muted-foreground" title={accounts.join(", ")}>
+            {accounts.length === 1 ? accounts[0] : `${accounts[0]} and ${accounts.length - 1} more`}
+          </span>
+        ) : null}
+      </div>
+      <div className="flex min-w-0 flex-wrap items-center gap-2 @sm:flex-nowrap @sm:justify-end">
+        <StatePill connected={Boolean(c.connected)} waiting={connecting} />
+        {onConnect ? (
+          <Button size="sm" variant={c.connected ? "quiet" : "secondary"} onClick={() => onConnect(c.key)} disabled={connecting && !c.connected}>
+            {c.connected ? changeLabel : connectLabel}
+          </Button>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+/**
+ * The app's accounts on a card.
+ *
+ *   connections   useConnections' `connections`
+ *   onConnect(key)    useConnections' `connect`
+ *   connecting    the key being connected (useConnections' `connecting`)
+ *   title         the card's head (default "Accounts it uses"); null for none
+ *   description   one line under it: what the app does with them
+ *   empty         what the card says with no accounts (null draws nothing)
+ */
+export function ConnectCard({ connections = [], onConnect, connecting = null, title = "Accounts it uses", description, empty = "This app connects to no accounts.", className }) {
+  const list = Array.isArray(connections) ? connections : [];
+  if (!list.length && empty === null) return null;
+  return (
+    <section aria-label={title ?? "Accounts"} className={cx("@container grid min-w-0 overflow-hidden rounded-[var(--radius)] border border-border bg-card text-card-foreground", className)}>
+      {title || description ? (
+        <header className="grid gap-0.5 border-b border-border px-3.5 py-3">
+          {title ? (
+            <span className="flex min-w-0 items-center gap-2">
+              <Icon name="link" size={14} className="shrink-0 text-muted-foreground" />
+              <b className="truncate text-sm font-semibold">{title}</b>
+            </span>
+          ) : null}
+          {description ? <span className="text-xs text-muted-foreground">{description}</span> : null}
+        </header>
+      ) : null}
+      {list.length ? (
+        <ul className="m-0 grid list-none divide-y divide-border p-0">
+          {list.map((c) => (
+            <ConnectRow key={c.key} connection={c} onConnect={onConnect} connecting={connecting === c.key} />
+          ))}
+        </ul>
+      ) : (
+        <p className="m-0 px-3.5 py-3 text-[13px] text-muted-foreground">{empty}</p>
+      )}
+    </section>
+  );
+}

package/registry/blocks/connect-card/demo.jsx

@@ -0,0 +1,49 @@
+"use client";
+
+// ConnectCard with pretend accounts — the gallery's and the smoke test's
+// surface. Not installed into apps. Connect waits for a pretend sign-in,
+// then the row goes live. Below: the card at 320 px, a read-only card,
+// and one with no accounts.
+import { useState } from "react";
+import { ConnectCard, ConnectRow } from "../components/blocks/connect-card";
+
+const START = [
+  { key: "mail", label: "Email, to build your contacts and timelines and send the follow-ups you approve", category: "mail", category_label: "Mail", required: true, connected: false, accounts: [] },
+  { key: "calendar", label: "Calendar, to add your meetings to each timeline", category: "calendar", category_label: "Calendar", required: false, connected: true, accounts: ["nadia@pinewood.co", "team@pinewood.co"] },
+  { key: "old_crm", label: "Your old CRM, to import from", category: "crm", category_label: "CRM", required: false, connected: false, accounts: [] },
+];
+
+export default function ConnectCardDemo() {
+  const [connections, setConnections] = useState(START);
+  const [connecting, setConnecting] = useState(null);
+  const connect = (key) => {
+    setConnecting(key);
+    setTimeout(() => {
+      setConnections((cs) => cs.map((c) => (c.key === key ? { ...c, connected: true, accounts: c.accounts.length ? c.accounts : ["nadia@pinewood.co"] } : c)));
+      setConnecting(null);
+    }, 1500);
+  };
+  return (
+    <div className="grid gap-6 p-4">
+      <ConnectCard
+        className="w-full max-w-[800px]"
+        title="What the CRM reads"
+        description="Your mail and calendar, to build each person's timeline. Nothing is sent without your yes."
+        connections={connections}
+        connecting={connecting}
+        onConnect={connect}
+      />
+      <div className="flex flex-wrap items-start gap-4">
+        <ConnectCard className="w-full max-w-[320px]" connections={connections} connecting={connecting} onConnect={connect} />
+        <ConnectCard className="w-full max-w-[368px]" title="Read only" connections={connections.slice(0, 2)} />
+        <ConnectCard className="w-full max-w-[320px]" connections={[]} />
+      </div>
+      <div className="@container w-full max-w-[368px] rounded-[var(--radius)] border border-dashed border-border">
+        <p className="m-0 px-3.5 pt-3 text-[13px] text-muted-foreground">No people yet. They come from your mail once it is connected.</p>
+        <ul className="m-0 list-none p-0">
+          <ConnectRow connection={connections[0]} onConnect={connect} connecting={connecting === "mail"} />
+        </ul>
+      </div>
+    </div>
+  );
+}

package/registry/blocks/connect-card/index.js

@@ -0,0 +1,3 @@
+// The ConnectCard block — `makersclaw add connect-card`. Fixed: compose
+// it through its props (README.md beside this file).
+export { ConnectCard, ConnectRow } from "./connect-card";

package/registry/blocks/cost/README.md

@@ -0,0 +1,115 @@
+# Cost
+
+What a press will spend, said before the press. Part of the agent kit
+(0.8.1): **every control that spends shows its price on the control.**
+
+- `CostTag` — the price on a control: "about 700 cr", "up to 2,000 cr",
+  "1 call · 2 cr".
+- `CostConfirm` — the confirm before a big spend: "This uses about 700
+  credits, at most 1,000. 12,400 left.", **Go ahead**, and a cheaper
+  first step as a second choice ("Try the first 10 rows").
+- `Allowance` — the week's credits as a meter: "2,840 credits left this
+  week".
+- `creditsWords(n)` — credits as the kit says them: to a tenth under 10
+  ("1.2"), whole above, thousands marked ("2,000").
+
+```jsx
+import { CostTag, CostConfirm, Allowance } from "../components/blocks/cost";   // a Makersclaw app
+import { CostTag, CostConfirm, Allowance } from "@/components/makersclaw/blocks/cost";   // a shadcn project
+```
+
+Client components. They read no wallet and spend nothing: the screen
+passes the figures and the press goes out as a callback. 1 USD is 1,000
+credits.
+
+## Props
+
+### CostTag
+
+- `credits` — the estimate. `max` — the ceiling: alone it is "up to
+  2,000 cr"; with `credits` it is said on hover.
+- `calls` — model calls: "1 call · 2 cr".
+- `words` — your own words instead.
+- `loading` — the price is being asked for: a quiet "pricing…".
+- `icon` — `false` for no mark. `className`.
+
+Nothing is drawn when there is no price to say.
+
+### CostConfirm
+
+- `estimate`, `max` — credits it is likely to use, and at most.
+- `left` — credits left (a number), or your own words.
+- `onConfirm`, `confirmLabel` ("Go ahead"), `busy` (the press is out).
+- `onCancel`, `cancelLabel` ("Not now").
+- `cheaper` — `{ label, price?, onChoose }`: the smaller first step.
+- `onTopUp` — opens the desk to add credits. When `left` is under
+  `estimate`, the confirm says there are not enough and offers this
+  instead of Go ahead.
+- `title` — default "Before it starts". `className`.
+
+Under about 384 px of its own width its buttons stack, full width.
+
+### Allowance
+
+- `used`, `of` — credits used this week and the week's cap.
+- `words` — the line (default "4,180 of 10,000 credits this week").
+- `title` — default "This week"; `null` for none. `className`.
+
+## Where the figures come from (lib/hooks.js)
+
+- A model call: `useLlmAction({ input, … }).estimate` — `{ credits,
+  credits_max }`, asked of `POST _claw/llm` with `estimate: true`
+  (priced, never sent to a model, never charged), once per input.
+- A job: `useJobs().budget` — `{ week_cap_credits, week_used_credits }`
+  for Allowance; the job's own price is the app's to say ("about 700
+  cr"), from what its runs cost (`useRuns`' `credits`).
+- What is left: `useJobs().credits`, as `_claw/me` gives them.
+
+## Who may do what
+
+The confirm is the member's own act, in their own app, with credits the
+workspace already holds. Adding credits, a plan, a card: the desk's,
+always. `onTopUp` opens the desk; nothing here takes money.
+
+## Never
+
+- Never a control that spends without its price on it.
+- Never a payment form, a card field or a plan picker: money is the
+  desk's.
+- Never a price made up: say what the estimate, the runs or the
+  declared price say, or say nothing.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { useJobs } from "../lib/hooks";
+import { Button } from "../components/ui";
+import { Allowance, CostConfirm, CostTag } from "../components/blocks/cost";
+
+export default function EnrichAll({ rows, enrich }) {
+  const { budget } = useJobs();
+  const [asking, setAsking] = useState(false);
+  const each = 1.4;
+  return (
+    <div className="grid gap-3">
+      {asking ? (
+        <CostConfirm
+          estimate={rows.length * each}
+          max={rows.length * each * 1.5}
+          left={budget ? budget.week_cap_credits - budget.week_used_credits : null}
+          onConfirm={() => enrich(rows)}
+          onCancel={() => setAsking(false)}
+          cheaper={{ label: "Try the first 10 rows", price: `about ${Math.round(10 * each)} cr`, onChoose: () => enrich(rows.slice(0, 10)) }}
+        />
+      ) : (
+        <Button icon="sparkles" onClick={() => setAsking(true)}>
+          Enrich {rows.length} rows <CostTag credits={rows.length * each} icon={false} />
+        </Button>
+      )}
+      {budget ? <Allowance used={budget.week_used_credits} of={budget.week_cap_credits} /> : null}
+    </div>
+  );
+}
+```

package/registry/blocks/cost/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "cost",
+  "title": "Cost",
+  "description": "What a press will spend, said before the press. CostTag is the price on a control that spends (\"about 700 cr\", \"up to 2,000 cr\", \"1 call · 2 cr\"). CostConfirm is the confirm before a big spend: what it uses and at most, what is left, Go ahead, and an optional cheaper first step (\"Try the first 10 rows\"); with too few credits it says so and points at the desk, where credits are added. Allowance is the week's credits as a meter. Fed by useLlmAction's estimate, useJobs' budget and credits (lib/hooks.js); it reads no wallet and spends nothing itself.",
+  "useWhen": "Every control that spends credits says its price on it: Run now, Read now, Enrich 500 rows, Summarize, Generate. Put CostConfirm before a spend big enough to pause over (a whole table, a long run), and Allowance where an app shows its agent's week (beside a schedule-card, in a run's overview).",
+  "tags": ["cost", "price", "credits", "estimate", "spend", "confirm", "budget", "allowance", "meter", "billing", "kit"],
+  "exports": ["CostTag", "CostConfirm", "Allowance", "creditsWords"],
+  "files": ["index.js", "cost.jsx"],
+  "requires": []
+}

package/registry/blocks/cost/cost.jsx

@@ -0,0 +1,176 @@
+"use client";
+
+// What a press will spend, said before the press: the price on a control
+// (CostTag), the confirm before a big spend with a cheaper second choice
+// (CostConfirm), and the week's allowance (Allowance). Props in,
+// callbacks out; the block reads no wallet and spends nothing itself.
+// Tokens only. Money stays on the desk: topping up opens it, never a
+// form here. Its own width decides its layout (@container).
+
+import { Button, Icon, cx } from "../../ui";
+
+/** Credits as the kit says them: to a tenth under 10 ("1.2"), whole above,
+ *  thousands marked the same on the server and in the browser ("2,000"). */
+export function creditsWords(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) return null;
+  const v = n < 10 ? Math.round(n * 10) / 10 : Math.round(n);
+  return v.toLocaleString("en-US", { maximumFractionDigits: 1 });
+}
+
+/** The price words: "about 700 cr", "up to 2,000 cr", "1 call · 2 cr". */
+function tagWords({ credits, max, calls, words }) {
+  if (words) return words;
+  const c = creditsWords(credits);
+  const m = creditsWords(max);
+  if (typeof calls === "number" && calls > 0) {
+    const n = `${calls} ${calls === 1 ? "call" : "calls"}`;
+    return c ? `${n} · ${c} cr` : m ? `${n} · up to ${m} cr` : n;
+  }
+  if (c) return `about ${c} cr`;
+  if (m) return `up to ${m} cr`;
+  return null;
+}
+
+/**
+ * The price on a control that spends.
+ *
+ *   credits   the estimate ("about 700 cr")
+ *   max       the ceiling: alone, "up to 2,000 cr"; with credits, said on hover
+ *   calls     model calls: "1 call · 2 cr"
+ *   words     your own words instead ("free", "about a minute of reading")
+ *   loading   the price is being asked for: a quiet "pricing…"
+ *   icon      false for no mark (inside a Button that has its own icon)
+ *
+ * Nothing at all when there is no price to say.
+ */
+export function CostTag({ credits, max, calls, words, loading = false, icon = true, className }) {
+  const said = tagWords({ credits, max, calls, words });
+  if (!said && !loading) return null;
+  const ceiling = creditsWords(max);
+  return (
+    <span
+      className={cx("inline-flex min-w-0 items-center gap-1 whitespace-nowrap text-xs font-normal tabular-nums text-muted-foreground", className)}
+      title={credits != null && ceiling ? `at most ${ceiling} credits` : undefined}
+    >
+      {icon ? <Icon name="zap" size={12} className="shrink-0" /> : null}
+      <span className="truncate">{said ?? "pricing…"}</span>
+    </span>
+  );
+}
+
+/**
+ * The confirm before a big spend, in the member's own app: what it uses,
+ * at most, what is left, Go ahead or a cheaper first step.
+ *
+ *   estimate   credits it is likely to use (700)
+ *   max        at most (1,000), or null
+ *   left       credits left (12,400), or words ("12,400 left this week"), or null
+ *   onConfirm, confirmLabel ("Go ahead"), busy (the press is out)
+ *   onCancel, cancelLabel ("Not now")
+ *   cheaper    { label: "Try the first 10 rows", price?: "about 70 cr", onChoose }
+ *   onTopUp    opens the desk to add credits, when there is not enough
+ *   title      the head (default "Before it starts")
+ */
+export function CostConfirm({
+  estimate,
+  max,
+  left,
+  onConfirm,
+  confirmLabel = "Go ahead",
+  busy = false,
+  onCancel,
+  cancelLabel = "Not now",
+  cheaper,
+  onTopUp,
+  title = "Before it starts",
+  className,
+}) {
+  const e = creditsWords(estimate);
+  const m = creditsWords(max);
+  const leftNumber = typeof left === "number" && Number.isFinite(left) ? left : null;
+  const leftWords = leftNumber != null ? `${creditsWords(leftNumber)} left.` : typeof left === "string" && left ? left : null;
+  const short = leftNumber != null && typeof estimate === "number" && leftNumber < estimate;
+  const use = e ? `This uses about ${e} credits${m && max !== estimate ? `, at most ${m}` : ""}.` : m ? `This uses at most ${m} credits.` : null;
+  return (
+    <section role="group" aria-label={title} className={cx("@container grid min-w-0 gap-3 rounded-[var(--radius)] border border-border bg-card p-3 text-[13px] text-card-foreground", className)}>
+      <div className="flex min-w-0 items-start gap-2">
+        <Icon name="zap" size={16} className="mt-0.5 shrink-0 text-muted-foreground" />
+        <div className="grid min-w-0 gap-0.5">
+          <b className="font-semibold">{title}</b>
+          <p className="m-0">
+            {use} {leftWords ? <span className={short ? "text-destructive" : "text-muted-foreground"}>{leftWords}</span> : null}
+          </p>
+          {short ? (
+            <p className="m-0 flex items-center gap-1 text-xs text-destructive">
+              <Icon name="warning" size={12} />
+              Not enough credits for this. Adding them is on the desk.
+            </p>
+          ) : null}
+        </div>
+      </div>
+      <div className="flex flex-col items-stretch gap-2 @sm:flex-row @sm:flex-wrap @sm:items-center">
+        {short && onTopUp ? (
+          <Button size="sm" variant="primary" icon="external" onClick={onTopUp}>
+            Add credits on the desk
+          </Button>
+        ) : (
+          <Button size="sm" variant="primary" icon="play" loading={busy} disabled={short} onClick={onConfirm}>
+            {confirmLabel}
+          </Button>
+        )}
+        {cheaper ? (
+          <Button size="sm" variant="secondary" onClick={cheaper.onChoose} disabled={busy}>
+            <span className="truncate">{cheaper.label}</span>
+            {cheaper.price ? <span className="font-normal text-muted-foreground">{cheaper.price}</span> : null}
+          </Button>
+        ) : null}
+        {onCancel ? (
+          <Button size="sm" variant="quiet" onClick={onCancel} disabled={busy}>
+            {cancelLabel}
+          </Button>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+/**
+ * The week's allowance as a meter.
+ *
+ *   used, of   credits used and the cap (4,180 of 10,000)
+ *   words      the line ("2,840 credits left this week"); default "<used> of <of> credits this week"
+ *   title      the label over it (default "This week"); null for none
+ */
+export function Allowance({ used, of, words, title = "This week", className }) {
+  const pct = typeof used === "number" && of > 0 ? Math.max(0, Math.min(1, used / of)) : null;
+  const full = pct != null && pct >= 1;
+  const said = words ?? (pct != null ? `${creditsWords(used)} of ${creditsWords(of)} credits this week` : null);
+  return (
+    <div className={cx("grid min-w-0 gap-1 text-xs", className)}>
+      {title || said ? (
+        <div className="flex min-w-0 flex-wrap items-baseline justify-between gap-x-3">
+          {title ? <span className="font-medium text-foreground">{title}</span> : null}
+          {said ? (
+            <span className={cx("inline-flex min-w-0 items-center gap-1 tabular-nums", full ? "text-destructive" : "text-muted-foreground")}>
+              {full ? <Icon name="warning" size={12} className="shrink-0" /> : null}
+              <span className="truncate">{said}</span>
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      {pct != null ? (
+        <span
+          role="meter"
+          aria-label={title ?? "Credits this week"}
+          aria-valuemin={0}
+          aria-valuemax={of}
+          aria-valuenow={Math.min(used, of)}
+          aria-valuetext={said ?? undefined}
+          className="block h-1.5 overflow-hidden rounded-sm bg-border"
+        >
+          <span className={cx("block h-full", full ? "bg-destructive" : "bg-muted-foreground")} style={{ width: `${pct * 100}%` }} />
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/registry/blocks/cost/demo.jsx

@@ -0,0 +1,66 @@
+"use client";
+
+// CostTag, CostConfirm and Allowance with pretend figures — the
+// gallery's and the smoke test's surface. Not installed into apps. Prices
+// on buttons, a confirm with a cheaper first step, a confirm with too few
+// credits, and the week's allowance empty, half spent and spent; at 320
+// and 368 px so the layout by its own width shows.
+import { useState } from "react";
+import { Button } from "../components/ui";
+import { Allowance, CostConfirm, CostTag } from "../components/blocks/cost";
+
+export default function CostDemo() {
+  const [asking, setAsking] = useState(true);
+  const [busy, setBusy] = useState(false);
+  const go = () => {
+    setBusy(true);
+    setTimeout(() => {
+      setBusy(false);
+      setAsking(false);
+    }, 900);
+  };
+  return (
+    <div className="grid gap-6 p-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <Button size="sm" icon="play">
+          Read now <CostTag credits={700} max={1000} icon={false} />
+        </Button>
+        <Button size="sm" icon="sparkles">
+          Shorter <CostTag calls={1} credits={1.2} icon={false} />
+        </Button>
+        <Button size="sm" icon="sparkles">
+          Enrich 500 rows <CostTag max={2000} icon={false} />
+        </Button>
+        <Button size="sm" icon="sparkles">
+          Explain this score <CostTag loading icon={false} />
+        </Button>
+        <CostTag credits={0.4} />
+        <CostTag words="free" />
+      </div>
+      <div className="flex flex-wrap items-start gap-4">
+        {asking ? (
+          <CostConfirm
+            className="w-full max-w-[368px]"
+            estimate={700}
+            max={1000}
+            left={12400}
+            busy={busy}
+            onConfirm={go}
+            onCancel={() => setAsking(false)}
+            cheaper={{ label: "Try the first 10 rows", price: "about 14 cr", onChoose: go }}
+          />
+        ) : (
+          <Button size="sm" onClick={() => setAsking(true)}>
+            Enrich 500 rows <CostTag credits={700} icon={false} />
+          </Button>
+        )}
+        <CostConfirm className="w-full max-w-[320px]" title="Not enough credits" estimate={700} max={1000} left={400} onTopUp={() => {}} onCancel={() => {}} />
+      </div>
+      <div className="grid w-full max-w-[368px] gap-4">
+        <Allowance used={0} of={10000} words="10,000 credits left this week" />
+        <Allowance used={7160} of={10000} words="2,840 credits left this week" />
+        <Allowance used={10000} of={10000} words="All 10,000 spent · back Monday" />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/cost/index.js

@@ -0,0 +1,3 @@
+// The cost block — `makersclaw add cost`. Fixed: compose it through its
+// props (README.md beside this file).
+export { CostTag, CostConfirm, Allowance, creditsWords } from "./cost";

package/registry/blocks/data-picker/README.md

@@ -0,0 +1,81 @@
+# DataPicker
+
+Mapping data from earlier steps into a field of an automation. A step reads
+what an earlier step made with `{{ steps.read_mail.output.messages }}`; the
+data picker is how a person writes that without knowing the syntax.
+
+- `DataPicker` — the menu. **This run** (when it started, the clock, the
+  run's id); **This item** (inside a for-each: the item and its place in
+  the list); **Your questions** (what a manual run asks first); **Earlier
+  steps** (every step that runs before this one, nearest first). Where a
+  real run left a sample of a step's output, the step opens to the fields
+  inside it, each with a taste of its value ("ana@x.com", "12 items").
+- `DataButton` — the **{ }** button and the menu in a popover.
+- `DataInput` — a labelled text field (one line, or several with
+  `multiline`) with the button beside it. A press inserts the reference
+  where the cursor was.
+- `DataPairs` — a list of name and value rows (a step's `input`, a Set's
+  `values`), each value with its own button. A value that reads as a
+  number, true, false, null, a list or an object is kept as that; anything
+  else is text, and `{{ … }}` is a reference the platform reads later.
+
+```jsx
+import { DataInput, DataPairs } from "../components/blocks/data-picker";   // a Makersclaw app
+import { DataInput, DataPairs } from "@/components/makersclaw/blocks/data-picker";   // a shadcn project
+```
+
+`makersclaw add data-picker` lays `automation-model` with it
+(`availableBefore` says what a step may read). Client components. The
+platform checks every reference when the automation is saved; a reference
+to a field no earlier step makes is refused with the step and the field
+named.
+
+## Props
+
+### DataInput
+
+- `label`, `value`, `onChange(text)`, `help`, `placeholder`, `mono`,
+  `multiline`, `rows`, `disabled`.
+- `available` — automation-model's `availableBefore(def, stepId,
+  stepTitle)`: `{ steps: [{ id, kind, label }], inLoop }`, and optionally
+  `inputs: [{ name, label }]`. Leave it out and the field is plain text.
+- `samples` — `{ [stepId]: a real output }`, from a run, so the menu can
+  show fields and values; or null.
+
+### DataPairs
+
+- `label`, `value` (`{ name: value }`), `onChange(next)`, `help`,
+  `keyLabel` ("Name"), `addLabel` ("Add a field"), `disabled`, `available`,
+  `samples`.
+
+### DataPicker / DataButton
+
+- `available`, `samples`, `onPick(text)`; `DataButton` also `disabled`.
+
+### Helpers
+
+`menuGroups(available, samples)`, `fieldsOf(sample, base)` and
+`preview(value)`: the menu's data as plain objects.
+
+## Never
+
+- Never put a secret in a value: an account is chosen by kind, and the
+  platform resolves the token when the step runs.
+- Never rename a step to change a reference: a step's id is what a run's
+  rows and an app update match steps by.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { DataInput } from "../components/blocks/data-picker";
+
+const available = { steps: [{ id: "mail", kind: "tool", label: "Read the mail" }], inLoop: false };
+const samples = { mail: { messages: [{ from: "ana@x.com", subject: "Quote" }], count: 1 } };
+
+export default function Note() {
+  const [message, setMessage] = useState("Read {{ steps.mail.output.count }} emails.");
+  return <DataInput label="Message" value={message} onChange={setMessage} multiline rows={3} available={available} samples={samples} />;
+}
+```

package/registry/blocks/data-picker/block.json

@@ -0,0 +1,38 @@
+{
+  "name": "data-picker",
+  "title": "DataPicker",
+  "description": "Mapping data from earlier steps into a field. DataPicker is the menu (this run, this item inside a for-each, the questions a manual run asks, and every earlier step's output, with the fields inside it and a taste of their values where a real run left a sample); DataButton is the { } button that opens it; DataInput is a labelled text field (one line or several) with the menu beside it; DataPairs is a list of name and value rows with a menu on each value. A press inserts {{ steps.mail.output.messages }} where the cursor was.",
+  "useWhen": "A form edits a step's input and the value may come from an earlier step: the step-settings block does this for you. Use it on its own for a field of your own that takes `{{ … }}` references.",
+  "tags": [
+    "automation",
+    "workflow",
+    "data",
+    "mapping",
+    "expression",
+    "variable",
+    "reference",
+    "picker",
+    "insert",
+    "fields",
+    "step input",
+    "n8n",
+    "make"
+  ],
+  "exports": [
+    "DataButton",
+    "DataInput",
+    "DataPairs",
+    "DataPicker",
+    "fieldsOf",
+    "menuGroups",
+    "preview"
+  ],
+  "files": [
+    "index.js",
+    "data-picker.jsx",
+    "fields.js"
+  ],
+  "requires": [
+    "automation-model"
+  ]
+}