makersclaw 0.2.0 → 0.3.1

package/registry/blocks/payment-methods/payment-methods.jsx

@@ -0,0 +1,302 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Badge, Button, Confirm, Empty, Icon, Notice, Skeleton, Tooltip, cx, todayString } from "../../ui";
+
+// The payment methods a customer has saved, as cards: the brand, the last
+// four digits, the expiry and which one is the default. Make default and
+// Remove (behind a Confirm) go out through callbacks that return { ok }.
+// Adding one is the app's: `onAdd` opens the payment provider (Paddle),
+// which collects the card. The block never holds a card number.
+
+// Server and browser may differ in locale, time zone and even the day:
+// the first render uses fixed ones (en-US, UTC) so it matches the server's
+// HTML, then the reader's own take over.
+function useHydrated() {
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  return hydrated;
+}
+
+const BRANDS = {
+  visa: { name: "Visa", icon: "credit-card" },
+  mastercard: { name: "Mastercard", icon: "credit-card" },
+  amex: { name: "American Express", icon: "credit-card" },
+  discover: { name: "Discover", icon: "credit-card" },
+  jcb: { name: "JCB", icon: "credit-card" },
+  unionpay: { name: "UnionPay", icon: "credit-card" },
+  maestro: { name: "Maestro", icon: "credit-card" },
+  card: { name: "Card", icon: "credit-card" },
+  paypal: { name: "PayPal", icon: "credit-card" },
+  apple_pay: { name: "Apple Pay", icon: "apple" },
+  google_pay: { name: "Google Pay", icon: "google" },
+  bank: { name: "Bank account", icon: "building" },
+};
+
+function brandOf(method) {
+  const key = String(method.brand ?? "card").toLowerCase().replace(/[\s-]+/g, "_");
+  const known = BRANDS[key];
+  return known ?? { name: method.brand || "Card", icon: "credit-card" };
+}
+
+// The name a method is called by in buttons and dialogs: "Visa ending 4242".
+function nameOf(method) {
+  if (method.label) return method.label;
+  const brand = brandOf(method).name;
+  return method.last4 ? `${brand} ending ${method.last4}` : brand;
+}
+
+// "expired" · "soon" (this month or next) · "ok" · null (no expiry).
+function expiryState(method, today) {
+  const m = Number(method.expMonth);
+  let y = Number(method.expYear);
+  if (!m || !y) return null;
+  if (y < 100) y += 2000;
+  const [ty, tm] = today.split("-").map(Number);
+  const months = (y - ty) * 12 + (m - tm);
+  if (months < 0) return "expired";
+  if (months <= 1) return "soon";
+  return "ok";
+}
+
+const expiryText = (method) => {
+  const m = String(method.expMonth).padStart(2, "0");
+  const y = String(method.expYear).slice(-2);
+  return `${m}/${y}`;
+};
+
+async function attempt(fn) {
+  try {
+    const res = await fn();
+    return res && res.ok === false ? res.error || "That did not save." : null;
+  } catch (e) {
+    return e?.message || "That did not save.";
+  }
+}
+
+function MethodCard({ method, today, busy, error, onMakeDefault, onAskRemove, removable, lockedReason }) {
+  const brand = brandOf(method);
+  const expiry = expiryState(method, today);
+  const name = nameOf(method);
+  return (
+    <li
+      className={cx(
+        "relative grid gap-4 rounded-lg border bg-card p-4 text-card-foreground",
+        method.isDefault ? "border-primary/60" : "border-border",
+      )}
+    >
+      <div className="flex items-start gap-3">
+        <span className="grid h-11 w-14 shrink-0 place-items-center rounded-md border border-border bg-muted text-foreground">
+          <Icon name={brand.icon} size={22} />
+        </span>
+        <div className="grid min-w-0 flex-1 gap-0.5">
+          <p className="truncate font-medium">
+            {method.last4 ? (
+              <>
+                <span aria-hidden="true" className="tracking-widest text-muted-foreground">
+                  ••••{" "}
+                </span>
+                <span className="sr-only">{brand.name} ending </span>
+                <span className="tabular-nums">{method.last4}</span>
+              </>
+            ) : (
+              method.label || brand.name
+            )}
+          </p>
+          <p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-sm text-muted-foreground">
+            <span>{method.last4 ? brand.name : method.holder || method.email || ""}</span>
+            {method.expMonth && method.expYear ? (
+              <span className={cx(expiry === "expired" && "text-destructive")}>
+                {expiry === "expired" ? "Expired" : "Expires"} {expiryText(method)}
+              </span>
+            ) : null}
+          </p>
+          {method.last4 && method.holder ? <p className="truncate text-xs text-muted-foreground">{method.holder}</p> : null}
+        </div>
+        <div className="flex shrink-0 flex-col items-end gap-1">
+          {method.isDefault ? (
+            <Badge tone="primary" variant="soft">
+              Default
+            </Badge>
+          ) : null}
+          {expiry === "expired" ? (
+            <Badge tone="danger" variant="soft">
+              Expired
+            </Badge>
+          ) : expiry === "soon" ? (
+            <Badge tone="warning" variant="soft">
+              Expires soon
+            </Badge>
+          ) : null}
+        </div>
+      </div>
+
+      {onMakeDefault || onAskRemove ? (
+        <div className="flex flex-wrap items-center gap-2 border-t border-border pt-3">
+          {onMakeDefault && !method.isDefault ? (
+            <Button
+              size="sm"
+              variant="quiet"
+              icon="check"
+              onClick={() => onMakeDefault(method)}
+              loading={busy === "default"}
+              disabled={Boolean(busy) || expiry === "expired"}
+              aria-label={`Make ${name} the default`}
+            >
+              Make default
+            </Button>
+          ) : null}
+          {onAskRemove ? (
+            <Tooltip label={removable ? "" : lockedReason} className="ml-auto">
+              <Button
+                size="sm"
+                variant="danger"
+                icon="trash"
+                onClick={() => onAskRemove(method)}
+                disabled={Boolean(busy) || !removable}
+                aria-label={`Remove ${name}`}
+                className="ml-auto"
+              >
+                Remove
+              </Button>
+            </Tooltip>
+          ) : null}
+        </div>
+      ) : null}
+
+      {error ? (
+        <p role="alert" className="text-xs text-destructive">
+          {error}
+        </p>
+      ) : null}
+    </li>
+  );
+}
+
+function Loading() {
+  return (
+    <ul aria-busy="true" aria-label="Loading payment methods" className="grid gap-3 md:grid-cols-2">
+      {[0, 1].map((i) => (
+        <li key={i} className="flex gap-3 rounded-lg border border-border p-4">
+          <Skeleton shape="rect" className="h-11 w-14" />
+          <div className="grid flex-1 content-start gap-2">
+            <Skeleton className="w-1/2" />
+            <Skeleton className="w-1/3" />
+          </div>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export function PaymentMethods({
+  methods,
+  onAdd,
+  onSetDefault,
+  onRemove,
+  loading = false,
+  error,
+  title = "Payment methods",
+  description = "The cards and wallets saved to your account. The default is charged first.",
+  addLabel = "Add payment method",
+  emptyTitle = "No saved payment methods",
+  emptyBody = "Add one and it is ready at checkout.",
+  today,
+  className,
+}) {
+  const [busy, setBusy] = useState({});
+  const [errors, setErrors] = useState({});
+  const [removing, setRemoving] = useState(null);
+  const [removeBusy, setRemoveBusy] = useState(false);
+  const [adding, setAdding] = useState(false);
+  const [addError, setAddError] = useState(null);
+  const hydrated = useHydrated();
+  const now = today ?? (hydrated ? todayString() : new Date().toISOString().slice(0, 10));
+  const list = (methods ?? []).filter(Boolean);
+  const onlyOne = list.length <= 1;
+
+  const mark = (id, state) => setBusy((b) => ({ ...b, [id]: state }));
+  const fail = (id, message) => setErrors((e) => ({ ...e, [id]: message }));
+
+  async function makeDefault(method) {
+    mark(method.id, "default");
+    fail(method.id, null);
+    fail(method.id, await attempt(() => onSetDefault(method)));
+    mark(method.id, null);
+  }
+
+  async function confirmRemove() {
+    const method = removing;
+    if (!method) return;
+    setRemoveBusy(true);
+    fail(method.id, null);
+    const failed = await attempt(() => onRemove(method));
+    setRemoveBusy(false);
+    setRemoving(null);
+    if (failed) fail(method.id, failed);
+  }
+
+  async function add() {
+    setAdding(true);
+    setAddError(null);
+    setAddError(await attempt(() => onAdd()));
+    setAdding(false);
+  }
+
+  const addButton = onAdd ? (
+    <Button variant="primary" icon="plus" onClick={add} loading={adding}>
+      {addLabel}
+    </Button>
+  ) : null;
+
+  let body;
+  if (loading) body = <Loading />;
+  else if (!list.length) body = <Empty icon="credit-card" title={emptyTitle} body={emptyBody} action={addButton} />;
+  else
+    body = (
+      <ul aria-label={title} className="grid gap-3 md:grid-cols-2">
+        {list.map((method) => (
+          <MethodCard
+            key={method.id}
+            method={method}
+            today={now}
+            busy={busy[method.id]}
+            error={errors[method.id]}
+            onMakeDefault={onSetDefault ? makeDefault : null}
+            onAskRemove={onRemove ? setRemoving : null}
+            removable={!method.isDefault || onlyOne}
+            lockedReason="Make another method the default before removing this one"
+          />
+        ))}
+      </ul>
+    );
+
+  return (
+    <section className={cx("grid gap-5", className)}>
+      <header className="flex flex-wrap items-start justify-between gap-3">
+        <div className="min-w-0 max-w-prose">
+          <h2 className="text-xl font-semibold">{title}</h2>
+          {description ? <p className="mt-1 text-sm text-muted-foreground">{description}</p> : null}
+        </div>
+        {!loading && list.length ? <div className="w-full sm:w-auto [&>button]:w-full">{addButton}</div> : null}
+      </header>
+      {error ? <Notice tone="danger">{error}</Notice> : null}
+      {addError ? (
+        <Notice tone="danger" onDismiss={() => setAddError(null)}>
+          {addError}
+        </Notice>
+      ) : null}
+      {body}
+      <Confirm
+        open={Boolean(removing)}
+        onClose={() => (removeBusy ? null : setRemoving(null))}
+        onConfirm={confirmRemove}
+        tone="danger"
+        busy={removeBusy}
+        title={removing ? `Remove ${nameOf(removing)}?` : "Remove?"}
+        body="It will no longer be offered at checkout. You can add it again later."
+        confirmLabel="Remove"
+      />
+    </section>
+  );
+}

package/registry/blocks/pdf-document/README.md

@@ -0,0 +1,213 @@
+# PdfDocument
+
+Make PDFs in the workspace theme, in the browser. A small set of document
+parts — headings, text, label-over-value fields, tables whose header
+repeats on every page, totals, callouts, badges, rows and columns — and
+a ready quote / estimate / invoice layout built from them. `renderPdf`
+turns a document into a `Blob` to download, preview, upload or attach;
+`usePdf` keeps one fresh while a form changes (a live preview); and
+`PdfDownloadButton` is the "Download PDF" beside it.
+
+The look is a clean business document: white paper, near-black ink,
+grey for secondary text, hairline rules, one accent — the theme's
+primary — on a bar along the top edge and on the amount that matters.
+Type is one face at a few sizes on a 4pt rhythm, sentence case, figures
+aligned in their columns. It prints well in black and white.
+
+It is [@react-pdf/renderer](https://github.com/diegomura/react-pdf)
+(MIT) underneath: it lays the document out in JavaScript and writes the
+PDF, no browser print dialog and no server. The blocks that print
+(quote-builder, proposal-accept…) import this one, never
+`@react-pdf/renderer`.
+
+```jsx
+import { QuoteDocument, renderPdf, PdfDownloadButton } from "../components/blocks/pdf-document";   // a Makersclaw app ("./blocks/pdf-document" from components/)
+import { QuoteDocument, renderPdf, PdfDownloadButton } from "@/components/makersclaw/blocks/pdf-document";   // a shadcn project
+```
+
+Render from a `"use client"` component. `quoteTotals`, `formatMoney`,
+`formatQuantity`, `formatPdfDate`, `buildPdfTheme` are plain functions
+and work on the server (use the same sums on the screen and in the PDF).
+
+## Colours: why the theme is read at render time
+
+A PDF cannot read CSS variables — every colour in it is a value written
+into the file. So `renderPdf` reads the workspace theme from the page at
+the moment it makes the PDF (a hidden probe resolves `--color-primary`
+and the other tokens to plain colours) and passes them in. Change the
+theme and the next PDF follows; a PDF already made keeps its colours.
+
+Two schemes:
+
+- `paper` (the default) — what gets printed, emailed or signed: white
+  paper and dark ink whatever the workspace looks like, with the theme's
+  primary as the accent. A dark workspace still sends a light invoice.
+  If the primary is too pale to read on white (a mint, a lemon), text
+  uses a darker shade of it (4.5:1 or more) while bars keep the colour.
+- `theme` — the workspace's own background, ink and borders, for a PDF
+  meant to be read on screen in the brand's look.
+
+Nothing in a document names a colour: parts take a `tone` (`default` ·
+`muted` · `accent` · `success` · `warning` · `danger` · `info`).
+
+Fonts: Helvetica, which every PDF reader has built in, so a PDF is small
+and nothing is fetched. It draws Latin text; for other scripts, or
+symbols like ₹, register a font that has them (`registerPdfFont`).
+
+## QuoteDocument
+
+A quote, an estimate or an invoice from data. The sender and the
+document's name at the top, then who it is for, the dates and the amount
+due; the lines; the sums; notes, terms and how to pay.
+
+```jsx
+<QuoteDocument
+  kind="invoice"                   // quote (default) · estimate · invoice
+  number="INV-2026-041"
+  issued="2026-09-23"              // "YYYY-MM-DD" or a Date
+  until="2026-10-07"               // valid until (quote) · due (invoice)
+  from={{ name: "Northwind Studio", lines: ["18 Harbour Street", "Bristol BS1 4QA"], email: "billing@northwind.studio", logo: "/logo.png" }}
+  to={{ name: "Priya Raman", company: "Juniper Health", lines: ["400 Market St"], email: "priya@juniper.health" }}
+  items={[{ description: "Design system", detail: "32 components", quantity: 1, unit: "", unitPrice: 9600, discountPercent: 0, taxable: true }]}
+  currency="GBP" locale="en-GB"
+  taxRate={20} taxLabel="VAT (20%)"
+  discount={{ percent: 5 }}        // or { amount: 250, label: "Loyalty" }
+  paid={3000}                      // a deposit: prints Total, Paid, Balance due
+  status="Deposit received" statusTone="success"   // an outlined badge under the number
+  notes="Thanks for the conversation…"             // a tinted callout
+  terms="Payment is due within 14 days."
+  payment={["Northwind Studio Ltd", "Sort code 00-00-00"]}   // "How to pay" (lines or a string)
+/>
+```
+
+Every prop but the data you have is optional: `title` overrides the
+document's name, `reference` adds a "Reference" field (a PO number),
+`footer` replaces the footer line (default: sender, email, website),
+`dateLocale` formats dates (default `en-GB`: 23 Sep 2026), `size` is
+`"A4"` (default) or `"LETTER"`. Amounts are in the currency's main unit
+(pounds, not pence); `quoteTotals` does the sums — each line rounded,
+the discount before tax, tax only on `taxable` lines.
+
+## The parts
+
+Compose your own document from these; they only render inside a
+`PdfDocument`, passed to `renderPdf` (never into the page).
+
+- `PdfDocument` — `title`, `author`, `subject` (the file's properties),
+  `size` (`"A4"` · `"LETTER"` · `"LEGAL"` · `[w, h]` in points),
+  `landscape`, `margin` (`compact` 36pt · `normal` 48pt · `roomy` 64pt),
+  `accentBar` (default `true`), `footer` (a line at the foot of every
+  page, with "Page 2 of 3" at the right when there is more than one;
+  `null` for none). Content flows onto new pages by itself.
+- `PdfStack` — a column with `gap` (pt, default 8); `break` starts it on
+  a new page; `wrap={false}` keeps it on one page.
+- `PdfRow` — a row: `gap` (default 16), `justify` (`start` · `between` ·
+  `end` · `center`), `align` (`start` · `center` · `end` · `baseline`).
+  `PdfCol` — one column of it: `flex` (share, default 1; `0` = as wide as
+  its content) or `width` (pt).
+- `PdfHeading` — `level` 1 (24pt, the document's name) · 2 (12pt, a
+  section) · 3 (bold body size); `tone`, `align`.
+- `PdfText` — `size` (`xs` · `sm` · `md` · `lg` · `xl` · `xxl`), `tone`,
+  `bold`, `align`.
+- `PdfLabel` — the small muted line above a value. `PdfField` — a label
+  over a value (`strong` sets the value large and bold).
+- `PdfLines` — lines of an address: the first bold, the rest muted
+  (`first={false}`, `muted={false}` to change).
+- `PdfTable` — `columns` `[{ key, label, flex? | width?, align?,
+  render?(row, i) }]`, `rows` (a row's `detail` prints as a muted second
+  line under the first column), `empty`. The header repeats on each page;
+  a row never splits.
+- `PdfTotals` — `rows` `[{ label, value, strong?, tone? }]` flush right;
+  the `strong` row is larger, over a rule. `width` (default 220pt).
+- `PdfCallout` — a tinted box with an accent edge (`tone="neutral"` for
+  grey), optional `title`.
+- `PdfBadge` — an outlined pill: `tone` `accent` · `success` · `warning`
+  · `danger` · `neutral`.
+- `PdfDivider` — a hairline; `space` above and below (pt), `strong` for
+  an ink rule.
+- `PdfImage` (`src`: a URL the browser can fetch, or a data URL),
+  `PdfLink` (`src`), `PdfView`, `PdfRawText` — the library's own parts,
+  for anything else; style them with `usePdfTheme()` values.
+- `usePdfTheme()` — inside a part: `{ paper, ink, muted, rule, band,
+  accent, accentInk, accentSoft, onAccent, success, warning, danger,
+  info, font, fontBold }`. `PDF_TYPE` is the size scale in points.
+
+## Functions
+
+- `renderPdf(doc, { theme?, root?, scheme? })` → `Promise<Blob>`
+  (`application/pdf`). `theme` from `resolvePdfTheme(root, { scheme })`
+  or `buildPdfTheme(slots, { scheme, font })`; by default it is read from
+  `<body>` (or `root`) now. Rejects when the document cannot be made (an
+  image that will not load, a font that will not fetch).
+- `usePdf(build, deps, { delay = 400, enabled = true, ...renderOptions })`
+  → `{ blob, url, loading, error, refresh }`. Re-renders `delay` ms after
+  `deps` settle; `url` is an object URL, revoked when replaced.
+- `PdfDownloadButton` — `document` (an element, or a function returning
+  one, called on press), `fileName`, `label` ("Download PDF"), `icon`,
+  `variant`, `size`, `disabled`, `options` (for renderPdf). Busy while it
+  renders; a failure shows a toast and the button is ready again.
+- `downloadBlob(blob, fileName)` — save any Blob as a file.
+- `registerPdfFont({ family, regular, bold? })` → `{ family, bold }` —
+  a TTF/WOFF by URL; pass the result as `font` to `buildPdfTheme`.
+- `quoteTotals({ items, discount?, taxRate?, paid? })` → `{ lines,
+  subtotal, discount, tax, total, paid, due }`; `lineAmount(item)`;
+  `round2(n)`.
+- `formatMoney(n, currency = "USD", locale = "en-US")` ("£1,234.50"),
+  `formatQuantity(q, locale)` ("1.5"), `formatPdfDate(value, locale =
+  "en-GB")` ("23 Sep 2026") — in characters the PDF's face can draw.
+
+## Example
+
+A quote screen: the form, a live preview in the `pdf-viewer` block, and
+the download.
+
+```jsx
+"use client";
+import { PdfViewer } from "../components/blocks/pdf-viewer";
+import { PdfDownloadButton, QuoteDocument, usePdf } from "../components/blocks/pdf-document";
+
+export function QuotePreview({ quote }) {
+  const doc = () => <QuoteDocument {...quote} />;
+  const { blob, error } = usePdf(doc, [quote]);
+  return (
+    <div className="grid gap-3">
+      <div className="flex justify-end">
+        <PdfDownloadButton variant="primary" document={doc} fileName={`${quote.number}.pdf`} />
+      </div>
+      <PdfViewer file={blob} loading={!blob && !error} title={`Quote ${quote.number}`} thumbnails={false} />
+    </div>
+  );
+}
+```
+
+Your own document:
+
+```jsx
+const blob = await renderPdf(
+  <PdfDocument title="Statement" footer="Juniper Health · Statement for August">
+    <PdfHeading level={1}>Statement</PdfHeading>
+    <PdfText tone="muted">1–31 August 2026</PdfText>
+    <PdfDivider />
+    <PdfTable columns={[{ key: "date", label: "Date", width: 80 }, { key: "what", label: "Description", flex: 3 }, { key: "amount", label: "Amount", width: 90, align: "right" }]} rows={rows} />
+    <PdfTotals rows={[{ label: "Closing balance", value: formatMoney(balance), strong: true }]} />
+  </PdfDocument>,
+);
+```
+
+## What it will not do
+
+- Render the parts into the page: they are PDF parts, not HTML. Preview
+  a PDF with the `pdf-viewer` block.
+- Edit or fill an existing PDF, or sign one (see `signature-pad`).
+- Use the workspace's web font on its own: register one with
+  `registerPdfFont`, or the PDF uses Helvetica.
+- Make PDFs on the server from this block (it is a client block that
+  reads the theme from the page); `quoteTotals` and the formatters do run
+  there.
+- Write right-to-left text or hyphenate: words are never split at a line
+  end.
+
+## Credits
+
+Built on [@react-pdf/renderer](https://github.com/diegomura/react-pdf) by
+Diego Muracciole (MIT), used unmodified. See THIRD-PARTY-NOTICES.md.

package/registry/blocks/pdf-document/block.json

@@ -0,0 +1,13 @@
+{
+  "name": "pdf-document",
+  "title": "PdfDocument",
+  "description": "Make PDFs in the workspace theme (@react-pdf/renderer): a small set of document primitives (headings, text, label/value fields, tables with repeating headers, totals, callouts, badges, rows and columns) and a clean ready-made quote / estimate / invoice layout, rendered in the browser to a Blob with renderPdf(doc). The theme's colours are read from the page when the PDF is made (a PDF cannot read CSS variables): white paper, near-black ink and the theme's primary as the one accent. Also a live-preview hook (usePdf), a Download PDF button, and the quote sums and money formatting as plain functions.",
+  "useWhen": "A screen produces a document someone downloads, prints, emails or signs: a quote, an invoice, an estimate, a receipt, a statement, a certificate, a one-page report. The quote-builder and proposal blocks print through it. Not for showing an existing PDF on screen (pdf-viewer) or for a web page people read in the app (doc-page).",
+  "tags": ["pdf", "document", "invoice", "quote", "estimate", "receipt", "print", "download", "export", "react-pdf", "billing", "proposal", "statement"],
+  "exports": ["renderPdf", "usePdf", "PdfDownloadButton", "downloadBlob", "registerPdfFont", "PdfDocument", "PdfStack", "PdfRow", "PdfCol", "PdfText", "PdfHeading", "PdfLabel", "PdfField", "PdfDivider", "PdfCallout", "PdfBadge", "PdfTable", "PdfTotals", "PdfLines", "PdfView", "PdfRawText", "PdfImage", "PdfLink", "PdfThemeProvider", "usePdfTheme", "PDF_TYPE", "QuoteDocument", "quoteTotals", "lineAmount", "round2", "formatMoney", "formatQuantity", "formatPdfDate", "resolvePdfTheme", "buildPdfTheme", "DEFAULT_PDF_THEME"],
+  "files": ["index.js", "pdf-document.jsx", "primitives.jsx", "quote.jsx", "money.js", "theme.js"],
+  "requires": [],
+  "dependencies": {
+    "@react-pdf/renderer": "4.9.0"
+  }
+}

package/registry/blocks/pdf-document/demo.jsx

@@ -0,0 +1,136 @@
+"use client";
+
+// PdfDocument — the gallery's and the smoke test's surface. Not installed
+// into apps. A small quote editor: the fields on the left, the PDF on the
+// right, made in the browser from QuoteDocument as you type (usePdf) and
+// shown in the pdf-viewer block, with a Download PDF button. Switch the
+// kind to Invoice and the same data prints as an invoice with a deposit.
+// The colours are the workspace theme's, read when the PDF is made.
+import { useState } from "react";
+import { Button, Card, Field, IconButton, Input, Notice, Textarea, ToggleGroup } from "../components/ui";
+import { PdfViewer } from "../components/blocks/pdf-viewer";
+import { PdfDownloadButton, QuoteDocument, formatMoney, quoteTotals, usePdf } from "../components/blocks/pdf-document";
+
+const STUDIO = {
+  name: "Northwind Studio",
+  lines: ["18 Harbour Street", "Bristol BS1 4QA, United Kingdom"],
+  email: "billing@northwind.studio",
+  website: "northwind.studio",
+};
+
+const START_ITEMS = [
+  { id: "l1", description: "Discovery workshop", detail: "Two half-day sessions with your team", quantity: 2, unit: "days", unitPrice: 1400 },
+  { id: "l2", description: "Design system", detail: "Tokens, 32 components, documentation", quantity: 1, unitPrice: 9600 },
+  { id: "l3", description: "Landing page build", quantity: 3, unitPrice: 1850 },
+];
+
+let nextId = 4;
+
+export default function PdfDocumentDemo() {
+  const [kind, setKind] = useState("quote");
+  const [client, setClient] = useState({ name: "Priya Raman", company: "Juniper Health", email: "priya@juniper.health" });
+  const [items, setItems] = useState(START_ITEMS);
+  const [taxRate, setTaxRate] = useState("20");
+  const [notes, setNotes] = useState("Thank you for the conversation last week. This quote covers the first phase; we will scope the build together once discovery is done.");
+
+  const invoice = kind === "invoice";
+  const doc = {
+    kind,
+    number: invoice ? "INV-2026-041" : "Q-2026-118",
+    issued: "2026-09-23",
+    until: invoice ? "2026-10-07" : "2026-10-23",
+    from: STUDIO,
+    to: { name: client.name, company: client.company, email: client.email },
+    items,
+    currency: "GBP",
+    locale: "en-GB",
+    taxRate: Number(taxRate) || 0,
+    taxLabel: `VAT (${Number(taxRate) || 0}%)`,
+    paid: invoice ? 3000 : 0,
+    status: invoice ? "Deposit received" : null,
+    statusTone: "success",
+    notes,
+    terms: invoice ? "Payment is due within 14 days." : "This quote is valid for 30 days. Work starts on a signed quote and a 30% deposit.",
+    payment: invoice ? ["Northwind Studio Ltd", "Sort code 00-00-00", "Account 00000000"] : null,
+  };
+  const pdf = usePdf(() => <QuoteDocument {...doc} />, [JSON.stringify(doc)], { delay: 500 });
+  const sums = quoteTotals({ items, taxRate: doc.taxRate, paid: doc.paid });
+
+  const setItem = (id, patch) => setItems((list) => list.map((it) => (it.id === id ? { ...it, ...patch } : it)));
+
+  return (
+    <div className="grid gap-4 lg:grid-cols-[minmax(0,400px)_minmax(0,1fr)] lg:items-start">
+      <Card title="Quote details" padding="md">
+        <div className="grid gap-4">
+          <ToggleGroup
+            aria-label="Kind of document"
+            className="w-full"
+            value={kind}
+            onChange={setKind}
+            items={[
+              { value: "quote", label: "Quote" },
+              { value: "invoice", label: "Invoice" },
+            ]}
+          />
+          <div className="grid gap-3 sm:grid-cols-2">
+            <Field id="q-name" label="Client">
+              <Input id="q-name" value={client.name} onChange={(e) => setClient({ ...client, name: e.target.value })} />
+            </Field>
+            <Field id="q-company" label="Company">
+              <Input id="q-company" value={client.company} onChange={(e) => setClient({ ...client, company: e.target.value })} />
+            </Field>
+          </div>
+
+          <div className="grid gap-2">
+            <p className="text-sm font-medium">Line items</p>
+            <ul className="grid gap-2">
+              {items.map((it) => (
+                <li key={it.id} className="grid grid-cols-[minmax(0,1fr)_4rem_6rem_auto] items-center gap-2">
+                  <Input aria-label="Description" value={it.description} placeholder="What is it?" onChange={(e) => setItem(it.id, { description: e.target.value })} />
+                  <Input aria-label="Quantity" inputMode="decimal" className="text-right tabular-nums" value={String(it.quantity)} onChange={(e) => setItem(it.id, { quantity: e.target.value })} />
+                  <Input aria-label="Unit price" inputMode="decimal" className="text-right tabular-nums" value={String(it.unitPrice)} onChange={(e) => setItem(it.id, { unitPrice: e.target.value })} />
+                  <IconButton icon="trash" label={`Remove ${it.description || "line"}`} onClick={() => setItems((list) => list.filter((x) => x.id !== it.id))} />
+                </li>
+              ))}
+            </ul>
+            <div className="flex items-center justify-between gap-2">
+              <Button variant="quiet" size="sm" icon="plus" onClick={() => setItems((list) => [...list, { id: `l${nextId++}`, description: "", quantity: 1, unitPrice: 0 }])}>
+                Add line
+              </Button>
+              <p className="text-sm text-muted-foreground tabular-nums">
+                Subtotal <span className="font-medium text-foreground">{formatMoney(sums.subtotal, "GBP", "en-GB")}</span>
+              </p>
+            </div>
+          </div>
+
+          <Field id="q-tax" label="VAT rate" hint="Percent, on every line.">
+            <Input id="q-tax" inputMode="decimal" className="tabular-nums" value={taxRate} onChange={(e) => setTaxRate(e.target.value)} />
+          </Field>
+          <Field id="q-notes" label="Note to the client">
+            <Textarea id="q-notes" autoGrow minRows={2} maxRows={6} value={notes} onChange={(e) => setNotes(e.target.value)} />
+          </Field>
+        </div>
+      </Card>
+
+      <div className="grid min-w-0 gap-3">
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <div className="min-w-0">
+            <p className="text-sm font-medium">
+              {invoice ? "Invoice" : "Quote"} {doc.number}
+            </p>
+            <p className="text-sm text-muted-foreground tabular-nums">
+              {invoice ? "Balance due" : "Total"} {formatMoney(sums.due, "GBP", "en-GB")} · {pdf.loading ? "Updating preview…" : "Preview is up to date"}
+            </p>
+          </div>
+          <PdfDownloadButton variant="primary" document={() => <QuoteDocument {...doc} />} fileName={`${doc.number}.pdf`} />
+        </div>
+        {pdf.error ? (
+          <Notice tone="danger" title="The preview couldn't be made">
+            {String(pdf.error.message ?? pdf.error)}
+          </Notice>
+        ) : null}
+        <PdfViewer file={pdf.blob} loading={!pdf.blob} title={`${invoice ? "Invoice" : "Quote"} ${doc.number}`} fileName={`${doc.number}.pdf`} thumbnails={false} height="760px" />
+      </div>
+    </div>
+  );
+}