gbs-add-block 2.0.1 → 2.0.3

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

@@ -0,0 +1,202 @@
+# Forms
+
+Every field is a real native control with the label, hint and error wired
+around it. Pass `label`, `description` and `error` as props — never build that
+markup yourself.
+
+## The shared field contract
+
+All of Input, Textarea, NumberInput, OtpInput, Checkbox, CheckboxGroup, Radio,
+RadioGroup, Switch, Select, MultiSelect, DatePicker, DateRangePicker and
+FileUploader accept:
+
+- `label` (`ReactNode`) — the field's accessible name.
+- `description` (`ReactNode`) — hint below the control, linked with `aria-describedby`.
+- `error` (`ReactNode`) — message below the control; **also marks it invalid**.
+- `size` — `"sm" | "md" | "lg"`, default `md`.
+- `disabled`, `required` — native states.
+- `classNames` — `Partial<Record<Slot, string>>`; slots differ per component.
+- `localeText` — overrides the built-in UI strings.
+- `className`, `style` — applied to the root element.
+
+Ids come from `useId`; `describeField` (in `shared/core/field.ts`) builds the
+describedby chain as `{id}-description` and `{id}-error`. Pass your own `id` to
+override the generated one.
+
+## Controlled vs uncontrolled
+
+Every field supports both. Pass `value`/`checked` **with** its change handler
+for controlled, or `defaultValue`/`defaultChecked` for uncontrolled. Mixing them
+(a `value` with no handler) leaves the field frozen.
+
+**The handler name differs per component:**
+
+- `onValueChange(value: string)` — Input, OtpInput, Textarea
+- `onValueChange(value: number | null)` — NumberInput
+- `onValueChange(values: string[])` — CheckboxGroup
+- `onValueChange(value: string | null)` — RadioGroup
+- `onCheckedChange(checked: boolean)` — Checkbox
+- `onCheckedChange(checked: boolean): void | Promise<unknown>` — Switch
+- `onChange(value: V | null, option)` — Select
+- `onChange(values: V[], options)` — MultiSelect
+- `onChange(date: Date | null)` — DatePicker
+- `onChange(range, complete: boolean)` — DateRangePicker
+
+Input, Textarea and NumberInput also fire the native `onChange` alongside
+`onValueChange`, so form libraries that hook the native event keep working.
+
+## Native form posting
+
+Give the field a `name` and it posts like a native control. `Select` and
+`MultiSelect` render hidden inputs (one per value); FileUploader without an
+`endpoint` posts the files with the form.
+
+## Input
+
+All `<input>` attributes, plus:
+
+`value`, `defaultValue`, `onValueChange`, `label`, `description`, `error`,
+`size`, `leading`, `trailing`, `clearable` (default `false`), `revealPassword`
+(default `true`, for `type="password"`), `showCount`, `classNames`,
+`localeText`, `ref` (the `<input>` element).
+
+Slots: `root`, `label`, `control`, `input`, `description`, `error`, `count`.
+
+```tsx
+<Input label="Email" type="email" value={email} onValueChange={setEmail} clearable />
+<Input label="Weight" trailing="kg" showCount maxLength={6} />
+```
+
+## OtpInput
+
+One real `<input>` drawn as cells, so SMS autofill
+(`autocomplete="one-time-code"`), paste and screen readers treat it as one field.
+
+`length` (6), `mode` (`numeric` `alphanumeric` `alphabetic`), `uppercase`,
+`value`, `defaultValue`, `onValueChange`, `onComplete`, `groups`, `mask`,
+`label`, `description`, `error`, `size`, `name`, `required`, `disabled`,
+`classNames` (`root` `label` `cells` `cell` `separator` `description` `error`),
+`localeText`, `ref`.
+
+```tsx
+<OtpInput label="Code" groups={[3, 3]} onComplete={verify} />
+```
+
+## Textarea
+
+All `<textarea>` attributes, plus `value`, `defaultValue`, `onValueChange`,
+`label`, `description`, `error`, `size`, `autoResize`, `minRows`, `maxRows`,
+`resize` (`none` `vertical` `horizontal` `both`), `showCount`, `localeText`,
+`ref`, `classNames` (`root` `label` `textarea` `description` `error` `count`).
+
+```tsx
+<Textarea label="Notes" value={notes} onValueChange={setNotes}
+  autoResize minRows={2} maxRows={8} maxLength={500} showCount />
+```
+
+## NumberInput
+
+A text input with `role="spinbutton"`, not `<input type="number">` — so the
+wheel cannot silently edit it, a partially typed number is not lost, and
+locale notation like `1.234,56` parses.
+
+`value`/`defaultValue`/`onValueChange` (`number | null`), `min`, `max`, `step`,
+`largeStep`, `snapToStep`, `decimals`, `locale`, `format` (`decimal` `currency`
+`percent`), `currency`, `useGrouping`, `clampBehavior` (`blur` `strict` `none`),
+`stepper`, `wheel`, `selectOnFocus`, `clearable`, `label`, `description`,
+`error`, `size`, `leading`, `trailing`, `disabled`, `readOnly`, `required`,
+`localeText`, `ref`, every `<input>` attribute, and `classNames` (`root`
+`label` `control` `input` `stepper` `description` `error`).
+
+```tsx
+<NumberInput label="Quantity" min={1} max={99} value={qty} onValueChange={setQty} />
+<NumberInput label="Amount" format="currency" currency="USD" decimals={2} locale="en-US" />
+{/* 45% in the field is 0.45 in the value */}
+<NumberInput label="Discount" format="percent" step={0.01} min={0} max={1} />
+```
+
+Keyboard: ↑/↓ step, PageUp/PageDown by `largeStep`, Home/End jump to
+`min`/`max`, Escape restores the last committed number.
+
+## Checkbox and CheckboxGroup
+
+The box is a real `<input type="checkbox">`.
+
+**Checkbox:** `checked`/`defaultChecked` (`true`, `false` or `"indeterminate"`),
+`onCheckedChange`, `value`, `label`, `description`, `error`, `size`, `ref`,
+every `<input>` attribute, and `classNames` (`root` `control` `input` `label`
+`description` `error`).
+
+**CheckboxGroup:** `value`/`defaultValue`/`onValueChange` (string arrays),
+`options` **or** `<Checkbox value>` children, `label` (a legend), `description`,
+`error`, `required`, `disabled`, `name`, `size`, `orientation`, `selectAll`,
+`localeText`, `classNames` (`root` `legend` `description` `items` `error`).
+
+```tsx
+<Checkbox label="Remember me" name="remember" checked={remember} onCheckedChange={setRemember} />
+
+<CheckboxGroup label="Notify me by" name="channels" selectAll
+  options={[{ value: "email", label: "Email" }, { value: "sms", label: "SMS" }]}
+  value={channels} onValueChange={setChannels} />
+```
+
+## Radio and RadioGroup
+
+Real `<input type="radio">` elements sharing a `name`, so arrow keys roam the
+group, the group is one tab stop, and the browser validates it as one required
+field.
+
+**RadioGroup:** `value`/`defaultValue`/`onValueChange` (`string | null`),
+`options` (plain strings or full option objects) **or** `<Radio value>`
+children, `label` (a legend), `description`, `error`, `required`, `disabled`,
+`name`, `size`, `orientation`, `variant` (`default` `card`), `clearable`,
+`localeText`, `classNames` (`root` `legend` `description` `items` `clear`
+`error`).
+
+**Radio:** `value` (required), `label`, `description`, `error`, `size`,
+`disabled`, `classNames`, `ref`, every `<input>` attribute.
+
+```tsx
+<RadioGroup label="Send the report" name="frequency"
+  options={["Daily", "Weekly", "Monthly"]} value={freq} onValueChange={setFreq} />
+
+{/* variant="card" draws tiles, for choices that need explaining. */}
+<RadioGroup label="Plan" variant="card" defaultValue="team" options={[
+  { value: "starter", label: "Starter", description: "Up to 3 projects" },
+  { value: "team", label: "Team", description: "Unlimited projects" },
+]} />
+```
+
+A radio cannot be unselected by clicking, so an optional question needs
+`clearable` or a "None" option.
+
+## Switch
+
+Use a Switch when flipping it **is** the action; use a Checkbox when the value
+is submitted later with a form.
+
+`checked`/`defaultChecked`/`onCheckedChange` (may return a promise), `value`,
+`label`, `description`, `error`, `size`, `labelPosition` (`end` `start`),
+`loading`, `disabled`, `readOnly`, `required`, `name`, `localeText`, `ref`,
+every `<input>` attribute, and `classNames` (`root` `control` `input` `track`
+`thumb` `label` `description` `error`).
+
+Return a promise from `onCheckedChange` and the switch shows the new setting,
+spins while it saves, and reverts if the save fails.
+
+```tsx
+<Switch label="Two-factor authentication" checked={enabled}
+  onCheckedChange={(next) => api.setTwoFactor(next)} />
+```
+
+## Select, DatePicker, FileUploader
+
+Those live in `pickers.md` — they are the fields that take `onChange` rather
+than `onValueChange`.
+
+## Validation
+
+There is no form library here. Compute the message yourself and pass it as
+`error`; the component handles `aria-invalid`, `aria-describedby` and the
+styling. With React Hook Form or similar, wire `value` and the component's own
+handler name, and pass `error={errors.field?.message}`.

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

@@ -0,0 +1,189 @@
+# Installing and updating GBS components
+
+## The distribution model
+
+`gbs-add-block` is **not a runtime dependency**. It is a CLI that copies
+TypeScript source into the consuming repo, the way shadcn/ui does. Nothing is
+imported from `node_modules` at runtime, and the copied files are yours to edit.
+
+`package.json` of the library declares no `main` and no `exports` — only
+`bin: { "gbs-add-block": "index.cjs" }` and `files: ["index.cjs", "source",
+".gbs"]`. There is nothing to `import "gbs-add-block"` from.
+
+Peer dependencies: `react@^19` and `react-dom@^19`. The beta components have no
+other runtime dependencies.
+
+## Commands
+
+```bash
+npx gbs-add-block -a Button --beta                 # one component
+npx gbs-add-block -a Button,Input,Modal --beta     # several
+npx gbs-add-block -i --beta                        # interactive picker
+npx gbs-add-block -l --beta                        # list available
+npx gbs-add-block -a Button --beta --force         # overwrite edited shared/ files
+npx gbs-add-block -skill                           # install this skill
+npx gbs-add-block -skill --for claude              # only the Claude Code copy
+```
+
+| Flag | Alias | Meaning |
+| --- | --- | --- |
+| `--add` | `-a` | Component, or comma-separated list. Case-insensitive. |
+| `--interactive` | `-i` | Pick from a menu. |
+| `--list` | `-l` | Print available components. |
+| `--beta` | — | Install the 2.0 redesigned components. `-beta` also works. |
+| `--skill` | — | Install this skill at the project root. `-skill` and `-a skill` also work. |
+| `--for` | — | With `--skill`: which agents to write adapters for (`claude`, `codex`, `antigravity`, or `none`). Default: all. |
+| `--force` | — | Replace files you have edited locally in `shared/` or `.gbs/`. |
+
+**Always pass `--beta`.** Without it you get the 1.x set (`Select`, `SideBar`,
+`FormRenderer`, `MaterialInput`, `ContextMenu`, `Navbar`, `Bargraph`,
+`DarkMode`, `Toast`, `Uploader`, `UsePaginatedData`, `UseUploader` and others),
+which is a different, older API with different props. The two sets are not
+interchangeable.
+
+## Installing this skill
+
+```bash
+npx gbs-add-block@latest -skill
+```
+
+Writes to the project root — not into `component-lib/`. Each agent reads a
+different location, so the CLI writes one copy per agent from the same source:
+
+| Path | For |
+| --- | --- |
+| `.gbs/skills/gbs-components/` | GBS SE Agent. Canonical; always written. |
+| `.claude/skills/gbs-components/` | Claude Code. Full copy; `autoAttach` becomes `paths`. |
+| `.agents/rules/gbs-components.md` | Antigravity. One file; set its glob in the IDE. |
+| `AGENTS.md` | Codex. A pointer inside `gbs-add-block` markers. |
+
+`--for claude,codex` narrows it; `--for none` writes only `.gbs/`. Switching
+targets removes the adapters you dropped.
+
+Re-running updates everything. A file edited since the CLI wrote it is never
+replaced without `--force`, tracked by sha256 in `.gbs/.install-manifest.json`.
+`AGENTS.md` is the exception: the project owns that file, so only the marked
+block is rewritten.
+
+It can be combined with a component install:
+
+```bash
+npx gbs-add-block -a DataGrid -beta -skill
+```
+
+## Where files land
+
+Always `<cwd>/component-lib/`. The destination is not configurable, so run the
+CLI from the repo root (or move the folder afterwards and fix the imports).
+
+```
+component-lib/
+  shared/          installed with every beta component
+  button/
+  data-grid/
+  input/
+```
+
+## Folder names
+
+The folder is the lowercased component name, with five exceptions:
+
+| Component | Folder |
+| --- | --- |
+| `DataGrid` | `data-grid` |
+| `DatePicker` | `date-picker` |
+| `FileUploader` | `file-uploader` |
+| `NumberInput` | `number-input` |
+| `RadioGroup` | `radio-group` |
+
+Everything else: `Button` → `button`, `Combobox` → `combobox`, `Toaster` →
+`toaster`, and so on.
+
+Note the mismatch between the install name and the import name for two of them:
+
+- Install `Combobox`; import `Select` and `MultiSelect` from `component-lib/combobox`.
+- Install `Toaster`; import `toast` and `Toaster` from `component-lib/toaster`.
+- Install `Dialog`; import `dialog` and `DialogHost` from `component-lib/dialog`.
+
+## Available beta components
+
+`DataGrid`, `Combobox`, `DatePicker`, `Toaster`, `FileUploader`, `Dialog`,
+`Input`, `Modal`, `Textarea`, `Button`, `Breadcrumb`, `Checkbox`, `Tabs`,
+`Spinner`, `Menu`, `Tooltip`, `Popover`, `Card`, `Skeleton`, `NumberInput`,
+`RadioGroup`, `Switch`, `Accordion`, `Alert`, `Avatar`, `Badge`, `Progress`.
+
+`Skeleton` also brings `Empty`; `Card` also brings `Stat`; `Badge` also brings
+`Tag`; `Avatar` also brings `AvatarGroup`; `Input` also brings `OtpInput`;
+`Progress` also brings `CircularProgress`.
+
+## What each folder contains
+
+```
+component-lib/input/
+  index.ts        the barrel — import from here
+  core/           framework-free logic, no React import
+  react/          the components
+  styles.css      import once
+  README.md       full prop documentation
+```
+
+Tests are deliberately **not** copied: they import `vitest`, which the consuming
+project has no reason to have.
+
+## The shared folder
+
+Every beta component imports `../../shared`. The CLI installs it alongside
+whatever you picked, and it is versioned independently (`shared/version.json`).
+
+Rules the installer enforces:
+
+- `shared/` only moves forward. If the project has a newer version than the CLI
+  carries, the install aborts rather than downgrading it.
+- A file you edited since the CLI wrote it is never replaced without `--force`.
+  It tracks this with sha256 hashes in `component-lib/shared/.install-manifest.json`.
+
+**Do not edit `component-lib/shared/`.** Components are yours to change; shared
+is replaced on update. Put your changes in your own module instead.
+
+`shared` exports `cx`, `countCharacters`, `describeField`,
+`useControllableState`, `AnchoredPopover`, `placePopover`, `icons` and
+`sharedVersion`.
+
+## Importing
+
+Import the barrel in the component that uses it:
+
+```ts
+import { Input, OtpInput } from "component-lib/input";
+```
+
+Put the stylesheet in the project's global CSS, once — never in a component file:
+
+```css
+@import "../component-lib/input/styles.css";
+```
+
+Most repos set a path alias. The library's own READMEs are written with
+`@/components/<folder>`; the DataGrid README uses `component-lib/data-grid`.
+Both mean the installed folder — follow whatever the host repo already uses.
+
+### Public entry points
+
+| Path | Contents |
+| --- | --- |
+| `component-lib/<folder>` | Components, hooks, types, locale defaults. **Use this.** |
+| `component-lib/<folder>/core` | Framework-free helpers; safe on a server. Documented per component. |
+| `component-lib/<folder>/styles.css` | The stylesheet. |
+| `component-lib/shared` | Shared helpers, mostly used by the components themselves. |
+
+Anything deeper (`component-lib/input/react/Input`) is internal. It will resolve,
+but it is not a supported path and re-running the CLI may move it.
+
+## Next.js
+
+Every React file in the library starts with `"use client"`. A Server Component
+can render them, but cannot pass function props (`onValueChange`, `onClick`,
+`footer={({ close }) => …}`). Put the interactive part in a Client Component.
+
+`toast()` does nothing during a server render. Call it in the browser, for
+example after a Server Action resolves.

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

@@ -0,0 +1,206 @@
+# Overlays
+
+Modal, Dialog, Popover, Menu, Tooltip and Toaster. All render in the browser's
+top layer (native `<dialog>` or the Popover API) or a portal on `<body>`, so no
+parent's `overflow`, `transform` or `z-index` can clip them. You never need a
+portal, a z-index or a focus trap of your own.
+
+## Choosing one
+
+| | Interrupts | Lives | Use for |
+| --- | --- | --- | --- |
+| **Modal** | Yes, blocks | Top layer | A task or form that owns the screen |
+| **dialog.confirm** | Yes, blocks | Top layer | A decision that must happen now |
+| **Popover** | No | Top layer | A panel of controls tied to a trigger |
+| **Menu** | No | Top layer | A list of commands |
+| **Tooltip** | No | Top layer | A few words of label on hover/focus |
+| **toast** | No, and leaves | A corner | Confirming what already happened |
+| **Alert** | No, and stays | In the layout | The state a page or section is in |
+
+## Modal
+
+Built on native `<dialog>`: the browser supplies the top layer, the inert page
+behind, the focus trap and focus return. The component adds controlled state,
+dismiss rules, a close guard, sizes, drawers and animation.
+
+```tsx
+import { Modal } from "component-lib/modal";
+
+const [open, setOpen] = useState(false);
+
+<Modal open={open} onOpenChange={setOpen} title="Edit profile"
+  footer={({ close }) => <Button onClick={close}>Done</Button>}>
+  …
+</Modal>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` / `boolean` / `(open, reason?) => void` | — / `false` | Controlled or uncontrolled. `reason` is `escape`, `backdrop`, `close-button` or `api`. |
+| `title`, `description` | `ReactNode` | — | Header text. |
+| `aria-label` | `string` | — | Names a modal that has no `title`. |
+| `children`, `footer` | `ReactNode \| ({ close }) => ReactNode` | — | Body and footer. |
+| `size` | `sm` `md` `lg` `xl` `full` | `md` | 400 / 520 / 720 / 960 px, or the whole screen. |
+| `placement` | `center` `top` `left` `right` `bottom` | `center` | `left`, `right` and `bottom` are drawers. |
+| `closeButton`, `closeOnEscape`, `closeOnBackdrop` | `boolean` | `true` | Dismiss options. |
+| `onBeforeClose` | `(reason) => boolean \| Promise<boolean>` | — | Return `false` to stay open. |
+| `initialFocus` | `RefObject<HTMLElement>` | — | Otherwise `[data-autofocus]`, then the first focusable element. |
+| `keepMounted` | `boolean` | `false` | Keep the content's state while closed. |
+| `className`, `classNames`, `style`, `localeText`, `id`, `ref` | — | — | Slots below. |
+
+Slots: `root`, `header`, `title`, `description`, `close`, `body`, `footer`.
+`ref` exposes `open()`, `close()`, `getElement()`.
+
+Guard an unsaved form:
+
+```tsx
+<Modal open={open} onOpenChange={setOpen}
+  onBeforeClose={async (reason) =>
+    reason === "api" || !dirty || dialog.confirm({ title: "Discard changes?" })}>
+```
+
+Known limits: exit animations need `transition-behavior: allow-discrete`
+(Chrome 117+, Safari 18+); elsewhere it closes instantly. Scroll lock uses
+`:root:has(.md-root[open])`, which can shift content by the scrollbar's width.
+
+## dialog (alert / confirm / prompt)
+
+A promise-based API for the decisions a Modal is too heavy for. Mount the host
+**once** near the root; then call `dialog.*` from anywhere, including outside
+React.
+
+```tsx
+// once, e.g. app/layout.tsx or App.tsx
+import { DialogHost } from "component-lib/dialog";
+<DialogHost />
+
+// anywhere
+import { dialog } from "component-lib/dialog";
+
+if (await dialog.confirm({ title: "Delete 3 invoices?", intent: "danger", confirmLabel: "Delete" })) {
+  await deleteInvoices();
+}
+const name = await dialog.prompt({ title: "Rename", defaultValue: "report.pdf", required: true });
+await dialog.alert("Export finished");
+```
+
+- `alert` resolves when closed, `confirm` resolves `true`/`false`, `prompt`
+  resolves the text or `null`.
+- `onConfirm` may be async: the dialog shows progress, and if it throws, shows
+  the error and stays open.
+- Requests queue and show one at a time.
+- Where there is no document (a server render) they resolve as canceled.
+
+Options: `title`, `description`, `intent` (`default` `info` `success` `warning`
+`danger`), `icon`, `confirmLabel`, `cancelLabel`, `dismissible`, `size`
+(`sm` `md`), `onConfirm`. Prompt adds `defaultValue`, `placeholder`,
+`inputLabel`, `inputType`, `required`, `validate`.
+
+`<Dialog open onClose>` is the same dialog as an ordinary controlled component,
+if you would rather not use the queue. `createDialogStore()` and
+`createDialogApi(store)` build isolated instances; pass the store to
+`<DialogHost store={store} />`.
+
+## Popover
+
+```tsx
+<Popover trigger={<Button variant="outline">Filters</Button>} title="Filters">
+  {({ close }) => (
+    <>
+      <Checkbox label="Only active" />
+      <Button size="sm" onClick={close}>Apply</Button>
+    </>
+  )}
+</Popover>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `trigger` | required | A **single** element, cloned with a ref and the ARIA wiring. |
+| `open` / `defaultOpen` / `onOpenChange` | — | Reason: `escape`, `outside`, `trigger`, `api`. |
+| `title` / `description` | — | Heading inside the panel; `title` also names it. |
+| `aria-label` | "More information" | Names the panel when there is no `title`. |
+| `side` / `align` | `bottom` / `start` | Flips and clamps to stay on screen. |
+| `gap` | `6` | Distance from the trigger, in pixels. |
+| `scrollable` | `false` | Cap the height to the space available and scroll. |
+| `autoFocus` | `true` | Move focus into the panel on open. |
+| `className`, `classNames`, `style`, `localeText` | — | Slots: `root`, `panel`, `header`, `title`, `description`, `body`. |
+
+`children` may be a function receiving `{ close }`. The browser provides light
+dismiss and Escape; focus returns to the trigger. `data-side` on the root says
+which side it settled on after flipping.
+
+## Menu
+
+The WAI-ARIA menu button pattern. Use it for commands, not for a form control —
+for picking a value use `Select`.
+
+```tsx
+import {
+  Menu, MenuItem, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem,
+  MenuGroup, MenuSeparator, MenuSub,
+} from "component-lib/menu";
+
+<Menu trigger={<Button variant="outline">Actions</Button>} label="Row actions">
+  <MenuItem icon={<EditIcon />} shortcut="⌘E" onSelect={edit}>Edit</MenuItem>
+  <MenuSub label="Export">
+    <MenuItem onSelect={() => download("csv")}>CSV</MenuItem>
+    <MenuItem onSelect={() => download("pdf")}>PDF</MenuItem>
+  </MenuSub>
+  <MenuSeparator />
+  <MenuCheckboxItem checked={compact} onCheckedChange={setCompact}>Compact rows</MenuCheckboxItem>
+  <MenuSeparator />
+  <MenuItem destructive onSelect={remove}>Delete</MenuItem>
+</Menu>
+```
+
+**Menu:** `trigger` (required, a single element), `open`/`defaultOpen`/
+`onOpenChange` (reasons `escape`, `outside`, `trigger`, `select`, `api`),
+`label` ("Menu"), `side`/`align`/`gap` (`bottom`/`start`/`4`), `closeOnSelect`
+(true), `className`, `classNames`, `style`, `localeText`.
+
+Slots: `root`, `list`, `item`, `icon`, `label`, `shortcut`, `separator`,
+`group`, `groupLabel`, `indicator`, `submenu`.
+
+| Item | Props |
+| --- | --- |
+| `MenuItem` | `onSelect`, `icon`, `shortcut`, `disabled`, `destructive`. Closes the menu by default. |
+| `MenuCheckboxItem` | `checked` / `onCheckedChange`. Stays open, so several can be toggled. |
+| `MenuRadioGroup` + `MenuRadioItem` | `value` / `onValueChange` on the group, `value` on each item. |
+| `MenuGroup` | A titled section; the title is a label, never focused. |
+| `MenuSeparator` | A rule between sections. |
+| `MenuSub` | A nested menu; opens on hover, Enter, or the arrow pointing into it. |
+
+`shortcut` only draws the hint — binding the key is yours.
+
+Keyboard: ↓/↑ on the trigger open at the first/last item; ↓/↑ move and wrap;
+Home/End jump; letters typeahead; Enter/Space choose; →/← open a submenu or go
+back (mirrored in RTL); Escape closes and returns focus; Tab closes and moves on.
+Disabled items stay focusable but arrow keys skip them.
+
+## Tooltip
+
+```tsx
+<Tooltip content="Export as CSV">
+  <Button variant="ghost" aria-label="Export"><DownloadIcon /></Button>
+</Tooltip>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `content` | required | The label. A few words; longer content belongs in a Popover. |
+| `children` | required | A **single** element, cloned with a ref, handlers and `aria-describedby`. |
+| `side` / `align` / `gap` | `top` / `center` / `6` | Flips and clamps. |
+| `delay` | `400` | Wait before showing on hover. Keyboard focus never waits. |
+| `closeDelay` | `120` | Wait before hiding. |
+| `disabled` | `false` | Never show it. |
+| `className`, `classNames`, `style` | — | Slots: `root`, `content`. |
+
+**It describes, it does not name.** The tooltip is wired with
+`aria-describedby`, so an icon button still needs its own `aria-label`. It never
+takes focus, is `pointer-events: none`, and touch devices never see it — so
+nothing essential may live only there.
+
+## Toaster
+
+See `toaster.md`.

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

@@ -0,0 +1,83 @@
+# Pickers
+
+Select, MultiSelect, DatePicker, DateRangePicker and FileUploader. They share the
+field contract in `forms.md` (`label`, `description`, `error`, `size`,
+`classNames`, `localeText`) but all four use **`onChange`**, not `onValueChange`.
+
+## Select and MultiSelect
+
+Import both from `component-lib/combobox`.
+
+```ts
+interface ComboboxOption<V = string> {
+  value: V;              // string or number
+  label: string;
+  description?: string;  // second line
+  group?: string;        // heading, in first-seen order
+  disabled?: boolean;
+  icon?: ReactNode;
+  keywords?: string[];   // extra search terms
+}
+```
+
+Shared props: `options` (required), `mode` (`client` | `server`), `loading`,
+`onSearchChange`, `searchDebounce` (250), `searchable` (true), `hasMore`,
+`onLoadMore`, `filterFn`, `renderOption`, `allowCreate`, `onCreate`, `label`,
+`description`, `error`, `placeholder` ("Select…"), `required`, `disabled`,
+`clearable` (true), `size`, `name`, `maxHeight` (280), `virtualize` (true above
+80 options), `emptyMessage`, `className`, `style`, `localeText`,
+`onOpenChange`, `ref`, and `classNames` (`root` `label` `control` `value` `tag`
+`popover` `search` `list` `option` `footer`).
+
+`Select` adds `value`/`defaultValue` (`V | null`) and `closeOnSelect` (true).
+`MultiSelect` adds `value`/`defaultValue` (`V[]`), `max`, `maxVisibleTags` (3),
+`showSelectAll` (true) and `closeOnSelect` (false).
+
+`ref` gives `open()`, `close()`, `toggle()`, `focus()`, `clear()`, `getValue()`,
+`getSelectedOptions()`.
+
+```tsx
+<Select label="Country" options={countries} value={country} onChange={setCountry} />
+<MultiSelect label="Tags" options={tagOptions} value={tags} onChange={setTags} max={5} />
+```
+
+Server mode: set `mode="server"`, feed the current results as `options`, and
+handle `onSearchChange` (fires once on open, then debounced) and `onLoadMore`.
+There is no async "load option by value" — pass options that already include the
+selected values.
+
+## DatePicker and DateRangePicker
+
+`value`, `defaultValue`, `min` and `max` accept a `Date`, an ISO `yyyy-mm-dd`
+string or a timestamp. `onChange` always gives `Date` objects at local midnight.
+`DateRangePicker.onChange` also receives a `complete` flag, `false` after the
+first of two clicks.
+
+Shared props: `min`, `max`, `isDateDisabled`, `locale`, `weekStartsOn`,
+`format`, `numberOfMonths`, `showWeekNumbers`, `showToday`, `allowInput` (true),
+`fixedWeeks` (true), `label`, `description`, `error`, `placeholder`, `required`,
+`disabled`, `readOnly`.
+
+```tsx
+<DatePicker label="Start date" value={date} onChange={setDate} />
+<DateRangePicker label="Period" value={range} onChange={setRange} />
+```
+
+## FileUploader
+
+`multiple`, `accept`, `maxSize`, `endpoint`, `autoUpload`, `params`,
+`fieldNames`, `onChange`, `onUploadComplete`, plus `label`, `description`,
+`error`. Without an `endpoint` the files post with the surrounding form.
+
+Each chunk is a `multipart/form-data` POST carrying `uploadId`, `fileName`,
+`chunkIndex`, `totalChunks`, `fileSize`, `additionalParams` and `chunk`. Answer
+2xx; the last body becomes `item.response`. 5xx/408/429 and network errors retry
+with backoff; other 4xx fail the file.
+
+```tsx
+<FileUploader label="Attachments" multiple accept=".pdf,image/*"
+  maxSize={20 * 1024 * 1024} endpoint="/api/upload"
+  onUploadComplete={(items) => console.log(items.map((i) => i.response))} />
+```
+
+`useFileUploader()` exposes the same engine for a custom UI.