@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/toast.md

@@ -0,0 +1,130 @@
+# Toast
+
+**Status:** stable
+
+Imperative notification system over Base UI Toast — auto-dismiss timers, swipe-to-dismiss, focus management, ARIA live-region announcements, and a limit-aware stack. Wrap the app in ToastProvider, then push toasts from anywhere with the global, Sonner-shaped toast() (toast.success/error/info/warning/loading/promise/dismiss) or the useToast() hook inside components.
+
+**Keywords:** toast, notification, snackbar, feedback, success, error, promise, loading, undo
+
+## Usage
+
+Use Toast for transient feedback caused by a user action: saved, failed, copied, queued, uploaded, or undone. Use Banner for persistent page/app state and InlineStatus or Field errors for feedback that must remain attached to content.
+
+### Best practices
+
+- Do: Mount one ToastProvider near the app root before any code calls toast() or useToast().
+- Do: Use toast.promise for async actions so loading, success, and error states stay tied to one notification.
+- Do: Keep toast copy short and outcome-focused. Add an action only when it is immediately useful, such as Undo.
+- Don't: Use Toast for critical blockers or persistent outages. Use Banner or Dialog when the user must notice and act.
+- Don't: Fire multiple toasts for one operation. Update the same toast when a task progresses.
+- Don't: Put the only path to an action in a toast that auto-dismisses. An Undo that expires on a timer is data loss on a schedule, so error toasts and any toast carrying actionProps default to timeout 0 and wait to be read — pass an explicit timeout only when the action is also reachable somewhere else. When a timeout exists at all, 5s is the floor: anything shorter cannot be read and acted on.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Viewport | yes | The positioned live-region stack rendered by ToastProvider. |
+| Surface | yes | The individual ToastRoot containing title, description, action, and close affordance. |
+| Title | yes | Short outcome text, used as the accessible name. |
+| Description | no | Optional detail or context beneath the title. |
+| Action | no | Optional inline action such as Undo or Retry. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ToastRoot | Base UI Toast.Root props + className (requires the `toast` object) | A single toast surface. Animates enter/leave via data-[starting-style]/data-[ending-style]; swipe-to-dismiss is wired by Base UI. |
+| ToastTitle | Base UI Toast.Title props + className | The toast headline (text-title-sm). Auto-associated as the toast's accessible name. |
+| ToastDescription | Base UI Toast.Description props + className | Supporting body copy beneath the title (text-body-sm, muted). Auto-associated as the toast's accessible description. |
+| ToastClose | Base UI Toast.Close props + className | Dismiss button. Base UI handles the close and leave animation; labelled "Dismiss" by default. |
+| ToastAction | Base UI Toast.Action props + className | Inline action button (e.g. Undo). The imperative path renders one on every toast and Base UI sources its label and handler from that toast's `actionProps`, rendering nothing when there are none — so `toast(msg, { actionProps })` is all an action needs. Reach for the component directly only when composing a toast by hand; compose with render={<Button … />}. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ToastProvider | { children, timeout?, limit?, closeIcon?, position?, viewportClassName? } | — | Wraps Base UI Toast.Provider and renders the themed Viewport + toast list. Mount once near the app root, above any caller of useToast(). |
+| position | "top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right" | "top-right" | Screen anchor for the toast stack. |
+| viewportClassName | string | — | Extra classes merged LAST onto the fixed viewport region — for safe-area insets or an offset (e.g. clearing a sidebar). |
+| timeout | number | 5000 | Default auto-dismiss time in ms for toasts. 0 keeps a toast until it is dismissed. Error toasts, loading toasts, and any toast carrying actionProps default to 0 regardless of this value; a per-toast timeout overrides both. |
+| limit | number | 3 | Maximum toasts shown at once; older toasts are pushed out when the limit is exceeded. |
+| closeIcon | ReactNode | <Icon name="xmark" /> | Override the dismiss-button glyph. The default already follows the injected icon set. |
+| useToast / useToastManager | () => { toasts, add, close, update, promise } | — | Manager hook for use inside components. add({ title, description, timeout?, type?, priority?, actionProps? }) returns the new toast id and applies the same persistence default as toast.* — an error, loading, or actionProps toast stays until dismissed unless you pass a timeout. close(id), update(id, opts), and promise(p, opts) round out the API. |
+| toast | (message, options?) => string  &  { success, error, warning, info, message, loading, promise, dismiss, update, add, custom } | — | Imperative singleton callable OUTSIDE React (event handlers, utilities, non-React code) — the Sonner-shaped surface that makes migrating a lib/toast wrapper a near drop-in. Requires a mounted <ToastProvider> (it binds the shared manager). Each call returns the toast id; toast.dismiss(id?) closes one or all; toast.promise(p, { loading, success, error }) and toast.update(id, opts) handle async + in-place updates. |
+| type (toast option) | "success" \| "error" \| "warning" \| "info" \| "loading" | — | Set by the toast.* helpers. Drives a semantic left accent (success→success, error→destructive, warning→tone-warning, info→tone-info); loading shows a spinner. Both loading and error persist until updated or dismissed unless the call supplies a timeout. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `muted-foreground`, `accent`, `accent-foreground`, `secondary`, `secondary-foreground`, `ring`, `success`, `tone-warning`, `tone-info`, `destructive`
+
+## Motion
+
+- **arrival** · ToastRoot · `motion-slide-left` — A toast interrupts without being asked, so where it came from is the reader's first question. Sliding in from the viewport edge answers it and marks the toast as belonging to the edge rather than to whatever it happens to cover.
+- **response** · ToastAction · `motion-interactive` — Toasts are on a timer, so the action has to look actionable at a glance — there is no time to hunt for the hit target.
+- **transition** · ToastRoot · `motion-slide-left` — Leaving the same way it entered keeps the stack legible when several dismiss at once; toasts that fade in place leave the remaining ones jumping to fill gaps with no visible cause.
+- **activity** · ToastRoot · _no motion_ — A toast reports a result that has already happened. Anything still in flight belongs in the surface that started it, where the reader is still looking.
+
+## Accessibility
+
+- Base UI announces toasts through an ARIA live region — `low` priority is polite, `high` is assertive.
+- Auto-dismiss timers pause on hover/focus and while the window is hidden.
+- ToastClose is keyboard-focusable and labelled; Esc dismisses the focused toast.
+- ToastClose draws a 24px box (21px against the desktop root) and carries a 24x24+ POINTER TARGET behind it, per WCAG 2.5.8 — the glyph stays quiet because a dismiss control should not be the loudest thing in a toast. Base UI keeps the button out of the accessibility tree until the toast is focused; the toast itself is the announced element.
+- An action does NOT dismiss its toast — Base UI leaves that to the handler, so an action that opens a confirmation keeps the toast it is confirming. Call `toast.dismiss(id)` yourself when the action should close it.
+- Animate enter/leave via data-[starting-style]/data-[ending-style] rather than mount/unmount flips.
+
+## Related
+
+- Components: Banner, InlineStatus, Button, Progress
+- Patterns: DashboardPage, SettingsPage
+
+## Examples
+
+### Imperative (from anywhere)
+
+```tsx
+import { toast } from "@sableui/react"
+
+toast.success("Saved", { description: "Your post is live." })
+```
+
+### Promise (loading → success / error)
+
+```tsx
+import { toast } from "@sableui/react"
+
+toast.promise(publish(), { loading: "Publishing…", success: "Published", error: "Failed to publish" })
+```
+
+### Persistent loading, updated in place
+
+```tsx
+import { toast } from "@sableui/react"
+
+const id = toast.loading("Pinning to Arweave…"); /* later */ toast.update(id, { title: "Pinned", type: "success", timeout: 4000 })
+```
+
+### Custom toast markup (composed parts)
+
+```tsx
+import { Icon, toast, ToastClose, ToastDescription, ToastRoot, ToastTitle, ToastViewport, useToast } from "@sableui/react"
+
+const { toasts } = useToast()
+<ToastViewport>{toasts.map((t) => (<ToastRoot key={t.id} toast={t}><div className="flex min-w-0 flex-col gap-1"><ToastTitle>{t.title}</ToastTitle><ToastDescription>{t.description}</ToastDescription></div><ToastClose><Icon name="xmark" /></ToastClose></ToastRoot>))}</ToastViewport>
+```
+
+### Undo action
+
+```tsx
+import { toast } from "@sableui/react"
+
+toast.message("Post archived", { actionProps: { children: "Undo", onClick: () => restorePost() } })
+```
+
+### Provider with app chrome
+
+```tsx
+import { AppShell, Button, Region, toast, ToastProvider } from "@sableui/react"
+
+<ToastProvider position="bottom-right" limit={3}><AppShell><Region max="feed"><Button onClick={() => toast.success("Saved")}>Save</Button></Region></AppShell></ToastProvider>
+```

package/llms/components/toggle.md

@@ -0,0 +1,95 @@
+# Toggle
+
+**Status:** stable
+
+Pressed-state button over Base UI Toggle, plus ToggleGroup for shared single- or multi-select rows. Pressed styling reads from data-[pressed].
+
+**Keywords:** toggle, pressed, button state, toolbar, segmented control, segmented, toggle group, button group, view switcher
+
+## Usage
+
+Use Toggle for button-like controls that can be pressed on or off within a toolbar or compact control set.
+
+### Best practices
+
+- Do: Use it for transient UI modes such as bold, preview, pin, or favorite.
+- Do: Make the pressed state visually and programmatically clear.
+- Do: Use ToggleGroup appearance="segmented" for a single-select view switch (List / Grid). It is the same capsule ThemeSwitcher wears — do not hand-build a track around a row of toggles.
+- Don't: Do not use Toggle for persistent application settings; use Switch.
+- Don't: Do not leave an icon-only Toggle without an accessible name. It announces as "button, pressed", which tells a screen-reader user the state but never what the state applies to.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Toggle | yes | A single pressed or unpressed control. |
+| ToggleGroup | no | A coordinated group of toggle choices. |
+| ToggleGroupItem | no | One toggle inside a group — an alias of Toggle, so <Toggle value="…"> inside a ToggleGroup is the same thing. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ToggleGroup | Base UI ToggleGroup props (value, defaultValue, onValueChange, multiple, disabled, orientation, loopFocus) + appearance?: "default" \| "segmented" + className | Groups child Toggles and shares pressed state across them — each Toggle inside carries a value. Defaults to multiple: false (single-select) — the fit for view-mode switches and segmented controls; pass multiple to allow several pressed at once, e.g. a row of formatting toggles. |
+| ToggleGroupItem | Alias of Toggle | Re-export of Toggle for group composition — a Toggle carrying a value is the group item. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| appearance | "default" \| "segmented" | "default" | On ToggleGroup: `default` is a loose row of toggles; `segmented` draws the capsule segmented control (one track, the pressed option filled) shared with ThemeSwitcher. Toggles inside inherit it. |
+| multiple | boolean | false | On ToggleGroup: allow several toggles pressed at once. The default is single-select, which behaves like a radio group. |
+| Toggle | Base UI Toggle props (pressed, defaultPressed, onPressedChange, disabled, value) + className | defaultPressed: false | A two-state button. Uncontrolled via defaultPressed; controlled via pressed + onPressedChange. Pass value to identify it inside a ToggleGroup. |
+
+## Variants
+
+- **appearance**: default, segmented
+
+## Tokens used
+
+`muted-foreground`, `foreground`, `accent`, `accent-foreground`, `card`, `border`, `ring`
+
+## Accessibility
+
+- Base UI sets aria-pressed on each Toggle and manages the pressed/disabled states.
+- ToggleGroup provides arrow-key roving focus across its items; loopFocus wraps at the ends.
+- Pressed styling reads from the data-[pressed] attribute; disabled items are dimmed and non-interactive.
+- Always supply an aria-label (or visible text) when a Toggle holds only an icon.
+
+## Related
+
+- Components: Switch, Button, Tabs
+
+## Examples
+
+### Standalone
+
+```tsx
+import { Toggle } from "@sableui/react"
+
+<Toggle aria-label="Mute">Mute</Toggle>
+```
+
+### Single-select group
+
+```tsx
+import { Icon, Toggle, ToggleGroup } from "@sableui/react"
+
+<ToggleGroup defaultValue={["list"]}><Toggle value="list" aria-label="List view"><Icon name="list" /></Toggle><Toggle value="grid" aria-label="Grid view"><Icon name="grid" /></Toggle></ToggleGroup>
+```
+
+### Segmented view switch
+
+```tsx
+import { Icon, Toggle, ToggleGroup } from "@sableui/react"
+
+<ToggleGroup appearance="segmented" defaultValue={["list"]} aria-label="View"><Toggle value="list" aria-label="List view"><Icon name="list" /></Toggle><Toggle value="grid" aria-label="Grid view"><Icon name="grid" /></Toggle></ToggleGroup>
+```
+
+### Multi-select group
+
+```tsx
+import { Toggle, ToggleGroup } from "@sableui/react"
+
+<ToggleGroup multiple defaultValue={["bold"]}><Toggle value="bold">Bold</Toggle><Toggle value="italic">Italic</Toggle></ToggleGroup>
+```

package/llms/components/toolbar.md

@@ -0,0 +1,168 @@
+# Toolbar
+
+**Status:** stable
+
+A row or column of controls that is one tab stop, with arrow-key movement between its items (role="toolbar"), over Base UI Toolbar. Items reuse Button's ghost variants and Input, so they follow density like every other control.
+
+**Keywords:** toolbar, action bar, button row, icon buttons, formatting bar, roving focus, arrow keys, tool chrome, editor toolbar
+
+## Usage
+
+Use Toolbar when three or more related controls sit together and act on the same thing — a text selection, a canvas, a document, a table. Tab lands on the toolbar once and the arrow keys move along it, so a keyboard user crosses an editor's twelve buttons in one keystroke instead of twelve. It works in both registers: ghost sm buttons on a page, compact icon-xs buttons inside a Workspace.
+
+### Best practices
+
+- Do: Give every Toolbar an aria-label that names what it acts on ("Text formatting", "Canvas"). With more than one toolbar on screen, that label is the only way a screen-reader user tells them apart.
+- Do: Use size="icon-sm" (page) or size="icon-xs" (workspace) with an aria-label for icon-only ToolbarButtons, and keep one size across the row so the controls line up.
+- Do: Split a long row into ToolbarGroups with a ToolbarSeparator between them — undo/redo, text style, insert. Groups give the eye the same structure the arrow keys already cross.
+- Do: Compose triggers and toggles through ToolbarButton's render prop — render={<MenuTrigger />}, render={<PopoverTrigger />}, or render={<Toggle value="bold" />} inside a ToggleGroup — so they join the toolbar's arrow-key order.
+- Don't: Put a bare Button, Toggle or Input inside a Toolbar. It renders, but it is not a toolbar item: the arrow keys skip it and it takes its own tab stop, which is the inconsistency Toolbar exists to remove. Use ToolbarButton, ToolbarInput, or render through ToolbarButton.
+- Don't: Wrap one or two buttons, or a dialog's Cancel/Confirm pair, in a Toolbar. Those are independent actions; arrow-key movement there is a surprise, not a shortcut. A plain row of Buttons is right.
+- Don't: Use Toolbar for navigation between pages or views. Links that go somewhere are Tabs, SideNav or Breadcrumbs; ToolbarLink is for the odd link that sits among actions, like Help.
+- Don't: Give toolbar buttons primary or destructive fills by default. A toolbar is a quiet strip of tools; the ghost default keeps it from competing with the page's one primary action.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Toolbar | yes | The root (role="toolbar"). Owns orientation, loopFocus and disabled for everything inside it. |
+| ToolbarButton | yes | An action. Button's ghost variants by default; `render` composes a menu trigger, popover trigger or Toggle into the toolbar. |
+| ToolbarGroup | no | A run of related items. `disabled` disables the whole run. |
+| ToolbarSeparator | no | A hairline between groups, oriented across the toolbar. Never a focus stop. |
+| ToolbarInput | no | A compact Input that joins the arrow-key order — a search or find field in the bar. |
+| ToolbarLink | no | An <a> styled like a ToolbarButton, for a link that sits among the actions. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ToolbarButton | { variant?: buttonVariants variant (default "ghost"); size?: buttonVariants size (default "sm"); disabled?: boolean; focusableWhenDisabled?: boolean (default true); render?: ReactElement } + Base UI Toolbar.Button props | A toolbar action, styled exactly like <Button>. Disabled buttons stay focusable by default and carry aria-disabled. Pass size="icon-sm"/"icon-xs" plus aria-label for icon-only. |
+| ToolbarLink | { href?: string; variant?: buttonVariants variant (default "ghost"); size?: buttonVariants size (default "sm"); render?: ReactElement } + Base UI Toolbar.Link props | An <a> in the toolbar's arrow-key order, styled like a ToolbarButton. |
+| ToolbarInput | { disabled?: boolean; focusableWhenDisabled?: boolean (default true) } + Base UI Toolbar.Input / native input props | Sable's Input at the sm control height (w-40 by default; override with className). Arrow keys leave the field so it does not trap the row. |
+| ToolbarGroup | { disabled?: boolean } + Base UI Toolbar.Group props | Groups related items; `disabled` disables all of them. |
+| ToolbarSeparator | Base UI Toolbar.Separator props + className | A hairline-strong rule across the toolbar's axis, exposed as role="separator" and skipped by the arrow keys. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Which arrow keys move focus (Left/Right or Up/Down) and which way the items stack. Separators turn to match. |
+| loopFocus | boolean | true | Arrowing past the last item wraps to the first, and back. |
+| disabled | boolean | false | Disables every item. Items stay focusable (aria-disabled) so the row keeps its shape under the keyboard. |
+| aria-label | string | — | Names the toolbar for assistive technology. Always set it. |
+| className | string | — | Layout overrides — e.g. `flex-1` to let the toolbar fill a bar. |
+
+## Variants
+
+- **orientation**: horizontal, vertical
+- **variant**: ghost, secondary, outline, primary, destructive, link
+- **size**: xs, sm, md, icon, icon-sm, icon-xs
+
+## Tokens used
+
+`foreground`, `accent`, `accent-foreground`, `ring`, `hairline-strong`, `input`, `card`
+
+## Motion
+
+- **arrival** · Toolbar · _no motion_ — A toolbar is fixed chrome. It is present when its surface is; animating it in would leave the tools briefly unusable for no reason the user can see.
+- **response** · ToolbarButton · `motion-interactive` — Inherited from buttonVariants: hover fill, focus ring and disabled dim ease together, so the item under the arrow keys reads as the one that moved.
+- **response** · ToolbarButton · `motion-press` — Inherited from buttonVariants. Many toolbar actions change something off to the side (the canvas, the selection), so the settle on press is the confirmation that lands where the pointer is.
+- **transition** · Toolbar · _no motion_ — The toolbar has no state of its own. Pressed state belongs to a Toggle rendered through ToolbarButton, which carries its own transition.
+- **activity** · Toolbar · _no motion_ — A toolbar never works on its own. Pending work belongs to the surface the action targets, or to a Spinner in the button that started it.
+
+## Accessibility
+
+- Base UI renders role="toolbar" with aria-orientation, and a roving tabindex: the toolbar is one tab stop, the arrow keys move between items, Home/End jump to the ends.
+- Disabled items stay focusable by default and announce as disabled (aria-disabled), so arrowing along the row never silently skips a control. Set focusableWhenDisabled={false} on an item to opt out.
+- ToolbarSeparator is role="separator" with the orientation opposite the toolbar's, and is not a focus stop.
+- ToolbarInput lets the arrow keys move the caret and only leaves the field at either end of its text.
+- Always set aria-label on the Toolbar, and on every icon-only ToolbarButton.
+- A Toggle rendered through ToolbarButton keeps aria-pressed; a MenuTrigger keeps aria-haspopup/aria-expanded.
+
+## Related
+
+- Components: Button, Toggle, Menu, Popover, Tooltip, Workspace, PanelSection, Separator
+
+## Examples
+
+### Formatting toolbar
+
+```tsx
+import { Icon, Toggle, ToggleGroup, Toolbar, ToolbarButton, ToolbarGroup, ToolbarLink, ToolbarSeparator } from "@sableui/react"
+
+<Toolbar aria-label="Text formatting">
+  <ToolbarGroup aria-label="History">
+    <ToolbarButton size="icon-sm" aria-label="Undo">
+      <Icon name="arrow-left" />
+    </ToolbarButton>
+    <ToolbarButton size="icon-sm" aria-label="Redo">
+      <Icon name="arrow-right" />
+    </ToolbarButton>
+  </ToolbarGroup>
+  <ToolbarSeparator />
+  <ToggleGroup multiple aria-label="Style">
+    <ToolbarButton size="icon-sm" aria-label="Bold" render={<Toggle value="bold" />}>
+      <Icon name="bold" />
+    </ToolbarButton>
+    <ToolbarButton size="icon-sm" aria-label="Italic" render={<Toggle value="italic" />}>
+      <Icon name="italic" />
+    </ToolbarButton>
+  </ToggleGroup>
+  <ToolbarSeparator />
+  <ToolbarLink href="/help">Help</ToolbarLink>
+</Toolbar>
+```
+
+### With a menu trigger and a search field
+
+```tsx
+import { Menu, MenuContent, MenuItem, MenuTrigger, Toolbar, ToolbarButton, ToolbarInput, ToolbarSeparator } from "@sableui/react"
+
+<Toolbar aria-label="Table">
+  <ToolbarButton>Export</ToolbarButton>
+  <Menu>
+    <ToolbarButton render={<MenuTrigger />}>View</ToolbarButton>
+    <MenuContent>
+      <MenuItem>Compact rows</MenuItem>
+      <MenuItem>Comfortable rows</MenuItem>
+    </MenuContent>
+  </Menu>
+  <ToolbarSeparator />
+  <ToolbarInput aria-label="Search rows" placeholder="Search" />
+</Toolbar>
+```
+
+### Vertical tool rail
+
+```tsx
+import { Icon, Toolbar, ToolbarButton, ToolbarSeparator } from "@sableui/react"
+
+<Toolbar orientation="vertical" aria-label="Tools">
+  <ToolbarButton size="icon-sm" aria-label="Select">
+    <Icon name="arrow-up" />
+  </ToolbarButton>
+  <ToolbarButton size="icon-sm" aria-label="Draw">
+    <Icon name="edit" />
+  </ToolbarButton>
+  <ToolbarSeparator />
+  <ToolbarButton size="icon-sm" aria-label="Delete" disabled>
+    <Icon name="trash" />
+  </ToolbarButton>
+</Toolbar>
+```
+
+### In a workspace bar
+
+```tsx
+import { Icon, Toolbar, ToolbarButton, WorkspaceBar } from "@sableui/react"
+
+<WorkspaceBar>
+  <Toolbar aria-label="Document" className="flex-1">
+    <ToolbarButton size="xs">File</ToolbarButton>
+    <ToolbarButton size="xs">Edit</ToolbarButton>
+    <ToolbarButton size="icon-xs" aria-label="Share" className="ms-auto">
+      <Icon name="share" />
+    </ToolbarButton>
+  </Toolbar>
+</WorkspaceBar>
+```

package/llms/components/tooltip.md

@@ -0,0 +1,93 @@
+# Tooltip
+
+**Status:** stable
+
+Hover/focus label over Base UI Tooltip (collision-aware positioning, ARIA wiring, delay grouping via TooltipProvider). Compact popover surface.
+
+**Keywords:** tooltip, hint, hover, assistive
+
+## Usage
+
+Use Tooltip for brief nonessential hints tied to a specific control or piece of text.
+
+### Best practices
+
+- Do: Use it to name icon-only controls or clarify compact UI when the label cannot be visible.
+- Do: Keep tooltip content short and noninteractive.
+- Don't: Do not put critical instructions, errors, or interactive content inside Tooltip.
+- Don't: Do not let a tooltip serve as an icon button's accessible name. A tooltip is not a name — without its own aria-label the button announces as "button", and the tooltip never opens for a screen reader at all.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| TooltipProvider | no | Optional provider for shared tooltip timing. |
+| TooltipTrigger | yes | The element that owns the hint. |
+| TooltipContent | yes | The short hint content. |
+| TooltipArrow | no | An optional pointer toward the trigger. |
+| SimpleTooltip | no | A convenience wrapper for common tooltip usage. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| TooltipProvider | Base UI Tooltip.Provider props (delay, closeDelay, timeout) | Wraps an app or group of Tooltips to share open/close delays. Once one tooltip is open, adjacent tooltips open instantly. |
+| TooltipTrigger | Base UI Trigger props + render | The anchor element. Use render={<Button/>} to compose with another component. |
+| TooltipContent | Base UI Popup props + side \| align \| sideOffset + className | Portals + positions + paints the popup. side ("top" \| "bottom" \| "left" \| "right" \| "inline-*") picks which side of the trigger to render against, defaults to "top", and auto-flips on collision; align ("start" \| "center" \| "end") defaults to "center"; sideOffset (gap between trigger and popup, in pixels) defaults to 6. |
+| TooltipArrow | Base UI Arrow props + className | Optional pointer connecting the popup to its trigger — a popover-coloured square turned 45° that carries the border on its outward edges. Place inside TooltipContent. |
+| SimpleTooltip | Base UI Tooltip.Root props + content: ReactNode + children: ReactElement + side \| align \| sideOffset | Shorthand wrapping Root + Trigger + Content for the common case. The single child becomes the trigger (via Base UI render); content sets the body; side / align / sideOffset forward to the content with the same defaults. Composition parts remain for advanced use. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| side | "top" \| "right" \| "bottom" \| "left" | "top" | On TooltipContent: which side of the trigger to render against. Flips automatically when there is no room. |
+| Tooltip (Root) | Base UI Tooltip.Root props (open, defaultOpen, onOpenChange, disabled) | — | Groups the trigger and content. Uncontrolled by default. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border-floating`
+
+## Motion
+
+- **arrival** · Content · `motion-pop` — The transform-origin follows the anchor, so the tooltip appears to grow out of the element it describes. That is what binds it to its trigger — a bubble that materialises at full size near two possible triggers belongs to neither.
+- **response** · Content · _no motion_ — The tooltip is not a hover target; pointing at it is how you dismiss it. Styling it for the pointer would suggest otherwise.
+- **transition** · Content · `motion-pop` — Same recipe, exit direction — it collapses back toward the anchor. Content that fades from a fixed size on close reads as a second, unrelated element disappearing.
+- **activity** · Content · _no motion_ — Tooltip copy is resident before the tooltip opens. Anything that has to be fetched is a Popover with its own loading state.
+
+## Accessibility
+
+- Base UI wires aria-describedby from trigger to popup and manages hover + focus open.
+- Opens on keyboard focus, not just hover; dismisses on Esc and blur.
+- Animate via data-[starting-style]/data-[ending-style] opacity attributes.
+- Tooltip text is supplementary — never put essential-only actions inside a tooltip.
+
+## Related
+
+- Components: Popover, ContextCard
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Icon, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@sableui/react"
+
+<TooltipProvider><Tooltip><TooltipTrigger render={<Button variant="ghost" size="icon-sm" aria-label="Info"><Icon name="info" /></Button>} /><TooltipContent>Stored permanently on Arweave.</TooltipContent></Tooltip></TooltipProvider>
+```
+
+### Sides
+
+```tsx
+import { Button, Tooltip, TooltipContent, TooltipTrigger } from "@sableui/react"
+
+<Tooltip><TooltipTrigger render={<Button variant="secondary">Right</Button>} /><TooltipContent side="right">Opens to the right</TooltipContent></Tooltip>
+```
+
+### Shorthand (SimpleTooltip)
+
+```tsx
+import { Button, Icon, SimpleTooltip } from "@sableui/react"
+
+<SimpleTooltip content="Stored permanently on Arweave."><Button variant="ghost" size="icon-sm" aria-label="Info"><Icon name="info" /></Button></SimpleTooltip>
+```