makersclaw 0.2.0 → 0.3.0

package/registry/blocks/annotate/demo.jsx

@@ -0,0 +1,135 @@
+"use client";
+
+// Annotate four ways — the gallery's and the smoke test's surface. Not
+// installed into apps.
+//   Bug report        a dashboard screenshot already marked up: a box, a
+//                     highlight, two numbered notes with words; saves and
+//                     sends through callbacks (a switch makes them fail),
+//                     and beside it what an agent receives.
+//   Fresh screenshot  the screenshot alone: the starter templates.
+//   No screenshot     the drop zone (drop, browse or paste).
+//   Read-only         the marked-up screenshot to look at.
+import { useState } from "react";
+import { Card, Switch, TabPanel, Tabs } from "../components/ui";
+import { Annotate, annotationToText } from "../components/blocks/annotate";
+
+// A small made-up analytics dashboard (480 × 300), drawn as flat blocks and
+// encoded as a PNG — a stand-in for a real screenshot.
+const DASHBOARD_PNG = "data:image/png;base64,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";
+const SHOT = { src: DASHBOARD_PNG, width: 480, height: 300 };
+
+// Marks written by hand, colours as TOKENS only (customData.tokens). A pin
+// is an ellipse carrying customData.note, with its number as a bound label.
+const tok = (strokeColor, backgroundColor) => ({ tokens: { strokeColor, ...(backgroundColor ? { backgroundColor } : {}) } });
+const pin = (n, x, y) => [
+  {
+    id: `pin-${n}`,
+    type: "ellipse",
+    x,
+    y,
+    width: 28,
+    height: 28,
+    fillStyle: "solid",
+    strokeWidth: 2,
+    roughness: 0,
+    boundElements: [{ type: "text", id: `pin-${n}-label` }],
+    customData: { note: n, ...tok("destructive", "destructive:soft") },
+  },
+  {
+    id: `pin-${n}-label`,
+    type: "text",
+    x: x + 9,
+    y: y + 5,
+    width: 10,
+    height: 18,
+    text: String(n),
+    fontSize: 14,
+    containerId: `pin-${n}`,
+    textAlign: "center",
+    verticalAlign: "middle",
+    customData: { note: n, ...tok("destructive") },
+  },
+];
+
+const MARKED = {
+  type: "annotation",
+  version: 1,
+  image: SHOT,
+  sketch: {
+    elements: [
+      { id: "box", type: "rectangle", x: 276, y: 156, width: 36, height: 120, strokeWidth: 3, roughness: 0, roundness: { type: 3 }, customData: tok("destructive", "none") },
+      ...pin(1, 300, 124),
+      { id: "band", type: "rectangle", x: 356, y: 219, width: 108, height: 16, fillStyle: "solid", strokeWidth: 1, roughness: 0, opacity: 35, customData: tok("warning", "warning") },
+      ...pin(2, 440, 186),
+    ],
+  },
+  notes: [
+    { n: 1, text: "September is amber and nothing says why. Label it, or keep it blue like the rest." },
+    { n: 2, text: "This refund row shows red with no reason — add a status column so it reads without the colour." },
+  ],
+};
+
+function BugReport() {
+  const [value, setValue] = useState(MARKED);
+  const [fail, setFail] = useState(false);
+  const [sent, setSent] = useState(null);
+  const wait = () => new Promise((r) => setTimeout(r, 500));
+  const save = async () => {
+    await wait();
+    return fail ? { ok: false, error: "The network dropped" } : { ok: true };
+  };
+  const submit = async ({ image, notes, text }) => {
+    await wait();
+    if (fail) return { ok: false, error: "The ticket couldn't be filed" };
+    setSent({ size: Math.max(1, Math.round(image.size / 1024)), count: notes.length, text });
+    return { ok: true };
+  };
+  return (
+    <div className="grid gap-4 xl:grid-cols-[minmax(0,1fr)_18rem]">
+      <Annotate title="Revenue dashboard — feedback" value={value} onChange={setValue} onSave={save} onSubmit={submit} submitLabel="File the bug" />
+      <div className="grid content-start gap-4">
+        <Card title="Callbacks">
+          <Switch id="annotate-fail" label="Make saves and sends fail" checked={fail} onChange={(e) => setFail(e.target.checked)} />
+        </Card>
+        <Card title="What an agent reads">
+          <pre className="whitespace-pre-wrap break-words font-mono text-xs">{annotationToText(value) || "Nothing yet."}</pre>
+          {sent ? (
+            <p className="mt-2 text-xs text-muted-foreground">
+              Sent: a PNG of {sent.size} KB and {sent.count} notes.
+            </p>
+          ) : null}
+        </Card>
+      </div>
+    </div>
+  );
+}
+
+export default function AnnotateDemo() {
+  const [tab, setTab] = useState("bug");
+  return (
+    <div className="grid gap-4">
+      <Tabs
+        aria-label="Annotate variants"
+        value={tab}
+        onChange={setTab}
+        tabs={[
+          { key: "bug", label: "Bug report" },
+          { key: "fresh", label: "Fresh screenshot" },
+          { key: "none", label: "No screenshot" },
+          { key: "read", label: "Read-only" },
+        ]}
+      />
+      <TabPanel tab={tab} value={tab}>
+        {tab === "bug" ? (
+          <BugReport />
+        ) : tab === "fresh" ? (
+          <Annotate title="Onboarding screen" defaultValue={{ image: SHOT }} onSubmit={async () => ({ ok: true })} />
+        ) : tab === "none" ? (
+          <Annotate title="Report a problem" onSubmit={async () => ({ ok: true })} submitLabel="Send to support" />
+        ) : (
+          <Annotate title="Revenue dashboard — feedback" defaultValue={MARKED} readOnly />
+        )}
+      </TabPanel>
+    </div>
+  );
+}

package/registry/blocks/annotate/index.js

@@ -0,0 +1,15 @@
+// The Annotate block — `makersclaw add annotate`. Fixed: compose it
+// through its props (README.md beside this file). Built on sketch-canvas
+// (the canvas underneath); the helpers read an annotation anywhere, the
+// server included.
+export { Annotate, ANNOTATE_TOOLS } from "./annotate";
+export {
+  ANNOTATE_TEMPLATES,
+  emptyAnnotation,
+  toAnnotation,
+  annotationNotes,
+  annotationToText,
+  noteMarkers,
+  nextNoteNumber,
+  markerSkeleton,
+} from "./annotate-data";

package/registry/blocks/approval-request/README.md

@@ -0,0 +1,116 @@
+# ApprovalRequest
+
+One request waiting on a decision: what is asked for (label and value
+facts, the amount in large type), who asked and when, why, and Approve /
+Reject. Reject asks for a reason the requester will see. The decision
+goes out through your callbacks; while one runs its button spins, when it
+fails the card says why and the buttons stay, and once it lands the card
+shows the outcome ("Approved by you · 23 September 2026") in their place.
+
+```jsx
+import { ApprovalRequest } from "../components/blocks/approval-request";   // a Makersclaw app ("./blocks/approval-request" from components/)
+import { ApprovalRequest } from "@/components/makersclaw/blocks/approval-request";   // a shadcn project
+```
+
+A client component. Load the request in the server surface (README §4)
+and pass its fields in.
+
+## The data
+
+- `details` — the card's facts, in order:
+  `[{ label, value, icon?, emphasis? }]`. `value` is a string or a node;
+  `icon` is a kit `Icon` name; `emphasis` sets the value large (the
+  amount).
+- `sections` — `variant="page"` only, the detail beside the card:
+  `[{ title, fields: [{ label, value, emphasis? }] }]`.
+- `requester` — `{ name, role?, src? }` (`src` a picture URL).
+
+## Props
+
+- `title` — what is asked for ("Linear Business", "Refund for order
+  20931"). Without it (and not `loading`) the block shows `emptyLabel`.
+- `onApprove()` — save the yes. Return `{ ok: true }` or
+  `{ ok: false, error }`; a throw counts as failed and its message shows.
+- `onReject(reason)` — save the no, with the reason typed (a trimmed
+  string, "" when `reasonRequired` is off). Same return as `onApprove`.
+  Leave either out and its button is not drawn.
+- `variant` — `"card"` (default: the card alone, with the requester, the
+  date and the reason why) or `"page"`: a heading, the `sections` and "The
+  request" (requester, date, why) on the left, the card on the right
+  (under them on a phone), sticky from 1024px.
+- `status` — `"pending"` (default) · `"approved"` · `"rejected"`. The
+  block shows its own outcome as soon as a decision saves; a new
+  `status` from you replaces it.
+- `decidedBy` · `decidedAt` · `decisionNote` — for a request decided
+  before: who, when, and the reason, shown under the outcome.
+- `kind` — a small badge beside the title ("Per seat", "Refund").
+- `requestedAt` — an ISO date or a `Date`.
+- `justification` — the requester's reason, as a paragraph.
+- `reasonRequired` — default `true`: Reject opens a reason field and
+  sends only when it is filled. `false`: Reject sends at once.
+- `approveLabel` · `rejectLabel` — default "Approve" / "Reject"
+  ("Refund €149.00", "Decline").
+- `heading` · `description` — `page`: the page's title (default `title`)
+  and the line under it.
+- `formatDate(value)` — how a date reads; default the viewer's long date
+  ("21 September 2026").
+- `loading` — a skeleton card while the request loads.
+- `emptyLabel` — default "Nothing is waiting for a decision.".
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/PurchaseApproval.jsx — client
+"use client";
+import { useRouter } from "next/navigation";
+import { updateRow } from "../lib/actions";
+import { ApprovalRequest } from "./blocks/approval-request";
+
+const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
+
+export default function PurchaseApproval({ request }) {
+  const router = useRouter();
+  const decide = (status, reason) =>
+    updateRow({ source: "public.purchase_requests", id: request.id, patch: { status, reason: reason ?? null }, detail: request.product }).then(
+      (res) => (res.ok && router.refresh(), res),
+    );
+  return (
+    <ApprovalRequest
+      title={request.product}
+      kind={request.pricing}
+      details={[
+        { label: "Starts", value: request.starts_on, icon: "calendar" },
+        { label: "Seats", value: `${request.seats} people`, icon: "users" },
+        { label: "Yearly cost", value: usd.format(request.amount), icon: "dollar", emphasis: true },
+      ]}
+      requester={{ name: request.requested_by, role: request.team }}
+      requestedAt={request.created_at}
+      justification={request.why}
+      status={request.status}
+      decidedBy={request.decided_by}
+      decidedAt={request.decided_at}
+      decisionNote={request.reason}
+      onApprove={() => decide("approved")}
+      onReject={(reason) => decide("rejected", reason)}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- List many requests: put them in a `data-table` and open one in this
+  block (a `Sheet`), or render one per row.
+- Take a decision in several steps (two approvers, a delegate): `status`
+  is one of three.
+- Edit the request: its facts are read-only here.
+
+A request it cannot be is your own component in `components/`, built
+from the kit — not an edit to this block. Its files are fixed: `npm run
+check` refuses a change, and `makersclaw add approval-request` restores
+them.
+
+## Credits
+
+Ported from Creative Tim UI (https://github.com/creativetimofficial/ui, software-purchase-01 and software-purchase-card, MIT), rewritten on the Makersclaw kit.

package/registry/blocks/approval-request/approval-request.jsx

@@ -0,0 +1,386 @@
+"use client";
+
+import { useEffect, useId, useState } from "react";
+import { Avatar, Badge, Button, Empty, Field, Icon, Notice, Separator, Skeleton, Textarea, cx } from "../../ui";
+
+// ApprovalRequest — one request waiting on a decision: what is asked for
+// (label/value facts), who asked and when, why, and Approve / Reject. The
+// decision goes out through `onApprove()` / `onReject(reason)`; the
+// block shows it working, shows a failure, and once it lands shows the
+// outcome in place of the buttons.
+
+const STATUS = {
+  pending: { tone: "warning", label: "Pending approval" },
+  approved: { tone: "success", label: "Approved" },
+  rejected: { tone: "danger", label: "Rejected" },
+};
+
+function defaultFormat(value) {
+  if (!value) return "";
+  const d = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(d.getTime())) return String(value);
+  return new Intl.DateTimeFormat(undefined, { dateStyle: "long" }).format(d);
+}
+
+function When({ value, format }) {
+  if (!value) return null;
+  const iso = value instanceof Date ? value.toISOString() : String(value);
+  return (
+    <time dateTime={iso} suppressHydrationWarning>
+      {format(value)}
+    </time>
+  );
+}
+
+function StatusBadge({ status }) {
+  const s = STATUS[status] ?? STATUS.pending;
+  return (
+    <Badge tone={s.tone} variant="soft">
+      {s.label}
+    </Badge>
+  );
+}
+
+function Requester({ requester, requestedAt, format }) {
+  if (!requester && !requestedAt) return null;
+  return (
+    <div className="flex min-w-0 items-center gap-2 text-sm text-muted-foreground">
+      {requester ? <Avatar name={requester.name} src={requester.src} size="xs" /> : null}
+      <p className="min-w-0">
+        {requester ? (
+          <>
+            <span className="font-medium text-foreground">{requester.name}</span>
+            {requester.role ? `, ${requester.role}` : ""}
+          </>
+        ) : null}
+        {requester && requestedAt ? " · " : null}
+        <When value={requestedAt} format={format} />
+      </p>
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   The card: facts and the decision
+   ------------------------------------------------------------------------ */
+
+function DecisionCard({
+  title,
+  kind,
+  details,
+  requester,
+  requestedAt,
+  justification,
+  status,
+  decidedBy,
+  decidedAt,
+  decisionNote,
+  onApprove,
+  onReject,
+  reasonRequired,
+  approveLabel,
+  rejectLabel,
+  format,
+  showContext,
+  className,
+}) {
+  const [local, setLocal] = useState(null);
+  const [mode, setMode] = useState("idle"); // idle · rejecting
+  const [busy, setBusy] = useState(null); // approve · reject
+  const [reason, setReason] = useState("");
+  const [error, setError] = useState(null);
+  const reasonId = useId();
+
+  // A new status from the app wins over what the block showed meanwhile.
+  useEffect(() => setLocal(null), [status]);
+
+  const shown = local?.status ?? status ?? "pending";
+  const pending = shown === "pending";
+  const facts = (details ?? []).filter(Boolean);
+
+  async function decide(kindOf) {
+    const fn = kindOf === "approve" ? onApprove : onReject;
+    if (!fn) return;
+    setBusy(kindOf);
+    setError(null);
+    let res;
+    try {
+      res = await fn(kindOf === "reject" ? reason.trim() : undefined);
+    } catch (e) {
+      res = { ok: false, error: e?.message };
+    }
+    setBusy(null);
+    if (res?.ok) {
+      setLocal({ status: kindOf === "approve" ? "approved" : "rejected", note: kindOf === "reject" ? reason.trim() : undefined, at: new Date() });
+      setMode("idle");
+    } else {
+      setError(res?.error || (kindOf === "approve" ? "The approval was not saved. Try again." : "The rejection was not saved. Try again."));
+    }
+  }
+
+  const note = local?.note ?? decisionNote;
+  const at = local?.at ?? decidedAt;
+  const by = local ? "you" : decidedBy;
+
+  return (
+    <section aria-label={title} className={cx("grid gap-4 rounded-lg border border-border bg-card p-4 text-card-foreground sm:p-5", className)}>
+      <header className="grid gap-2">
+        <div className="flex flex-wrap items-start justify-between gap-2">
+          <h2 className="min-w-0 text-lg font-semibold leading-tight">{title}</h2>
+          <div className="flex flex-wrap gap-1.5">
+            {kind ? <Badge variant="soft">{kind}</Badge> : null}
+            <StatusBadge status={shown} />
+          </div>
+        </div>
+        {showContext ? <Requester requester={requester} requestedAt={requestedAt} format={format} /> : null}
+      </header>
+
+      {facts.length ? (
+        <dl className="grid gap-4">
+          {facts.map((f, i) => (
+            <div key={f.label ?? i} className="flex items-center gap-3">
+              {f.icon ? (
+                <span className="flex size-8 shrink-0 items-center justify-center rounded-md bg-muted text-muted-foreground">
+                  <Icon name={f.icon} size={16} />
+                </span>
+              ) : null}
+              <div className="grid min-w-0 gap-0.5">
+                <dt className="text-xs text-muted-foreground">{f.label}</dt>
+                <dd data-nums className={cx("min-w-0 break-words", f.emphasis ? "text-xl font-semibold" : "text-sm font-medium")}>
+                  {f.value}
+                </dd>
+              </div>
+            </div>
+          ))}
+        </dl>
+      ) : null}
+
+      {showContext && justification ? (
+        <div className="grid gap-1">
+          <p className="text-xs text-muted-foreground">Why</p>
+          <p className="text-sm leading-relaxed text-foreground">{justification}</p>
+        </div>
+      ) : null}
+
+      <Separator />
+
+      {pending ? (
+        mode === "rejecting" ? (
+          <form
+            className="grid gap-3"
+            onSubmit={(e) => {
+              e.preventDefault();
+              if (reasonRequired && !reason.trim()) return;
+              decide("reject");
+            }}
+          >
+            <Field id={reasonId} label="Why is it rejected?" hint="The requester sees this." required={reasonRequired}>
+              <Textarea
+                id={reasonId}
+                rows={3}
+                value={reason}
+                onChange={(e) => setReason(e.target.value)}
+                autoFocus
+                disabled={busy !== null}
+                placeholder="Over this quarter's budget; ask again in January."
+              />
+            </Field>
+            <div className="flex flex-wrap justify-end gap-2">
+              <Button
+                variant="quiet"
+                onClick={() => {
+                  setMode("idle");
+                  setError(null);
+                }}
+                disabled={busy !== null}
+              >
+                Back
+              </Button>
+              <Button type="submit" variant="danger" loading={busy === "reject"} disabled={reasonRequired && !reason.trim()}>
+                {rejectLabel}
+              </Button>
+            </div>
+          </form>
+        ) : (
+          <div className="flex gap-3">
+            {onReject ? (
+              <Button
+                className="flex-1"
+                onClick={() => {
+                  setError(null);
+                  if (reasonRequired) setMode("rejecting");
+                  else decide("reject");
+                }}
+                loading={busy === "reject"}
+                disabled={busy !== null}
+              >
+                {rejectLabel}
+              </Button>
+            ) : null}
+            {onApprove ? (
+              <Button className="flex-1" variant="primary" icon="check" onClick={() => decide("approve")} loading={busy === "approve"} disabled={busy !== null}>
+                {approveLabel}
+              </Button>
+            ) : null}
+          </div>
+        )
+      ) : (
+        <div role="status" className="flex items-start gap-3 text-sm">
+          <Icon name={shown === "approved" ? "circle-check" : "circle-x"} size={20} className={cx("mt-0.5 shrink-0", shown === "approved" ? "text-success" : "text-destructive")} />
+          <div className="min-w-0">
+            <p className="font-medium">
+              {shown === "approved" ? "Approved" : "Rejected"}
+              {by ? ` by ${by}` : ""}
+              {at ? (
+                <span className="font-normal text-muted-foreground">
+                  {" · "}
+                  <When value={at} format={format} />
+                </span>
+              ) : null}
+            </p>
+            {note ? <p className="mt-0.5 text-muted-foreground">{note}</p> : null}
+          </div>
+        </div>
+      )}
+
+      {error ? (
+        <Notice tone="danger" onDismiss={() => setError(null)}>
+          {error}
+        </Notice>
+      ) : null}
+    </section>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   ApprovalRequest
+   ------------------------------------------------------------------------ */
+
+export function ApprovalRequest({
+  variant = "card",
+  title,
+  kind,
+  details,
+  sections,
+  requester,
+  requestedAt,
+  justification,
+  status = "pending",
+  decidedBy,
+  decidedAt,
+  decisionNote,
+  onApprove,
+  onReject,
+  reasonRequired = true,
+  approveLabel = "Approve",
+  rejectLabel = "Reject",
+  heading,
+  description,
+  formatDate = defaultFormat,
+  loading = false,
+  emptyLabel = "Nothing is waiting for a decision.",
+  className,
+}) {
+  const card = {
+    title,
+    kind,
+    details,
+    requester,
+    requestedAt,
+    justification,
+    status,
+    decidedBy,
+    decidedAt,
+    decisionNote,
+    onApprove,
+    onReject,
+    reasonRequired,
+    approveLabel,
+    rejectLabel,
+    format: formatDate,
+  };
+
+  if (loading) {
+    return (
+      <div aria-busy="true" aria-label="Loading the request" className={cx("grid w-full max-w-md gap-4 rounded-lg border border-border bg-card p-5", className)}>
+        <Skeleton className="w-2/3" />
+        {[0, 1, 2].map((i) => (
+          <div key={i} className="flex items-center gap-3">
+            <Skeleton shape="rect" className="size-8" />
+            <Skeleton className="w-1/2" />
+          </div>
+        ))}
+        <div className="flex gap-3">
+          <Skeleton shape="rect" className="h-11 flex-1" />
+          <Skeleton shape="rect" className="h-11 flex-1" />
+        </div>
+      </div>
+    );
+  }
+  if (!title) return <Empty icon="inbox" title="No request" body={emptyLabel} className={className} />;
+
+  if (variant !== "page") {
+    return <DecisionCard {...card} showContext className={cx("w-full max-w-md", className)} />;
+  }
+
+  const groups = (sections ?? []).filter(Boolean);
+  return (
+    <div className={cx("grid gap-8 lg:grid-cols-[minmax(0,1fr)_24rem] lg:items-start", className)}>
+      <div className="grid min-w-0 gap-6">
+        <div className="grid gap-1">
+          <h1 className="text-2xl font-semibold leading-tight">{heading ?? title}</h1>
+          {description ? <p className="text-muted-foreground">{description}</p> : null}
+        </div>
+        {groups.map((g, gi) => (
+          <section key={g.title ?? gi} className="grid gap-4 border-t border-border pt-6">
+            {g.title ? <h2 className="text-lg font-semibold">{g.title}</h2> : null}
+            <dl className="grid gap-4 sm:grid-cols-2">
+              {(g.fields ?? []).filter(Boolean).map((f, fi) => (
+                <div key={f.label ?? fi} className="grid min-w-0 gap-1">
+                  <dt className="text-sm font-medium">{f.label}</dt>
+                  <dd className={cx("min-w-0 break-words text-muted-foreground", f.emphasis && "font-semibold text-foreground")}>{f.value}</dd>
+                </div>
+              ))}
+            </dl>
+          </section>
+        ))}
+        {requester || requestedAt || justification ? (
+          <section className="grid gap-4 border-t border-border pt-6">
+            <h2 className="text-lg font-semibold">The request</h2>
+            <dl className="grid gap-4 sm:grid-cols-2">
+              {requester ? (
+                <div className="grid min-w-0 gap-1">
+                  <dt className="text-sm font-medium">Requested by</dt>
+                  <dd className="flex min-w-0 items-center gap-2 text-muted-foreground">
+                    <Avatar name={requester.name} src={requester.src} size="xs" />
+                    <span className="min-w-0">
+                      {requester.name}
+                      {requester.role ? ` (${requester.role})` : ""}
+                    </span>
+                  </dd>
+                </div>
+              ) : null}
+              {requestedAt ? (
+                <div className="grid gap-1">
+                  <dt className="text-sm font-medium">Requested on</dt>
+                  <dd className="text-muted-foreground">
+                    <When value={requestedAt} format={formatDate} />
+                  </dd>
+                </div>
+              ) : null}
+              {justification ? (
+                <div className="grid gap-1 sm:col-span-2">
+                  <dt className="text-sm font-medium">Why</dt>
+                  <dd className="text-sm leading-relaxed text-muted-foreground">{justification}</dd>
+                </div>
+              ) : null}
+            </dl>
+          </section>
+        ) : null}
+      </div>
+      <div className="lg:sticky lg:top-6">
+        <DecisionCard {...card} showContext={false} />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/approval-request/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "approval-request",
+  "title": "ApprovalRequest",
+  "description": "One request waiting on a decision: what is asked for as label/value facts (an amount in large type), who asked and when, why, a status badge, and Approve / Reject (reject asks for a reason). The decision goes out through async onApprove / onReject; the block shows it working, a failure, then the outcome in place of the buttons. A card alone, or a page of detail sections beside the card.",
+  "useWhen": "Someone must say yes or no to one thing another person asked for: a purchase, a refund, time off, a discount, an access request, a published post. Not for a queue of many requests (a data-table with row actions) or a yes/no about the founder's own action (kit Confirm).",
+  "tags": ["approval", "approve", "reject", "request", "review", "decision", "purchase", "expense", "refund", "time off", "sign off", "pending"],
+  "exports": ["ApprovalRequest"],
+  "files": ["index.js", "approval-request.jsx"],
+  "requires": []
+}