makersclaw 0.1.0 → 0.3.0

package/registry/blocks/testimonials/testimonials.jsx

@@ -0,0 +1,430 @@
+"use client";
+
+import { useState } from "react";
+import { Avatar, Button, Carousel, Empty, Icon, Image, Kicker, Rating, Skeleton, Stat, StatGroup, cx } from "../../ui";
+
+// Testimonials — a marketing section of customer quotes: who said it
+// (name, role, company, face or logo), the quote, an optional star
+// rating, an optional "see it on X" source, and optional headline
+// numbers beside them. Five layouts over the same rows: a grid of cards,
+// one large quote, a switcher (press a face to swap the quote), a
+// carousel (swipe, arrows, dots), and a carousel over a picture.
+//
+//   <Testimonials title="Loved by small teams" items={quotes}
+//                 stats={[{ label: "Teams", value: "4,200+" }]} />
+//
+// README.md beside this file lists every prop.
+
+const COLUMNS = {
+  1: "grid-cols-1",
+  2: "grid-cols-1 sm:grid-cols-2",
+  3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+  4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-4",
+};
+
+const LOOKS = {
+  card: "rounded-lg border border-border bg-card text-card-foreground p-6",
+  raised: "rounded-lg border border-border bg-card text-card-foreground p-6 shadow-lg",
+  plain: "",
+};
+
+// A network's name and the brand glyph drawn for it.
+const NETWORKS = {
+  x: { label: "X", icon: "x-logo" },
+  linkedin: { label: "LinkedIn", icon: "linkedin" },
+  instagram: { label: "Instagram", icon: "instagram" },
+  youtube: { label: "YouTube", icon: "youtube" },
+  facebook: { label: "Facebook", icon: "facebook" },
+  github: { label: "GitHub", icon: "github" },
+  google: { label: "Google", icon: "google" },
+};
+
+const keyOf = (item, i) => item.id ?? `${i}-${item.name ?? ""}`;
+const roleLine = (item) => [item.role, item.company].filter(Boolean).join(", ");
+
+function Header({ kicker, title, description, align, action }) {
+  if (!kicker && !title && !description && !action) return null;
+  const center = align === "center";
+  return (
+    <div className={cx("grid gap-3", center ? "mx-auto max-w-2xl justify-items-center text-center" : "max-w-2xl")}>
+      {kicker ? <Kicker>{kicker}</Kicker> : null}
+      {title ? <h2 className="text-balance text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h2> : null}
+      {description ? <p className="text-pretty text-base text-muted-foreground sm:text-lg">{description}</p> : null}
+      {action ? <div className="mt-2">{action}</div> : null}
+    </div>
+  );
+}
+
+function ActionButton({ action, className }) {
+  if (!action) return null;
+  return (
+    <Button variant="secondary" href={action.href} onClick={action.onClick} icon={action.icon ?? "plus"} className={className}>
+      {action.label}
+    </Button>
+  );
+}
+
+// Name (with a verified mark), then role and company, or the date.
+function Byline({ item, size = "md", center, avatar = true }) {
+  const sub = roleLine(item);
+  return (
+    <figcaption className={cx("flex min-w-0 gap-3", center ? "flex-col items-center text-center" : "items-center")}>
+      {avatar ? <Avatar name={item.name} src={item.avatar} size={size === "lg" ? "lg" : "md"} /> : null}
+      <div className="min-w-0">
+        <p className={cx("flex items-center gap-1.5 font-semibold", center && "justify-center")}>
+          <span className="min-w-0 truncate">{item.name}</span>
+          {item.verified ? (
+            <span className="inline-flex shrink-0 text-primary">
+              <Icon name="circle-check" size={16} />
+              <span className="sr-only">Verified customer</span>
+            </span>
+          ) : null}
+        </p>
+        {sub ? <p className="text-sm text-muted-foreground">{sub}</p> : null}
+        {item.date && !item.source ? <p className="text-sm text-muted-foreground">{item.date}</p> : null}
+      </div>
+    </figcaption>
+  );
+}
+
+function Stars({ item, center }) {
+  if (item.rating == null) return null;
+  return (
+    <div className={cx("flex", center && "justify-center")}>
+      <Rating value={item.rating} size="sm" label={`${item.name}'s rating`} />
+    </div>
+  );
+}
+
+// "View on X" and the date, under a quote that was posted somewhere.
+function Source({ item }) {
+  const s = item.source;
+  if (!s) return null;
+  const net = NETWORKS[s.network] ?? { label: s.label ?? "the source", icon: "external" };
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-1 border-t border-border pt-4 text-sm">
+      {s.href ? (
+        <Button variant="link" size="sm" href={s.href} tone="muted">
+          View on {s.label ?? net.label} <Icon name={net.icon} size={14} />
+        </Button>
+      ) : (
+        <span className="inline-flex items-center gap-1.5 text-muted-foreground">
+          On {s.label ?? net.label} <Icon name={net.icon} size={14} />
+        </span>
+      )}
+      {item.date ? <span className="text-muted-foreground">{item.date}</span> : null}
+    </div>
+  );
+}
+
+function QuoteCard({ item, look, center, bylineTop, quoteMark }) {
+  const byline = <Byline item={item} center={center} size={bylineTop && center ? "lg" : "md"} />;
+  return (
+    <figure
+      className={cx(
+        "flex h-full min-w-0 flex-col gap-4",
+        LOOKS[look] ?? LOOKS.card,
+        item.highlight && look !== "plain" && "border-primary ring-1 ring-primary",
+        center && "items-center text-center",
+      )}
+    >
+      {item.logo ? <div className={cx("flex min-h-10 items-center", center && "justify-center")}>{item.logo}</div> : null}
+      {bylineTop ? byline : null}
+      {!bylineTop ? <Stars item={item} center={center} /> : null}
+      {quoteMark ? <Icon name="quote" size={28} className="text-muted-foreground/50" /> : null}
+      <blockquote className={cx("text-pretty leading-relaxed", look === "plain" ? "text-muted-foreground" : "text-foreground")}>
+        {item.quote}
+      </blockquote>
+      <div className={cx("mt-auto grid gap-4", center && "justify-items-center")}>
+        {bylineTop ? <Stars item={item} center={center} /> : byline}
+        {item.href ? (
+          <Button variant="link" size="sm" href={item.href}>
+            {item.hrefLabel ?? "Read the story"} <Icon name="arrow-right" size={14} />
+          </Button>
+        ) : null}
+        <Source item={item} />
+      </div>
+    </figure>
+  );
+}
+
+function StatsStrip({ stats, center, className }) {
+  if (!stats?.length) return null;
+  return (
+    <StatGroup variant="divided" label="In numbers" className={cx(center && "mx-auto w-full max-w-3xl", className)}>
+      {stats.map((s, i) => (
+        <Stat key={s.label ?? i} label={s.label} value={s.value} unit={s.unit} caption={s.caption} size="lg" />
+      ))}
+    </StatGroup>
+  );
+}
+
+function Loading({ columns }) {
+  return (
+    <div aria-busy="true" aria-label="Loading testimonials" className={cx("grid gap-6", COLUMNS[columns] ?? COLUMNS[3])}>
+      {[0, 1, 2].map((i) => (
+        <div key={i} className="grid gap-4 rounded-lg border border-border bg-card p-6">
+          <Skeleton className="w-24" />
+          <Skeleton className="w-full" />
+          <Skeleton className="w-5/6" />
+          <Skeleton className="w-2/3" />
+          <div className="flex items-center gap-3 pt-2">
+            <Skeleton shape="circle" className="size-10" />
+            <div className="grid flex-1 gap-2">
+              <Skeleton className="w-1/2" />
+              <Skeleton className="w-1/3" />
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function Grid({ items, columns, look, center, bylineTop, quoteMark, focusOnHover, action }) {
+  return (
+    <div
+      className={cx(
+        "grid gap-6",
+        COLUMNS[columns] ?? COLUMNS[3],
+        // One card lit, the rest dimmed, while the pointer is over one.
+        focusOnHover && "[&:has(>*:hover)>*:not(:hover)]:opacity-50 [&>*]:transition-opacity motion-reduce:[&>*]:transition-none",
+      )}
+    >
+      {items.map((item, i) => (
+        <div key={keyOf(item, i)} className={cx("min-w-0", item.wide && "sm:col-span-full")}>
+          <QuoteCard item={item} look={look} center={center} bylineTop={bylineTop} quoteMark={quoteMark} />
+        </div>
+      ))}
+      {action ? (
+        <div className="grid min-h-48 min-w-0">
+          <Button
+            variant="secondary"
+            href={action.href}
+            onClick={action.onClick}
+            className="h-full w-full flex-col gap-3 rounded-lg border-dashed"
+          >
+            <span className="grid size-14 place-items-center rounded-full bg-muted">
+              <Icon name={action.icon ?? "plus"} size={24} />
+            </span>
+            {action.label}
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+// One quote, large: a picture or a logo on one side, the words on the
+// other; with `stats`, the numbers take the picture's place.
+function Single({ item, kicker, title, description, stats, look, action }) {
+  const heading = item.title ?? title;
+  const media = item.image ? (
+    <Image src={item.image} alt={item.imageAlt ?? ""} ratio="square" rounded="lg" className="w-full max-w-sm" />
+  ) : item.logo && look === "plain" ? (
+    <div className="grid min-h-40 place-items-center rounded-lg bg-muted p-8 text-2xl">{item.logo}</div>
+  ) : null;
+  const body = (
+    <div className="grid min-w-0 gap-5">
+      {kicker ? <Kicker>{kicker}</Kicker> : null}
+      {heading ? <h2 className="text-balance text-3xl font-semibold tracking-tight sm:text-4xl">{heading}</h2> : null}
+      {description && !heading ? <p className="text-muted-foreground">{description}</p> : null}
+      <Stars item={item} />
+      <blockquote className="text-pretty text-lg leading-relaxed text-foreground sm:text-xl">
+        <Icon name="quote" size={24} className="mb-3 block text-muted-foreground/50" />
+        {item.quote}
+      </blockquote>
+      <div className="flex flex-wrap items-center justify-between gap-4">
+        <Byline item={item} size="lg" />
+        {item.logo && look !== "plain" ? <div className="shrink-0">{item.logo}</div> : null}
+      </div>
+      {item.href ? (
+        <div>
+          <Button variant="link" href={item.href}>
+            {item.hrefLabel ?? "Read the story"} <Icon name="arrow-right" size={14} />
+          </Button>
+        </div>
+      ) : null}
+      {action ? (
+        <div>
+          <ActionButton action={action} />
+        </div>
+      ) : null}
+    </div>
+  );
+  const side = stats?.length ? (
+    <div className="grid content-center gap-6 sm:grid-cols-3 md:grid-cols-1 md:border-l md:border-border md:pl-10">
+      {stats.map((s, i) => (
+        <Stat key={s.label ?? i} label={s.label} value={s.value} unit={s.unit} caption={s.caption} size="lg" />
+      ))}
+    </div>
+  ) : media;
+  return (
+    <figure
+      className={cx(
+        "grid items-center gap-8",
+        side && "md:grid-cols-[minmax(0,1fr)_minmax(0,2fr)]",
+        stats?.length && "md:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]",
+        look !== "plain" && "rounded-xl border border-border bg-card p-6 text-card-foreground sm:p-10",
+      )}
+    >
+      {stats?.length ? body : side}
+      {stats?.length ? side : body}
+    </figure>
+  );
+}
+
+// Press a face to show that person's quote.
+function Switcher({ items, title, index, onIndex }) {
+  const item = items[index] ?? items[0];
+  return (
+    <div className="grid items-center gap-8 md:grid-cols-[minmax(0,2fr)_minmax(0,1fr)]">
+      <div className="grid min-w-0 gap-5">
+        {title ? <h2 className="text-balance text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h2> : null}
+        <figure className="grid gap-5" aria-live="polite">
+          <Stars item={item} />
+          <blockquote className="max-w-2xl text-pretty text-lg leading-relaxed text-muted-foreground">{item.quote}</blockquote>
+          <Byline item={item} avatar={false} />
+        </figure>
+        <div role="group" aria-label="Choose a customer" className="flex flex-wrap items-center gap-2">
+          {items.map((it, i) => (
+            <Button
+              key={keyOf(it, i)}
+              variant="quiet"
+              iconOnly
+              aria-pressed={i === index}
+              aria-label={`${it.name}${it.company ? `, ${it.company}` : ""}`}
+              onClick={() => onIndex(i)}
+              className={cx("rounded-lg transition-opacity", i === index ? "ring-2 ring-primary" : "opacity-60 hover:opacity-100")}
+            >
+              <Avatar name={it.name} src={it.avatar} shape="square" size="md" label="" />
+            </Button>
+          ))}
+        </div>
+      </div>
+      <div className="hidden justify-center md:flex">
+        {item.image ? (
+          <Image src={item.image} alt={item.imageAlt ?? item.name} ratio="portrait" rounded="lg" className="w-full max-w-72" />
+        ) : (
+          <div className="grid aspect-[3/4] w-full max-w-72 place-items-center rounded-lg bg-muted">
+            <Avatar name={item.name} src={item.avatar} size="lg" className="scale-150" />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function Slide({ item }) {
+  return (
+    <figure className="mx-auto grid max-w-3xl justify-items-center gap-6 px-2 py-6 text-center sm:px-12">
+      {item.logo ? <div className="flex min-h-10 items-center justify-center text-xl">{item.logo}</div> : null}
+      <Stars item={item} center />
+      <blockquote className="text-pretty text-lg font-medium leading-relaxed sm:text-2xl">&ldquo;{item.quote}&rdquo;</blockquote>
+      <Byline item={item} center />
+    </figure>
+  );
+}
+
+function Slides({ items, look, background, backgroundAlt, onIndex }) {
+  const carousel = (
+    <Carousel label="Customer quotes" loop onChange={onIndex}>
+      {items.map((item, i) => (
+        <Slide key={keyOf(item, i)} item={item} />
+      ))}
+    </Carousel>
+  );
+  if (!background && look === "plain") return carousel;
+  if (!background)
+    return <div className={cx(LOOKS[look] ?? LOOKS.card, "rounded-xl px-2 py-6 sm:px-8")}>{carousel}</div>;
+  return (
+    <div className="relative isolate overflow-hidden rounded-xl border border-border">
+      <div className="absolute inset-0 -z-10">
+        <Image src={background} alt={backgroundAlt ?? ""} rounded="none" className="h-full w-full" />
+      </div>
+      <div className="bg-background/85 px-4 py-8 backdrop-blur-sm sm:px-10 sm:py-12">{carousel}</div>
+    </div>
+  );
+}
+
+export function Testimonials({
+  items,
+  layout = "grid",
+  kicker,
+  title,
+  description,
+  align,
+  stats,
+  columns = 3,
+  look = "card",
+  cardAlign = "start",
+  byline = "bottom",
+  quoteMark = false,
+  focusOnHover = false,
+  action,
+  background,
+  backgroundAlt,
+  defaultIndex = 0,
+  onIndexChange,
+  loading = false,
+  empty,
+  label,
+  className,
+}) {
+  const list = (items ?? []).filter((it) => it && it.quote);
+  const [index, setIndex] = useState(Math.min(defaultIndex, Math.max(0, list.length - 1)));
+  const pick = (i) => {
+    setIndex(i);
+    onIndexChange?.(i);
+  };
+  const headAlign = align ?? (layout === "switcher" || layout === "single" ? "start" : "center");
+  const singleOwnsHeader = layout === "single" || layout === "switcher";
+
+  let body;
+  if (loading) body = <Loading columns={columns} />;
+  else if (list.length === 0)
+    body = (
+      <Empty
+        icon="quote"
+        title={empty?.title ?? "No reviews yet"}
+        body={empty?.body ?? "What customers say about you will show here."}
+        action={action ? <ActionButton action={action} /> : null}
+      />
+    );
+  else if (layout === "single")
+    body = <Single item={list[index] ?? list[0]} kicker={kicker} title={title} description={description} stats={stats} look={look} action={action} />;
+  else if (layout === "switcher") body = <Switcher items={list} title={title} index={Math.min(index, list.length - 1)} onIndex={pick} />;
+  else if (layout === "carousel") body = <Slides items={list} look={look} background={background} backgroundAlt={backgroundAlt} onIndex={onIndexChange} />;
+  else
+    body = (
+      <Grid
+        items={list}
+        columns={columns}
+        look={look}
+        center={cardAlign === "center"}
+        bylineTop={byline === "top"}
+        quoteMark={quoteMark}
+        focusOnHover={focusOnHover}
+        action={action}
+      />
+    );
+
+  const showHeader = !singleOwnsHeader || loading || list.length === 0;
+  return (
+    <section aria-label={label ?? (typeof title === "string" ? title : "Testimonials")} className={cx("px-4 py-16 sm:px-6 sm:py-20", className)}>
+      <div className="mx-auto grid w-full max-w-6xl gap-10 sm:gap-12">
+        {showHeader ? (
+          <Header
+            kicker={kicker}
+            title={title}
+            description={description}
+            align={headAlign}
+            action={list.length && layout === "carousel" ? <ActionButton action={action} /> : null}
+          />
+        ) : null}
+        {!loading && list.length && layout !== "single" ? <StatsStrip stats={stats} center={headAlign === "center"} /> : null}
+        {body}
+      </div>
+    </section>
+  );
+}

package/registry/blocks/transaction-list/README.md

@@ -0,0 +1,126 @@
+# TransactionList
+
+Money records as a plain list in a card. There are two variants:
+
+- `history` (the default) — payments in and out, grouped by month. Each
+  row has a mark (received, paid, pending, failed, refunded), the name,
+  the date and a signed amount.
+- `invoices` — one row per invoice: its number and date, a badge (Paid,
+  Due in 12 days, Due today, 3 days overdue, Void), the amount and a
+  download button.
+
+The header can hold a date-range filter and an Export button. It is a
+list, not a table: there are no columns and no sorting, so the rows show
+in the order they come in (newest first, usually).
+
+```jsx
+import { TransactionList } from "../components/blocks/transaction-list";   // a Makersclaw app ("./blocks/transaction-list" from components/)
+import { TransactionList } from "@/components/makersclaw/blocks/transaction-list";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the rows in the server surface (README §4).
+
+## The data
+
+A history row:
+
+```js
+{ id: "tx_1", name: "Northwind Ltd", date: "2026-09-21T12:30:00Z", amount: 2500, direction: "in", status: "completed", description: "Invoice #1042" }
+```
+
+- `date` — `"YYYY-MM-DD"`, or an ISO timestamp (then the time shows too).
+  Months group by its first seven characters.
+- `amount` — a number in the currency's major unit. The sign is drawn
+  from `direction` (`"in"` · `"out"`); without one, a negative amount is
+  money out.
+- `status` — `completed` (the default), `pending`, `failed` (struck
+  through), `refunded`.
+- `description` — a short line before the date. `currency` — per row,
+  over the `currency` prop.
+
+An invoice row:
+
+```js
+{ id: "inv_24", number: "INV-0024", date: "2026-09-15", dueDate: "2026-10-15", amount: 2500, status: "open" }
+```
+
+- `status` — `paid`, `open` (then the badge counts the days to or past
+  `dueDate`), `overdue` (when there is no due date), `void`, `draft`,
+  `cancelled`.
+- `name` — who it is for; shown before the date when `number` is set.
+
+## Props
+
+- `rows` — the records, in the order to show.
+- `variant` — `"history"` (default) or `"invoices"`.
+- `currency` — default `"USD"`. `locale` — money and dates, default the
+  reader's.
+- `groupBy` — `"month"` (the default for history) or `"none"` (the
+  default for invoices).
+- `title` · `description` — the card's heading; default "Transactions" or
+  "Invoices".
+- `dateFilter` — `true` shows a date-range picker in the header (with
+  presets). The block hides rows outside the range itself; `range` +
+  `onRangeChange(range)` control it (`{ from, to }` or `null`) when the
+  surface loads by date instead.
+- `onExport(rows, range)` — an Export button; it gets the rows on screen.
+  Return `{ ok: false, error }` to say why it failed.
+- `onDownload(row)` — a download button on each row (make the PDF, open
+  it); same return, the reason shows under the row. Or
+  `downloadHref(row)` — a link instead (return `null` for a row with none).
+- `onOpen(row)` — the row's name becomes a button (open your `Sheet`).
+- `loading` — skeleton rows. `error` — a line above the list.
+- `emptyTitle` · `emptyBody` — the empty state's words.
+- `today` — `"YYYY-MM-DD"`, the day an invoice's due date is counted
+  from; default today.
+- `className` — layout around it (width, margin). Never colour.
+
+## Example
+
+```jsx
+// components/Billing.jsx — client
+"use client";
+import { TransactionList } from "./blocks/transaction-list";
+
+export default function Billing({ invoices, payments, error }) {
+  return (
+    <div className="grid gap-6 lg:grid-cols-2">
+      <TransactionList
+        variant="invoices"
+        rows={invoices}
+        error={error}
+        description="Every invoice we have sent you."
+        downloadHref={(inv) => inv.pdfUrl}
+      />
+      <TransactionList
+        rows={payments}
+        dateFilter
+        description="Money in and out of the account."
+        onExport={async (rows) => {
+          const csv = rows.map((r) => [r.date, r.name, r.amount].join(",")).join("\n");
+          const url = URL.createObjectURL(new Blob([csv], { type: "text/csv" }));
+          Object.assign(document.createElement("a"), { href: url, download: "payments.csv" }).click();
+          return { ok: true };
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## What it will not do
+
+- Sort, page, or filter by column: rows come in ordered, and a record set
+  that needs those is a `data-table`.
+- Total the rows: put a `Stat` above it if a sum matters.
+- Make the invoice PDF or the export file: `onDownload` and `onExport`
+  are the app's.
+
+A list 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 transaction-list` restores them.
+
+## Credits
+
+Shape and behaviour from Creative Tim UI (https://github.com/creativetimofficial/ui), MIT; this is a rewrite on the Makersclaw kit.

package/registry/blocks/transaction-list/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "transaction-list",
+  "title": "TransactionList",
+  "description": "Money records as a plain list, in two variants: history (payments in and out, grouped by month, a received / paid / pending / failed mark and a signed amount) and invoices (number, date, a Paid / Due in N days / N days overdue badge, amount, download). Optional date-range filter, Export and per-row download. Empty, loading and error states built in.",
+  "useWhen": "A billing page's invoices, an account's payment history, a wallet's recent activity: records read top to bottom, newest first. Not for records the founder sorts, filters by column or totals (data-table), or for one order (order-detail).",
+  "tags": ["transactions", "payments", "history", "invoices", "billing", "receipts", "money", "ledger", "activity", "statement", "download", "export", "finance"],
+  "exports": ["TransactionList"],
+  "files": ["index.js", "transaction-list.jsx"],
+  "requires": []
+}

package/registry/blocks/transaction-list/demo.jsx

@@ -0,0 +1,79 @@
+"use client";
+
+// TransactionList with rows in memory — the gallery's and the smoke
+// test's surface. Not installed into apps.
+import { useState } from "react";
+import { Switch, ToggleGroup } from "../components/ui";
+import { TransactionList } from "../components/blocks/transaction-list";
+
+const HISTORY = [
+  { id: "tx_1", name: "Northwind Ltd", description: "Invoice INV-0024", date: "2026-09-21T12:30:00Z", amount: 2500, direction: "in" },
+  { id: "tx_2", name: "Figma", description: "Team plan", date: "2026-09-19T09:05:00Z", amount: 180, direction: "out" },
+  { id: "tx_3", name: "Globex Corp", description: "Invoice INV-0023", date: "2026-09-16T15:45:00Z", amount: 1750, direction: "in", status: "pending" },
+  { id: "tx_4", name: "Vercel", description: "Pro", date: "2026-09-02T07:00:00Z", amount: 20, direction: "out", status: "failed" },
+  { id: "tx_5", name: "Initech", description: "Invoice INV-0021", date: "2026-08-28T11:20:00Z", amount: 2990, direction: "in" },
+  { id: "tx_6", name: "Google Workspace", description: "6 seats", date: "2026-08-14T08:00:00Z", amount: 84, direction: "out" },
+  { id: "tx_7", name: "Acme Ltd", description: "Overpayment", date: "2026-08-03T16:10:00Z", amount: 250, direction: "out", status: "refunded" },
+];
+
+const INVOICES = [
+  { id: "inv_24", number: "INV-0024", name: "Northwind Ltd", date: "2026-09-15", dueDate: "2026-10-15", amount: 2500, status: "paid" },
+  { id: "inv_23", number: "INV-0023", name: "Globex Corp", date: "2026-09-10", dueDate: "2026-10-10", amount: 1750, status: "open" },
+  { id: "inv_22", number: "INV-0022", name: "Umbrella", date: "2026-09-01", dueDate: "2026-09-23", amount: 1500, status: "open" },
+  { id: "inv_21", number: "INV-0021", name: "Initech", date: "2026-08-20", dueDate: "2026-09-20", amount: 2990, status: "open" },
+  { id: "inv_20", number: "INV-0020", name: "Hooli", date: "2026-08-15", dueDate: "2026-09-14", amount: 3500, status: "void" },
+];
+
+const VIEWS = [
+  { value: "history", label: "History" },
+  { value: "invoices", label: "Invoices" },
+  { value: "empty", label: "Empty" },
+  { value: "loading", label: "Loading" },
+];
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export default function TransactionListDemo() {
+  const [view, setView] = useState("history");
+  const [failing, setFailing] = useState(false);
+  const [said, setSaid] = useState(null);
+
+  const act = (what) => async (arg) => {
+    await wait(500);
+    if (failing) return { ok: false, error: "The file could not be made. Try again." };
+    setSaid(`${what} was called${Array.isArray(arg) ? ` with ${arg.length} rows` : arg?.name ? ` for ${arg.number ?? arg.name}` : ""}.`);
+    return { ok: true };
+  };
+
+  const invoices = view === "invoices";
+
+  return (
+    <div className="grid gap-6">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <ToggleGroup items={VIEWS} value={view} onChange={setView} size="sm" aria-label="Which list to show" />
+        <Switch id="tx-fail" checked={failing} onChange={(e) => setFailing(e.target.checked)} label="Make actions fail" />
+      </div>
+      {said ? (
+        <p role="status" className="text-sm text-muted-foreground">
+          {said}
+        </p>
+      ) : null}
+      <div className="max-w-2xl">
+        <TransactionList
+          key={view}
+          variant={invoices ? "invoices" : "history"}
+          rows={view === "empty" ? [] : invoices ? INVOICES : HISTORY}
+          loading={view === "loading"}
+          currency="USD"
+          locale="en-US"
+          today="2026-09-23"
+          description={invoices ? "Every invoice sent this quarter." : "Money in and out of the account."}
+          dateFilter={!invoices}
+          onExport={act("onExport")}
+          onDownload={act("onDownload")}
+          onOpen={(row) => setSaid(`onOpen was called for ${row.number ?? row.name}.`)}
+        />
+      </div>
+    </div>
+  );
+}

package/registry/blocks/transaction-list/index.js

@@ -0,0 +1,4 @@
+// The TransactionList block — `makersclaw add transaction-list`. Fixed:
+// compose it through its props (README.md beside this file); a list it
+// cannot be is your own component in components/.
+export { TransactionList } from "./transaction-list";