@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/note.md

@@ -0,0 +1,81 @@
+# Note
+
+**Status:** stable
+
+Callout / admonition box. Its tone follows the shared status-tone vocabulary (neutral/info/success/warning/destructive), pairing a soft tone fill with a matching leading icon. Optional title.
+
+**Keywords:** note, callout, admonition, warning, caveat, hint, context
+
+## Usage
+
+Use Note for helpful supporting information that should sit near the relevant content — including a caveat or warning attached to a form, a dialog, or a section. It is the in-context callout; Banner is the page-level strip.
+
+### Best practices
+
+- Do: Use it for tips, caveats, or secondary context that improves understanding.
+- Do: Reach for Note rather than Banner when the message qualifies something on the page — a warning inside a dialog, a caveat above a submit button. Banner is a full-width announcement strip for page- or app-level state; inside a form it reads as a slab, and its soft fill carries no border or tone-colored icon, so the severity stops being visible.
+- Do: Keep tone calm and concise so the note does not compete with primary content.
+- Do: When the reader can resolve the state, pass `action` rather than putting a Button in children. The prop is data — label plus handler — so the callout owns the placement and weight; a Button dropped into children inherits neither, floats in the box's padding, and (in `secondary`) punches a near-background hole in the tone fill.
+- Don't: Do not use Note for state the whole page or app is in (an outage, an offline session, a blocked account) — that is Banner — or for a message tied to one field, which is the field's own error text.
+- Don't: Do not give a Note two actions. One remedy reads as the sentence's next move; two make it a decision point, which is a Dialog's job.
+- Don't: Do not stack several in a row. Three notes together are a wall of asides; if everything is called out, nothing is.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| action | { label: string; onClick?: () => void; href?: string } | — | A single remedy, rendered below the body and aligned to the text column. Deliberately data, not a slot: Note owns the placement, weight, ink and motion, so the action cannot be styled into a button that outweighs the sentence explaining it. Use onClick for an in-place action (renders a button, no glyph) or href for a link (renders an anchor with a trailing chevron) — the chevron means navigate, so it appears only when the action genuinely goes somewhere. |
+| tone | "neutral" \| "info" \| "success" \| "warning" \| "destructive" | "info" | Severity tone — drives the border, fill, and leading icon color/name. The shared status-tone vocabulary (STATUS_TONES). |
+| title | string | — | Optional bold lead-in rendered above the body (text-title-sm). |
+| icon | string \| ReactNode \| null | — | Override the variant glyph: a string swaps the icon name (keeping the tone color), a ReactNode replaces it, null removes it; omit for the variant default. |
+
+## Variants
+
+- **tone**: neutral, info, success, warning, destructive
+
+## Tokens used
+
+`foreground`, `border`, `muted`, `muted-foreground`, `tone-info`, `tone-warning`, `success`, `destructive`
+
+## Accessibility
+
+- Rendered with role="note" so assistive tech can announce it as an aside.
+- Color is never the sole signal — the leading icon and optional title reinforce severity.
+
+## Related
+
+- Components: Banner, InlineStatus, EmptyState
+
+## Examples
+
+### Info
+
+```tsx
+import { Note } from "@sableui/react"
+
+<Note tone="info">Editions mint on Solana mainnet.</Note>
+```
+
+### With title
+
+```tsx
+import { Note } from "@sableui/react"
+
+<Note tone="warning" title="Low balance">Top up SOL before minting.</Note>
+```
+
+### Warning with a remedy, inside a dialog
+
+```tsx
+import { Note } from "@sableui/react"
+
+<Note tone="warning" action={{ label: "Unload chat model", onClick: unloadChatModel }}>gemma-4 is holding VRAM — generating now may be slow or fail.</Note>
+```
+
+### Custom icon
+
+```tsx
+import { Note } from "@sableui/react"
+
+<Note tone="neutral" icon="lock">Pricing and supply cannot be changed after an edition is purchased.</Note>
+```

package/llms/components/notification-badge.md

@@ -0,0 +1,67 @@
+# NotificationBadge
+
+**Status:** stable
+
+An unread indicator. Renders a bare dot or a count pill (capped as "{max}+"), or nothing when there's nothing to show. overlay pins it to the corner of a relative host; it is aria-hidden, so the host's name carries the count.
+
+**Keywords:** notification, badge, count, unread
+
+## Usage
+
+Use NotificationBadge to show a compact unread count, alert count, or attention marker.
+
+### Best practices
+
+- Do: Place it on or near the item that owns the notifications.
+- Do: Use compact counts and cap large numbers when exact precision is not useful.
+- Don't: Do not use NotificationBadge as a standalone status label or category marker.
+- Don't: Do not show a bare dot when the count is meaningful. A dot says "something"; if the user can act on "how many", show the number.
+- Don't: Do not put a neutral badge on a secondary host. Both are the secondary surface, so the badge disappears; use primary or destructive there.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| dot | boolean | false | Render a bare dot indicator with no number. Takes precedence over count. |
+| count | number | — | Unread count. Renders nothing when <= 0 and dot is unset. |
+| max | number | 99 | Cap before showing "{max}+". |
+| tone | "destructive" \| "primary" \| "neutral" | "destructive" | Fill color. destructive for alarming counts; primary/neutral for non-alarming ones. |
+| size | "sm" \| "md" \| "lg" | "md" | Scales the dot/pill on the spacing scale (count pill: sm 16px, md 18px, lg 20px at the default density). |
+| overlay | boolean | false | Pin to the top-end corner of the nearest relative host (an icon button) — one placement for every caller instead of hand-tuned absolute offsets. |
+
+## Variants
+
+- **tone**: destructive, primary, neutral
+- **size**: sm, md, lg
+- **overlay**: true, false
+
+## Tokens used
+
+`destructive`, `destructive-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`
+
+## Accessibility
+
+- The badge is aria-hidden: a count rendered on a control is not associated with it, so the host needs an accessible name that includes the count — "Notifications, 3 unread" — or a screen-reader user hears "Notifications, button" and never learns there is anything new. Pass aria-hidden={false} only for a standalone badge whose number is the information.
+- A dot carries no number and no words: on its own it tells a sighted user only that something changed, and tells everyone else nothing. Pair it with a label that says what is new, and never make its colour the only difference between two states.
+
+## Related
+
+- Components: Badge, StatusDot
+
+## Examples
+
+### Dot + counts
+
+```tsx
+import { NotificationBadge, Row } from "@sableui/react"
+
+<Row gap={3}><NotificationBadge dot /><NotificationBadge count={3} /><NotificationBadge count={128} /></Row>
+```
+
+### Overlay on an icon button
+
+```tsx
+import { Button, Icon, NotificationBadge } from "@sableui/react"
+
+<Button variant="secondary" size="icon" aria-label="Notifications, 5 unread" className="relative"><Icon name="bell" /><NotificationBadge count={5} overlay /></Button>
+```

package/llms/components/number-field.md

@@ -0,0 +1,70 @@
+# NumberField
+
+**Status:** stable
+
+Numeric input with decrement/increment steppers over Base UI NumberField — keyboard arrows, scroll, scrub-to-change, min/max clamping, locale formatting, and form integration. Styled like Input; drops straight into a Field.
+
+**Keywords:** number field, numeric input, stepper, form
+
+## Usage
+
+Use NumberField for numeric values that benefit from validation, min/max bounds, or step controls.
+
+### Best practices
+
+- Do: Use it for quantities, thresholds, percentages, and other real numeric values.
+- Do: Set sensible min, max, and step behavior when the domain has bounds.
+- Don't: Do not use NumberField for identifiers such as phone numbers, ZIP codes, or credit card numbers.
+- Don't: Do not use it in a property grid with steppers left on. Its two 32px stepper buttons (36px each with their inset) put a ~110px floor on a control that needs ~44px there — pass steppers={false}, or use ScrubField.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| min | number | — | Lower bound. Clamps typing, arrows, scroll and scrub alike, so the value cannot leave the range by any route. |
+| max | number | — | Upper bound, clamped on every input route the same way as `min`. |
+| value / defaultValue | number | — | Controlled / uncontrolled numeric value. |
+| onValueChange | (value: number \| null, event) => void | — | Fired when the value changes (null when cleared). |
+| step / smallStep / largeStep | number | — | Increment amount; smallStep applies with the meta key, largeStep with shift. |
+| format | Intl.NumberFormatOptions | — | Locale formatting (currency, percent, units, …). |
+| steppers | boolean | true | Show the decrement / increment buttons. Turn off in a dense property grid — the two 32px stepper buttons (36px with their inset) put a ~110px floor on the control; without them the value left-aligns. |
+| disabled / readOnly / required / name / id | — | — | Standard form-control props. Base UI applies id + required to the input, so it labels and validates correctly. |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`
+
+## Accessibility
+
+- Decrement / Increment are labelled buttons (Decrease / Increase); the input is a spinbutton with aria-valuenow/min/max from Base UI.
+- Routes aria-describedby / aria-invalid onto the input, so a Field's helper + error are announced for it.
+
+## Related
+
+- Components: Input, Slider
+
+## Examples
+
+### Bounded
+
+```tsx
+import { NumberField } from "@sableui/react"
+
+<NumberField defaultValue={1} min={0} max={99} />
+```
+
+### In a field
+
+```tsx
+import { Field, NumberField } from "@sableui/react"
+
+<Field label="Quantity"><NumberField min={1} defaultValue={1} /></Field>
+```
+
+### Currency
+
+```tsx
+import { NumberField } from "@sableui/react"
+
+<NumberField defaultValue={9.99} format={{ style: "currency", currency: "USD" }} />
+```

package/llms/components/otp-field.md

@@ -0,0 +1,101 @@
+# OtpField
+
+**Status:** stable
+
+One-time-code entry over Base UI's OTP Field — one slot per character, SMS autofill on the first slot, paste fills every slot, and only one tab stop for the whole code.
+
+**Keywords:** otp, one-time code, one-time password, verification code, 2fa, two-factor, mfa, pin, passcode, input otp
+
+## Usage
+
+Use OtpField for a short, fixed-length code the user copies from somewhere else — an SMS or email verification code, an authenticator app, a device pairing PIN. The slots show how long the code is and where the user is in it, which a plain Input cannot.
+
+### Best practices
+
+- Do: Set `length` to the exact length the server sends, and verify in `onValueComplete` (or with `autoSubmit` inside a form). Most users paste or autofill the whole code at once, so the moment of completion is the natural submit.
+- Do: Label it through a `Field` ("Verification code") and say where the code was sent in the description. The first slot takes the field's name; the rest are announced by position.
+- Do: Use `groupSize` for codes of 6 or more so the user can check the code in chunks against the message they are reading from.
+- Don't: Do not use OtpField for a password, an arbitrary-length PIN, or anything the user types from memory. Slots promise a fixed length; use Input with `type="password"` and `autocomplete="current-password"` instead.
+- Don't: Do not intercept paste or clear the field on a wrong code before the user has seen the error. Blocking paste breaks SMS autofill and password managers, and wiping the slots erases the evidence of which digit was wrong.
+- Don't: Do not swap it for NumberField because the code is digits. A code is an identifier, not a quantity: NumberField strips leading zeros and offers steppers that make no sense here.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Root | yes | A role=group that holds the value, carries the field label and description, and reports completion. |
+| Slot | yes | One input per character. The first carries autocomplete="one-time-code" and accepts the whole code. |
+| Group gap | no | A decorative dash inserted every `groupSize` slots; hidden from assistive tech. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| length | number | 6 | Number of character slots. Completion fires when every slot is filled. |
+| groupSize | number | — | Insert a visual gap every N slots (3 renders 123 – 456). The value stays one contiguous string. |
+| value / defaultValue | string | — | Controlled / uncontrolled code. |
+| onValueChange | (value: string, details) => void | — | Fires on every edit. `details.reason` is input-change, input-clear, input-paste or keyboard. |
+| onValueComplete | (value: string, details) => void | — | Fires once every slot is filled — the place to verify the code. Also fires when a complete code is pasted over a complete value. |
+| onValueInvalid | (attempted: string, details) => void | — | Fires when typed or pasted text contains characters `validationType` rejects, so you can explain the rejection rather than letting it vanish. |
+| validationType | "numeric" \| "alpha" \| "alphanumeric" \| "none" | "numeric" | Which characters a slot accepts. Also picks the virtual keyboard (numeric → number pad). |
+| autoSubmit | boolean | false | Submit the owning form when the code becomes complete. |
+| mask | boolean | false | Render slots as password inputs. Only for codes that are secret on screen, such as a card PIN. |
+| getSlotLabel | (index: number, length: number) => string | Character N of L | Accessible name for slots after the first. Override to localize. |
+| aria-invalid | boolean | — | Marks every slot invalid (destructive border). `<Field error>` sets it for you. |
+| disabled / readOnly / required / name / id / form | — | — | Standard form-control props. `id` lands on the first slot, so `<Field>` and `<label htmlFor>` name the field. |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `border-strong`, `primary`, `ring`, `destructive`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — A code field is part of the form it sits in and appears with it. Animating it in would delay the one thing the user arrived to do — paste the code they just copied.
+- **response** · Slot · `motion-interactive` — Focus moves between slots on every keystroke. The eased ring and border are what let the eye follow the cursor across six identical boxes instead of hunting for it after each digit.
+- **transition** · Slot · `motion-interactive` — A filled slot strengthens its border, so a pasted code visibly lands in every slot at once. Easing it reads as the code arriving rather than the field flickering.
+- **activity** · Root · _no motion_ — Verifying the code is the form's work, not the field's. Show it on the submit Button's `loading` state, where the user expects the answer to appear.
+
+## Accessibility
+
+- The root is a role=group named by the field label; the first slot shares the label through `id`/`htmlFor`, and later slots are announced by position ("Character 2 of 6").
+- Only one slot is in the tab order. Arrow keys, Home/End and Backspace move between slots; Tab leaves the whole field.
+- The first slot carries autocomplete="one-time-code" and the numeric virtual keyboard, so iOS and Android offer the SMS code above the keyboard.
+- Slots render at 20px (`text-mono-lg`), above the 16px floor that stops iOS Safari zooming on focus.
+
+## Related
+
+- Components: Input, Form, NumberField
+
+## Examples
+
+### Six digits
+
+```tsx
+import { Field, OtpField } from "@sableui/react"
+
+<Field label="Verification code"><OtpField length={6} onValueComplete={verify} /></Field>
+```
+
+### In a field, grouped
+
+```tsx
+import { Field, OtpField } from "@sableui/react"
+
+<Field label="Verification code" description="Enter the 6-digit code we sent to your phone."><OtpField length={6} groupSize={3} /></Field>
+```
+
+### With an error
+
+```tsx
+import { Field, OtpField } from "@sableui/react"
+
+<Field label="Verification code" error="That code has expired. Request a new code and try again."><OtpField length={6} groupSize={3} defaultValue="482913" /></Field>
+```
+
+### Alphanumeric
+
+```tsx
+import { Field, OtpField } from "@sableui/react"
+
+<Field label="Pairing code"><OtpField length={8} groupSize={4} validationType="alphanumeric" /></Field>
+```

package/llms/components/page-header.md

@@ -0,0 +1,76 @@
+# PageHeader
+
+**Status:** stable
+
+In-flow page heading block: a title row (optional back control + actions) over an optional description, with room for children (filters, tabs) below.
+
+**Keywords:** page header, title, lede, page actions
+
+## Usage
+
+Use PageHeader to establish a page's title, supporting description, and primary page actions.
+
+### Best practices
+
+- Do: Use one PageHeader per major page or route.
+- Do: Keep the title literal and put explanation in the lede or nearby content.
+- Don't: Do not use PageHeader inside repeated cards, dialogs, or compact panels.
+- Don't: Do not put it outside the Region that holds the page content. It then sits at a different measure from what it introduces, and the page reads as two documents.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| title | ReactNode | — | The page title (renders an <h1>). |
+| description | ReactNode | — | Supporting copy beneath the title. |
+| back | ReactNode | — | Leading element before the title — typically a back control on drill-in routes. Keep it a ghost icon Button (size="icon", variant="ghost", aria-label="Back") so it stays quieter than the title. |
+| actions | ReactNode | — | Trailing actions aligned to the title row's end. They drop under the title when the row runs out of room, and the title wraps rather than truncating. |
+| titleAs | "h1" \| "h2" | "h1" | The title's heading element. Keep h1 — the route's one h1. Use h2 only when something above already owns the h1: a shell that renders the route title, or a page showing a PageHeader as an example. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`
+
+## Accessibility
+
+- Renders the title as an <h1>; use one PageHeader per page.
+- Its title renders the route's `h1`. Do not render another `h1` elsewhere on the page: heading navigation would report two documents, and the outline a screen-reader user builds from it stops matching the page.
+
+## Related
+
+- Components: AppHeader, Breadcrumbs, Button
+
+## Examples
+
+### With actions
+
+```tsx
+import { Button, PageHeader } from "@sableui/react"
+
+<PageHeader title="Storage credits" description="Fund permanent storage." actions={<Button>Top up</Button>} />
+```
+
+### One per page, inside the region
+
+```tsx
+import { Button, PageHeader, Region } from "@sableui/react"
+
+// PageHeader introduces the current route: title, optional description, and the
+// actions that act on THIS page.
+
+<Region max="content">
+  <PageHeader
+    title="Invoices"
+    description="Every charge on this account."
+    actions={<Button>Export</Button>}
+  />
+  <p className="text-body-md text-muted-foreground">Page content.</p>
+</Region>
+
+// ✗ Outside the Region. The header then sits at a different measure from the
+//   content it introduces, and the page reads as two documents.
+// ✗ Two on one page. A second one is a section heading — an h2 in a
+//   smaller step (text-heading-3 or below), not another PageHeader.
+// ✗ Global actions in it (account, search). Those persist across routes and
+//   belong in AppHeader.
+```

package/llms/components/page-loader.md

@@ -0,0 +1,67 @@
+# PageLoader
+
+**Status:** stable
+
+Full-screen branded loading splash: the screen fades in, the mark breathes, and an indeterminate Progress bar pulses beneath it. All motion is token-driven, so it freezes to a calm static screen when motion is off/reduced.
+
+**Keywords:** page loader, loading, route, pending
+
+## Usage
+
+Use PageLoader for full-route or full-page pending states where the entire view is not ready yet.
+
+### Best practices
+
+- Do: Use it during route transitions, auth checks, or initial data loading.
+- Do: Prefer a clear page-level message when the wait may take noticeable time.
+- Don't: Do not use PageLoader for small inline waits; use Spinner, an indeterminate Progress, or Skeleton.
+- Don't: Do not leave it mounted if the route's data can fail. It covers the whole viewport, so a PageLoader that never resolves is indistinguishable from a hung application — always give it a failure path.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| children | ReactNode | — | Brand mark / logo shown at center. Falls back to a neutral pulsing mark. |
+| label | string | "Loading" | Caption beneath the mark; also the accessible label on the role=status region. |
+| fullscreen | boolean | true | Cover the viewport (fixed) vs fill the nearest positioned parent (absolute). |
+| hideBar | boolean | false | Hide the indeterminate Progress bar under the mark. |
+
+## Tokens used
+
+`background`, `foreground`, `secondary`, `primary`, `muted-foreground`
+
+## Accessibility
+
+- role=status with an aria-label (the label prop) announces the loading state politely.
+- Decorative mark and bar are aria-hidden.
+- Motion respects the policy: under off/reduced the pulses hold their first frame (static).
+
+## Related
+
+- Components: Spinner, Skeleton, Progress
+
+## Examples
+
+### Default
+
+```tsx
+import { PageLoader } from "@sableui/react"
+
+<PageLoader label="Loading Studio" />
+```
+
+### With a logo
+
+```tsx
+import { PageLoader } from "@sableui/react"
+
+<PageLoader label="Loading"><img src="/logo.svg" alt="" className="h-10 w-auto" /></PageLoader>
+```
+
+### Contained (fills parent)
+
+```tsx
+import { PageLoader } from "@sableui/react"
+
+<div className="relative h-80"><PageLoader fullscreen={false} hideBar /></div>
+```

package/llms/components/pagination.md

@@ -0,0 +1,92 @@
+# Pagination
+
+**Status:** stable
+
+Page navigation built from our own Button + Icon (no Base UI). A <nav aria-label='Pagination'> with prev/next icon buttons that disable at the bounds and numbered page buttons; the current page is a secondary button marked aria-current. Collapses to first/last/current plus a sibling window, bridging skipped runs with an ellipsis.
+
+**Keywords:** pagination, pager, pages, table, results, navigation, next, previous
+
+## Usage
+
+Use Pagination when a result set is split into discrete pages and the user needs predictable movement through them. Pair it with DataTable, list results, or server-paged views; use a load-more Button or infinite scroll when page numbers are not meaningful.
+
+### Best practices
+
+- Do: Keep page state controlled by the parent route or data layer so URL, filters, and result fetches stay in sync.
+- Do: Use a specific label when multiple pagers appear on a page, such as "Collector pages".
+- Do: Reset to page 1 when filters or search terms materially change the result set.
+- Don't: Use Pagination for tiny lists where all items fit comfortably on one page.
+- Don't: Hide disabled previous/next buttons at the bounds; disabled controls make the current position clearer.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Nav | yes | The labelled pagination landmark. |
+| Previous/next | yes | Icon buttons for adjacent page movement, disabled at the bounds. |
+| Page buttons | yes | Numbered buttons with aria-current on the active page. |
+| Ellipsis | no | Non-interactive marker for skipped page ranges. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| page | number | — | The active page (1-based). Clamped into the valid range. |
+| total | number | — | Total number of pages. |
+| onPageChange | (page: number) => void | — | Called with the next page when a control is activated. No-op for out-of-range or unchanged values. |
+| siblingCount | number | 1 | Page buttons shown on each side of the current page before the list collapses into ellipses. First and last pages are always shown. |
+| label | string | Pagination | Accessible label applied to the surrounding nav element. |
+| className | string | — | Extra classes merged onto the nav. |
+
+## Tokens used
+
+`secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `foreground`, `muted-foreground`, `ring`
+
+## Accessibility
+
+- Renders a landmark <nav> with aria-label so assistive tech can jump to the pager.
+- The current page button carries aria-current='page'.
+- Prev/next buttons are real <button>s with aria-label and become disabled at the bounds.
+- Ellipsis slots are aria-hidden — they convey no navigable target.
+
+## Related
+
+- Components: DataTable, Table, Button
+- Patterns: ListDetailPage, DashboardPage
+
+## Examples
+
+### Controlled
+
+```tsx
+import { Pagination } from "@sableui/react"
+
+const [page, setPage] = useState(1)
+<Pagination page={page} total={10} onPageChange={setPage} />
+```
+
+### Many pages (ellipsis)
+
+```tsx
+import { Pagination } from "@sableui/react"
+
+const [page, setPage] = useState(8)
+<Pagination page={page} total={20} onPageChange={setPage} />
+```
+
+### Table results footer
+
+```tsx
+import { DataTable, Pagination, Stack } from "@sableui/react"
+
+<Stack gap={2}><DataTable data={rows} columns={columns} rowKey={(row) => row.id} /><Pagination label="Collector pages" page={page} total={12} onPageChange={setPage} /></Stack>
+```
+
+### Server query state
+
+```tsx
+import { Pagination } from "@sableui/react"
+
+const [page, setPage] = useState(searchParams.page ?? 1)
+<Pagination page={page} total={pageCount} onPageChange={(next) => { setPage(next); loadPage(next) }} />
+```