gbs-add-block 2.0.1 → 2.0.2

package/.gbs/skills/gbs-components/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: gbs-components
+description: Builds UI with the GBS headless component library (gbs-add-block). Use when adding or changing UI in apps that have a component-lib/ folder.
+autoAttach: ["src/**/*.tsx", "src/**/*.jsx", "app/**/*.tsx", "components/**/*.tsx"]
+---
+
+# GBS components (2.0 beta)
+
+## Install before you import
+
+Not an npm dependency — the CLI **copies source into the repo**:
+
+```bash
+npx gbs-add-block -a Button,Input,Modal --beta
+```
+
+Writes `component-lib/<folder>/` plus `component-lib/shared/`. Always pass
+`--beta`. Import the folder barrel **and its stylesheet** (or the repo's alias):
+
+```ts
+import { Button } from "component-lib/button";
+import "component-lib/button/styles.css";
+```
+
+Folder = lowercased name, except `data-grid`, `date-picker`, `file-uploader`,
+`number-input`, `radio-group`.
+
+## Rules most often missed
+
+1. **Change handlers are named per component.** `onValueChange`: Input,
+   OtpInput, Textarea, NumberInput, CheckboxGroup, RadioGroup, Tabs, Accordion,
+   MenuRadioGroup. `onCheckedChange`: Checkbox, Switch, MenuCheckboxItem.
+   `onChange`: Select, MultiSelect, DatePicker, DateRangePicker, FileUploader.
+   `onOpenChange`: Modal, Popover, Menu.
+2. **Never hand-roll `<label>`, hint or error markup.** Fields take `label`,
+   `description` and `error`; `error` also marks the control invalid and wires
+   `aria-describedby`. A `<label>` wrapper breaks it.
+3. **Style via `classNames` slots** (`classNames={{ root, label }}`);
+   `className` hits the root only. Theme globally with `--gbs-*` on `:root`.
+4. **Mount `<Toaster />` and `<DialogHost />` once at the app root**, or
+   `toast()` and `dialog.confirm()` do nothing.
+5. **All are client components** (`"use client"`); a Next.js Server Component
+   can render them but not pass function props.
+6. **Compound families throw outside their parent**: Tab/TabList/TabPanel need
+   Tabs, AccordionItem needs Accordion, MenuItem needs Menu.
+
+## Inventory (required props in parens)
+
+**Forms** — Input, Textarea, NumberInput (locale-aware), OtpInput; Checkbox +
+CheckboxGroup; Radio (`value`) + RadioGroup; Switch (applies immediately);
+Select and MultiSelect (`options`; searchable, client or server); DatePicker and
+DateRangePicker; FileUploader (chunked).
+
+**Actions** — Button: variants, sizes, icons, auto-loading from a returned
+promise; `render` draws a router link.
+
+**Overlays** — Modal (native `<dialog>`, also drawers); `dialog` + DialogHost
+(`await dialog.confirm/alert/prompt`); Popover (`trigger`); Menu (`trigger`) with
+MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem, MenuGroup,
+MenuSeparator, MenuSub; Tooltip (`content`); `toast` + Toaster.
+
+**Data** — DataGrid (`data`, `columns`) + createColumnHelper: virtualized;
+sort, filter, edit, CSV/Excel/PDF export.
+
+**Display** — Tabs/TabList/Tab (`value`)/TabPanel (`value`); Accordion +
+AccordionItem (`value`); Card/CardHeader/CardBody/CardFooter/Stat; Alert; Badge
+and Tag; Avatar and AvatarGroup; Progress and CircularProgress (`value={null}`
+is indeterminate); Skeleton and Empty; Spinner; Breadcrumb (`items`,
+`renderLink`).
+
+## Example
+
+```tsx
+"use client";
+import { useState } from "react";
+import { Button } from "component-lib/button";
+import { Input } from "component-lib/input";
+import { Select } from "component-lib/combobox";
+import { Modal } from "component-lib/modal";
+import { toast } from "component-lib/toaster";
+// plus each styles.css, once
+
+const ROLES = [{ value: "admin", label: "Admin" }, { value: "dev", label: "Dev" }];
+
+export function InviteButton() {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState("");
+  const [role, setRole] = useState<string | null>(null);
+  const invalid = !!email && !email.includes("@");
+
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Invite</Button>
+      <Modal open={open} onOpenChange={setOpen} title="Invite a teammate"
+        footer={({ close }) => (
+          <Button disabled={!email || invalid} onClick={async () => {
+            await invite({ email, role });
+            toast.success("Invitation sent");
+            close();
+          }}>Send</Button>
+        )}>
+        <Input label="Email" type="email" value={email} onValueChange={setEmail}
+          required error={invalid ? "Enter a valid email" : undefined} />
+        <Select label="Role" options={ROLES} value={role} onChange={setRole} />
+      </Modal>
+    </>
+  );
+}
+```
+
+## Don't
+
+- Raw `<button>`, `<input>`, `<select>`, `<table>`, `<dialog>`, or a hand-built
+  modal/menu/tooltip, when a component exists.
+- Deep imports (`.../input/react/Input`); import the barrel. Only `<name>/core`
+  is also public.
+- Editing `component-lib/shared/`; the CLI replaces it on update.
+- Invented props: no `asChild`, no `variant` on Input, no `onChange` on Switch.
+- `!important` or internal class selectors; set `--gbs-*` or pass `classNames`.
+- A Tooltip as a name; icon buttons need `aria-label`.
+
+## Details (in `references/`)
+
+- `install.md` — CLI flags, folders, `shared/`, 1.x vs beta.
+- `forms.md` — text and choice fields, controlled state, form posting.
+- `pickers.md` — Select, MultiSelect, DatePicker, FileUploader.
+- `overlays.md` — Modal, dialog, Popover, Menu, Tooltip.
+- `toaster.md` — `toast()` and `<Toaster />`.
+- `data-grid.md` — columns, API, export.
+- `data-display.md` — Card, Tabs, Accordion, Badge, Avatar, Progress.
+- `styling.md` — tokens, layers, Tailwind, slots, `data-*`, dark.
+- `accessibility.md` — what is supplied, what you add.

package/.gbs/skills/gbs-components/references/accessibility.md

@@ -0,0 +1,102 @@
+# Accessibility contract
+
+Each component supplies its own roles, states and keyboard behaviour. A short
+list of things stays yours — mostly names and headings, which only the page
+knows. Do not duplicate what is already supplied: a second `aria-describedby`
+or your own `<label htmlFor>` will fight the built-in wiring.
+
+## What the components supply
+
+| Area | Supplied |
+| --- | --- |
+| **Form fields** | A real native control; `<label>` linked to it via a generated `useId`; `aria-describedby` assembled from the hint, description and error (`{id}-description`, `{id}-error`); `aria-invalid` when `error` is set; `aria-required`. |
+| **CheckboxGroup / RadioGroup** | `role="group"` / `role="radiogroup"` with the `label` as the legend, one shared `name`, one tab stop, arrow-key roving. |
+| **Switch** | `role="switch"` on a real checkbox, so it is announced "on"/"off"; Space toggles, → on and ← off (mirrored in RTL). |
+| **NumberInput** | `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-valuetext`. |
+| **Select / MultiSelect** | `role="combobox"` owning a `role="listbox"`; `aria-expanded`, `aria-controls`, `aria-activedescendant` so focus stays in the search box; `aria-selected` per option. |
+| **Modal** | Native `<dialog>`: top layer, the page behind inert, focus trap, focus return on close. `title` names it. |
+| **Popover** | `aria-expanded` and `aria-controls` on the trigger; `title` names the panel; light dismiss and Escape from the browser; focus returns to the trigger. |
+| **Menu** | The WAI-ARIA menu button pattern: `aria-haspopup`, `aria-expanded`, `role="menu"` / `menuitem`, arrow keys, typeahead, Home/End, submenu arrows, Escape. |
+| **Tooltip** | `aria-describedby` on the child; Escape dismisses from anywhere. |
+| **Toaster** | A labelled landmark, polite live region; error toasts use `role="alert"`; **Alt+T** moves focus to the stack. |
+| **Alert** | `role="alert"` for `danger` / `warning`, `role="status"` otherwise. |
+| **Progress** | `role="progressbar"` with `aria-valuenow` / `min` / `max`, omitted entirely when `value={null}` so it reads as busy. |
+| **Tabs** | `role="tablist"` / `tab` / `tabpanel`, `aria-controls`, arrow keys (mirrored in RTL), Home/End, disabled tabs skipped. |
+| **Accordion** | Native `<details>`/`<summary>`: focusable header, Enter and Space, panel out of the accessibility tree while closed. |
+| **DataGrid** | The WAI-ARIA grid pattern: `role="row"` / `rowgroup`, `aria-colindex`, `aria-rowindex`, `aria-sort` on headers, `aria-multiselectable`, full cell keyboard navigation. |
+| **Skeleton** | Bars are `aria-hidden` — a screen reader gains nothing from a grey box. |
+| **Icons** | Decorative icons inside components are `aria-hidden`. |
+
+## What you must still provide
+
+1. **A `label` on every field.** It is the accessible name. Without it the
+   control is unnamed, whatever the placeholder says.
+
+2. **`aria-label` on icon-only buttons.**
+
+   ```tsx
+   <Button variant="ghost" icon={<TrashIcon />} aria-label="Delete" />
+   ```
+
+   A Tooltip does **not** supply this: it is wired with `aria-describedby`, so
+   the control keeps its own name. An icon button inside a Tooltip still needs
+   `aria-label`.
+
+3. **A name for every overlay.** `Modal` needs `title`, or `aria-label` when it
+   has no visible heading. `Popover` needs `title` or `aria-label` (it defaults
+   to "More information", which says nothing). `Menu` needs `label` (defaults to
+   "Menu").
+
+4. **`aria-label` on `TabList`** — `<TabList aria-label="Project">` — and on
+   `DataGrid` where the grid's purpose is not obvious from the page.
+
+5. **Your own heading levels.** `CardHeader` takes a `title` node, not a level:
+   pass `<h3>Revenue</h3>` so the page owns the document outline.
+
+6. **A name for a set of avatars.** `<AvatarGroup label="Assigned to">` — a row
+   of faces with no name says nothing.
+
+7. **`alt` semantics for Avatar** come from `name`. Set `decorative` when the
+   person's name is already printed next to it, so it is not announced twice.
+
+8. **An accessible route to anything that only appears on hover.** Tooltips are
+   never shown on touch devices and never take focus.
+
+9. **Keyboard bindings for `shortcut` hints.** `MenuItem shortcut="⌘E"` only
+   draws the hint; binding the key is yours.
+
+10. **A visible label for `Stat`** — it takes `label` as a required prop for
+    that reason; a figure alone means nothing.
+
+## Errors and validation
+
+Pass the message as `error`. The component sets `aria-invalid`, renders the
+message with an `{id}-error` id and appends that id to `aria-describedby`.
+Do not add `aria-invalid` or `aria-describedby` yourself.
+
+Order matters and is handled for you: any `aria-describedby` you pass is kept
+first, then the hint, then the description, then the error — the error last
+because it is the part that changes and the part a listener is waiting for.
+
+## Live regions
+
+- `Alert` announces only when its contents change. An alert rendered on first
+  paint says nothing — use a toast for something that just happened.
+- `Toaster` is always in the page as a polite region, so new toasts are read
+  without interrupting; `type: "error"` interrupts.
+- `Spinner` and `Skeleton` both take a `label`. Use one of them, or mark the
+  region busy — not both, or the wait is announced twice.
+
+## Right-to-left
+
+Stylesheets use logical properties (`padding-inline`, `margin-inline`,
+`inset-inline`, `border-inline`, `text-align: start`), so layout follows the
+document's `dir` with no configuration. Arrow-key behaviour mirrors in Menu,
+Switch, Tabs and the DataGrid. `Toaster` accepts an explicit `dir` prop
+(`ltr` `rtl` `auto`) for a region that must differ from the page.
+
+## Reduced motion
+
+Most stylesheets (21 of 27) disable their animations under
+`@media (prefers-reduced-motion: reduce)`. Do not add motion of your own that
+ignores it.

package/.gbs/skills/gbs-components/references/data-display.md

@@ -0,0 +1,185 @@
+# Data display
+
+The DataGrid has its own file: `data-grid.md`.
+
+## Tabs
+
+```tsx
+<Tabs defaultValue="overview">
+  <TabList aria-label="Project">
+    <Tab value="overview">Overview</Tab>
+    <Tab value="activity" badge={3}>Activity</Tab>
+    <Tab value="billing" disabled>Billing</Tab>
+  </TabList>
+  <TabPanel value="overview">…</TabPanel>
+  <TabPanel value="activity">…</TabPanel>
+</Tabs>
+```
+
+**Tabs:** `value`/`defaultValue`/`onValueChange`, `orientation` (`horizontal`
+`vertical`), `activation` (`automatic` `manual`), `variant` (`line` `pills`
+`enclosed`), `size`, `keepMounted`.
+**Tab:** `value` (required), `disabled`, `icon`, `badge`.
+**TabPanel:** `value` (required), `keepMounted`.
+
+`TabList`, `Tab` and `TabPanel` throw outside `<Tabs>`. Arrow keys move between
+tabs (swapped in RTL), Home/End jump, disabled tabs are skipped. `keepMounted`
+preserves hidden panels' state using React's `<Activity>`.
+
+## Accordion
+
+Built on native `<details>`/`<summary>`.
+
+```tsx
+<Accordion defaultValue={["shipping"]} items={[
+  { value: "shipping", title: "Shipping", content: <p>Two to five days.</p> },
+  { value: "returns", title: "Returns", content: <p>Thirty days.</p> },
+]} />
+
+<Accordion multiple variant="contained">
+  <AccordionItem value="one" title="Details" meta={<Badge count={3} />}>…</AccordionItem>
+</Accordion>
+```
+
+**Accordion:** `value`/`defaultValue`/`onValueChange` (string arrays), `items`
+**or** `<AccordionItem>` children, `multiple`, `collapsible`, `variant`
+(`separated` `contained` `plain`), `size`, `iconPosition`, `classNames`, `ref`.
+**AccordionItem:** `value` (required), `title`, `description`, `children`,
+`meta`, `icon`, `disabled`, `classNames` (`root` `header` `title` `description`
+`icon` `content` `body`), `ref` (the `<details>`).
+
+`AccordionItem` throws outside `<Accordion>`.
+
+## Card and Stat
+
+```tsx
+<Card>
+  <CardHeader title={<h3>Revenue</h3>} actions={<Menu trigger={…}>…</Menu>} />
+  <CardBody>
+    <Stat label="This month" value="£48,120"
+      trend={{ direction: trendDirection(12.4), label: "12.4%", description: "vs last month" }} />
+  </CardBody>
+</Card>
+```
+
+**Card:** `variant` (`outlined` `elevated` `plain`), `padding` (`none` `sm` `md`
+`lg`), `href`/`target`/`rel` (renders an `<a>`), `interactive`, `className`,
+`classNames` (`root` `header` `title` `description` `actions` `body` `footer`),
+`style`.
+**CardHeader:** `title`, `description`, `actions`. Pass your own heading element
+as `title` so the page owns the outline level.
+**Stat:** `label` and `value` (both required), `trend`, `help`, `icon`,
+`loading`, plus styling props.
+
+With `href` the card is an `<a>` — keep other links and buttons out of it; use
+`interactive` plus your own handler instead.
+
+## Alert
+
+```tsx
+<Alert variant="warning" title="Your trial ends in 3 days">
+  After that the workspace becomes read-only.
+</Alert>
+<Alert variant="danger" title="We could not save your changes" onDismiss={hide} />
+```
+
+`variant` (`info` `success` `warning` `danger` `neutral`), `size` (`sm` `md`),
+`title`, `description` or `children`, `icon` (a node, or `false`), `actions`,
+`onDismiss`, `classNames` (`root` `icon` `content` `title` `description`
+`actions` `dismiss`), `localeText`, `ref`, and every `<div>` attribute.
+
+Problems get `role="alert"` and interrupt; everything else gets `role="status"`.
+An alert present from first render announces nothing — live regions only speak
+on change.
+
+## Badge and Tag
+
+```tsx
+<Badge variant="success">Active</Badge>
+<Badge variant="danger" appearance="solid" count={128} />
+<Tag onRemove={() => remove("berlin")}>Berlin</Tag>
+```
+
+**Badge:** `children` or `count`, `variant` (`neutral` `accent` `success`
+`warning` `danger` `info`), `appearance` (`soft` `solid` `outline`), `size`
+(`sm` `md`), `max`, `showZero`, `formatValue`, `dot`, `icon`, `classNames`
+(`root` `dot` `icon` `label`), `ref`, and every `<span>` attribute.
+**Tag:** the same variants plus `onRemove`, `label` (names the remove button when
+the children are not a plain string), `disabled`, `classNames` (`root` `icon`
+`label` `remove`), `localeText`.
+
+A `count` of zero renders nothing unless `showZero`.
+
+## Avatar and AvatarGroup
+
+**Avatar:** `name` (alt text, initials and a stable colour), `src`, `initials`,
+`children`, `size` (`md`, 32px), `shape` (`circle`), `status`, `decorative`,
+`className`, `classNames`, `style`, `localeText`, `ref`, and every `<span>`
+attribute. A failed image falls back to initials.
+**AvatarGroup:** `children` (required), `max` (4, counting the overflow bubble),
+`size`, `shape`, `label` (names the set), plus the usual styling props.
+
+## Progress and CircularProgress
+
+```tsx
+<Progress label="Uploading report.pdf" value={62} showValue />
+<Progress value={null} label="Preparing export" />
+<CircularProgress value={62} size={56} showValue />
+```
+
+**Progress:** `value` (`number | null`), `max`, `label`, `showValue`,
+`valueText`, `variant` (`accent` `success` `warning` `danger`), `size` (`sm`
+`md` `lg`), `classNames` (`root` `header` `label` `value` `track` `bar`),
+`localeText`, `ref`, and every `<div>` attribute.
+**CircularProgress:** the same value props plus `size` (pixels), `thickness`,
+`showValue` or `children` for the middle.
+
+`value={null}` is indeterminate: `aria-valuenow` is omitted, so a screen reader
+says "busy". Use a Spinner when there is nothing to measure at all.
+
+## Skeleton and Empty
+
+```tsx
+{loading ? <Skeleton lines={3} label="Loading activity" />
+ : items.length === 0 ? <Empty title="No activity yet" description="…" actions={<Button…/>} />
+ : <ActivityList items={items} />}
+```
+
+**Skeleton:** `variant` (`text` `circle` `rect`), `lines` (1),
+`lastLineWidth` (60), `width`, `height`, `radius` (number = pixels, string used
+as given), `animation` (`pulse` `wave` `none`), `label`, `className`,
+`classNames` (`root` `line`), `style`. Bars are hidden from assistive tech;
+`label` is what gets announced.
+**Empty:** `title`, `description`, `actions`.
+
+## Spinner
+
+```tsx
+<Spinner />
+<Spinner size="sm" showLabel label="Saving…" />
+<Spinner loading={isPending} delay={250} minDuration={600}><Chart /></Spinner>
+```
+
+`loading` (true; with children, covers them), `size` (`xs` 12 · `sm` 16 · `md`
+24 · `lg` 32 · `xl` 48, or a pixel number), `variant` (`ring` `dots`), `label`
+("Loading"), `showLabel`, `delay` (0), `minDuration` (0), `className`,
+`classNames` (`root` `status` `indicator` `label` `content` `overlay`), `style`,
+`localeText`. `useDelayedLoading(loading, { delay, minDuration })` applies the
+same timing to any loading UI.
+
+## Breadcrumb
+
+```tsx
+<Breadcrumb
+  items={[{ label: "Home", href: "/" }, { label: "Invoices", href: "/invoices" },
+          { label: "INV-2026-0042" }]}
+  maxItems={4}
+  renderLink={(props) => <Link {...props} />}
+  structuredData={{ baseUrl: "https://app.example.com" }} />
+```
+
+`items` (required; `{ label, href?, icon?, name?, onClick? }`, top level first,
+last is the current page), `separator`, `maxItems`, `itemsBeforeCollapse` (1),
+`itemsAfterCollapse` (1), `renderLink`, `structuredData`, `size` (`md`),
+`className`, `classNames` (`root` `list` `item` `link` `current` `separator`
+`ellipsis`), `localeText`. Use `renderLink` for a router link — no `asChild`.

package/.gbs/skills/gbs-components/references/data-grid.md

@@ -0,0 +1,117 @@
+# DataGrid
+
+A virtualized grid. Import `DataGrid` and `createColumnHelper` from
+`component-lib/data-grid` and the stylesheet once.
+
+```tsx
+import { createColumnHelper, DataGrid } from "component-lib/data-grid";
+import "component-lib/data-grid/styles.css";
+
+interface Employee { id: number; name: string; salary: number; active: boolean }
+
+const col = createColumnHelper<Employee>();
+
+// Define columns at module level, or memoize them.
+const columns = [
+  col.field("id", { header: "ID", type: "number", width: 80, pin: "left" }),
+  col.field("name", { width: 200 }),
+  col.field("salary", { type: "number", format: (v) => `$${v.toLocaleString()}` }),
+  col.field("active", { type: "boolean" }),
+];
+
+export function Employees({ data }: { data: Employee[] }) {
+  return <DataGrid data={data} columns={columns} getRowId="id" enableRowSelection height={600} />;
+}
+```
+
+**Keep `data`, `columns` and `getRowId` stable.** The grid memoizes on their
+identity. Define columns at module level or in `useMemo`, and pass `getRowId` as
+a property name (`getRowId="id"`). With React Compiler on, inline values are
+memoized for you.
+
+## Props
+
+From `GridOptions<T>`: `data` (required), `columns` (required), `getRowId`,
+`mode` (`client` | `server`), `rowCount` (server mode), `state`, `initialState`,
+`onStateChange`, `onQueryChange`, `enableRowSelection`, `enableMultiSort`,
+`exportFileName`, and the feature toggles.
+
+From `DataGridProps<T>`: `ref` (`Ref<GridApi<T>>`), `height` (`number | string`,
+520; ignored with `autoHeight`), `autoHeight`, `rowHeight` (defaults to the
+density: compact 32, standard 40, comfortable 52), `headerHeight`, `loading`,
+`toolbar` (`boolean | ToolbarOptions` — search, columns, export, density),
+`pageSizeOptions` (`[25, 50, 100, 250]`), `emptyState`, `getRowClassName`,
+`locale` (BCP 47), `localeText`, `className`, `classNames`, `style`,
+`aria-label`.
+
+Slots: `root`, `toolbar`, `viewport`, `header`, `headerCell`, `row`, `cell`,
+`pagination`.
+
+## Columns
+
+| Option | Purpose |
+| --- | --- |
+| `field` / `accessor` / `id` | Where the value comes from. Display-only columns need just `id` and `cell`. |
+| `header`, `width`, `minWidth`, `maxWidth`, `align` | Presentation. |
+| `type` | `string` (default), `number`, `date`, `boolean`. Drives filter operators, sorting, alignment, editors, Excel cell types. |
+| `options` | `{ label, value }[]` for enum columns: "is any of" filter, select editor, label display. |
+| `format(value, row)` | Display text. Also used by search, CSV, PDF and copy. |
+| `cell` | Custom renderer. |
+| `editable`, `validate` | Inline editing with validation. |
+| `pin` | `"left"` or `"right"`. |
+| `exportable` | `false` keeps the column out of exports and copy. |
+
+`createColumnHelper<T>()` infers the value type for `cell`, `format`, `validate`
+and `sortFn`. Plain `ColumnDef<T>[]` objects also work.
+
+## Imperative API
+
+```tsx
+const api = useRef<GridApi<Employee>>(null);
+<DataGrid ref={api} … />
+
+api.current?.setFilter("status", { operator: "in", value: ["active"] });
+api.current?.exportExcel({ scope: "selected", fileName: "people" });
+api.current?.focusCell(0, "name");
+```
+
+Methods: `getState`, `setState`, `toggleSort`, `setSorting`, `setFilter`,
+`clearFilters`, `setGlobalFilter`, `setPageIndex`, `setPageSize`,
+`toggleRowSelected`, `toggleAllRowsSelected`, `clearSelection`,
+`getSelectedRowIds`, `getSelectedRows`, `setColumnVisibility`, `setColumnWidth`,
+`pinColumn`, `moveColumn`, `resetColumns`, `scrollToRow`, `focusCell`,
+`startEditing`, `cancelEditing`, `getRows`, `exportCsv`, `exportExcel`,
+`exportPdf`, `print`, `copyToClipboard`.
+
+## Export
+
+Export code is split into chunks loaded on first use. Scopes: `filtered`
+(default), `all`, `selected`, `page`, or pass `rows`.
+
+- `exportCsv` — UTF-8 with BOM; cells starting with `= + - @` get a `'` prefix
+  against formula injection.
+- `exportExcel` — real `.xlsx`: typed numbers, booleans and dates, bold frozen
+  header, auto-filter, column widths.
+- `exportPdf` — writes a real `.pdf` and downloads it: paper size, orientation,
+  repeated header row, page numbers, your own header/footer bands.
+- `print` — opens the browser's print dialog instead, for paper or for text the
+  PDF's Latin-1 fonts cannot encode.
+
+```tsx
+api.current?.exportPdf({
+  title: "Q3 headcount",
+  orientation: "landscape",
+  paperSize: "A4",                 // A3 A4 A5 letter legal
+  footer: { left: "Confidential", right: "Page {page} of {pages}" },
+});
+```
+
+Band tokens: `{title}`, `{page}`, `{pages}`, `{date}`, `{time}`. Also `margin`
+(points), `fontSize`, `header`, and `theme` (`text` `muted` `border` `headerBg`
+`headerText` `stripe`). PDF text is WinAnsi/Latin-1; other scripts become `?` —
+use `print()` for those.
+
+## Server mode
+
+Set `mode="server"`, pass the current page as `data` and the total as
+`rowCount`, and fetch in `onQueryChange`.