@moldable-ai/ui 0.2.20 → 0.2.22

package/src/components/ui/date-picker.md

@@ -0,0 +1,55 @@
+# DatePicker
+
+`DatePicker` is a portable, date-only calendar popover. Its value is an ISO
+calendar date (`YYYY-MM-DD`), so app storage does not introduce timezone
+conversion.
+
+```tsx
+<DatePicker
+  aria-label="Due date"
+  value={dueDate}
+  onValueChange={setDueDate}
+  min="2026-01-01"
+  clearable
+/>
+```
+
+## DatePicker or DateField
+
+- Use `DatePicker` when a predictable renderer-owned calendar is important.
+- Use `DateField` when compact keyboard entry and the browser's date control
+  are preferable.
+- Use the standalone `Calendar` for ranges, multiple dates, or an always
+  visible month.
+
+## API
+
+- `value`, `defaultValue`: ISO `YYYY-MM-DD` or an empty string.
+- `onValueChange`: receives the next ISO date or an empty string.
+- `min`, `max`: inclusive ISO date limits.
+- `placeholder`: trigger copy when empty.
+- `locale`: the `react-day-picker` locale used by the calendar and display.
+- `formatValue`: custom trigger rendering for the ISO value.
+- `clearable`, `clearLabel`: optional clear action inside the popover.
+- `density`: `compact`, `default`, or `comfortable`.
+- `open`, `defaultOpen`, `onOpenChange`: controlled or uncontrolled popover.
+- Remaining button props apply to the trigger.
+
+## Keyboard and accessibility
+
+Label the trigger through visible form text, `aria-labelledby`, or
+`aria-label`. The trigger opens with Enter or Space. The calendar owns arrow,
+Home, End, Page Up, and Page Down behavior. Selection closes the popover and
+focus returns to the trigger.
+
+## Platform behavior
+
+This component is portable and uses no host API. A future native date or time
+control must be introduced through a shared host capability with this
+renderer-owned control as its fallback.
+
+## Don't
+
+- Do not put timestamps or UTC instants in this date-only value.
+- Do not use this component for time, date-time, or date-range selection.
+- Do not manually convert the selected value through `Date.toISOString()`.

package/src/components/ui/dialog.md

@@ -0,0 +1,59 @@
+# Dialog
+
+Use `Dialog` for focused work that temporarily blocks the current surface. Use
+`AlertDialog` or `ConfirmDialog` for consequential confirmation, `Popover` for
+small anchored controls, and `Sheet` for a secondary region that should retain
+spatial context.
+
+## Anatomy
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Edit details</Button>
+  </DialogTrigger>
+  <DialogContent size="lg">
+    <DialogHeader>
+      <DialogTitle>Edit details</DialogTitle>
+      <DialogDescription>Update the selected record.</DialogDescription>
+    </DialogHeader>
+    <DialogBody>{/* the only scrolling region */}</DialogBody>
+    <DialogFooter>
+      <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+        Save <Kbd>⌘</Kbd>
+        <Kbd>Enter</Kbd>
+      </span>
+      <DialogAction primary loading={isSaving} onClick={saveChanges}>
+        Save changes
+      </DialogAction>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+`DialogContent` supports `sm`, `default`, `lg`, and `full`. It limits itself to
+the host-provided window and chat-safe insets. `DialogBody` owns vertical
+scrolling; do not put overflow on both the content and body.
+
+Keep dialogs opaque and visually stable. Translucent material belongs on small
+temporary control overlays where seeing the underlying context is useful.
+
+Use `DialogAction` for footer commands that need the standard async and keyboard
+contracts. Its `loading` prop forwards to `Button`, preventing duplicate
+activation while retaining the label width and accessible name. Keep the dialog
+controlled, show inline field errors, and close only after success. Disable the
+whole form only when edits during submission would be unsafe. Use
+`ConfirmDialog` when confirmation is the entire workflow.
+
+Set `primary` on at most one `DialogAction` to opt into the default-action
+shortcut. Command+Enter activates it on macOS; Control+Enter does so on other
+platforms. The shortcut works from anywhere in the dialog unless a focused
+control consumes the key event with `preventDefault()`, or the primary action is
+loading or disabled. Plain Enter keeps the focused control's native behavior.
+Use `Kbd` to show the shortcut when it improves discovery; render the
+platform-appropriate modifier in app code.
+
+Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
+scope is not obvious. Escape, outside dismissal, initial focus, and focus return
+come from the Radix primitive; do not replace them with manual document event
+handlers.

package/src/components/ui/empty.md

@@ -20,7 +20,7 @@ import {
   EmptyTitle,
 } from '@moldable-ai/ui'
 
-;<Empty className="pb-[calc(var(--chat-safe-padding,0px)+2rem)]">
+;<Empty variant="pane" safeBottom>
   <EmptyHeader>
     <EmptyMedia variant="icon">
       <Database />
@@ -52,6 +52,9 @@ For a successful zero state, omit the action when there is nothing useful to do:
 ## API summary
 
 - `Empty`: centered flex container for the complete state.
+- `Empty variant`: `compact`, `pane`, or `full`; defaults to `pane`.
+- `Empty safeBottom`: adds host-provided chat clearance. Do not enable it when
+  an owning `AppFrameContent` or parent scroll region already applies clearance.
 - `EmptyHeader`: groups media, title, and description.
 - `EmptyMedia`: `variant="default"` or `variant="icon"`.
 - `EmptyTitle`: primary label.
@@ -65,7 +68,7 @@ For a successful zero state, omit the action when there is nothing useful to do:
 - Show one primary setup action when the state is blocked.
 - Distinguish first-run, filtered-zero, permission, and successful-zero states.
 - Keep the app’s normal shell or pane structure visible.
-- Add chat-safe padding when the empty state occupies a pane that reaches the bottom.
+- Use `safeBottom` when the empty state itself owns a pane that reaches the bottom.
 
 ## Don't
 
@@ -79,4 +82,6 @@ For a successful zero state, omit the action when there is nothing useful to do:
 
 An empty state should feel like part of a local instrument, not a landing page. Keep it visually small even when centered. If the desktop chat can resolve the state, provide specific app context or an explicit “Ask Moldable about this” affordance that prefills desktop chat; do not add another chat box.
 
-For scrollable panes, use enough bottom padding to remain visible above chat, commonly `pb-[calc(var(--chat-safe-padding,0px)+1rem)]` or more when a fixed dock is present.
+For scrollable panes, prefer `safeBottom` on the owning `ScrollArea`. Apply it
+to `Empty` only when the empty state is the owner, so nested states do not add
+the same safe area twice.

package/src/components/ui/error-boundary-view.md

@@ -0,0 +1,98 @@
+# ErrorBoundaryView
+
+`ErrorBoundaryView` presents a compact recovery state without owning error
+catching, reporting, or host policy.
+
+## When to use
+
+Use it as the renderer for a React error boundary, route-level failure, or
+host-provided pane error. Supply `actions` when the host owns reporting,
+navigation, or chat recovery.
+
+## When not to use
+
+Do not use it for inline field validation, routine empty states, or transient
+request failures that can stay beside the initiating control. It does not catch
+errors itself; use `AppErrorBoundary` when the package should own catching and
+Moldable reporting.
+
+## Anatomy
+
+The view contains one compact surface with a title, optional message, optional
+error-details disclosure, and one action row. It does not add illustrations or
+nested cards.
+
+## Usage
+
+```tsx
+import { ErrorBoundaryView } from '@moldable-ai/ui'
+
+function PaneError() {
+  return (
+    <ErrorBoundaryView
+      title="Could not load this pane"
+      message="Retry the request or report the captured error."
+      details={error.stack}
+      onRetry={retry}
+      actions={
+        <Button type="button" variant="secondary" onClick={reportError}>
+          Report error
+        </Button>
+      }
+    />
+  )
+}
+```
+
+## Variants and sizes
+
+The renderer has one responsive layout. It uses the available height in a pane
+and can fill a window when its parent gives it full height. The content remains
+bounded to a readable width.
+
+## API
+
+- `title`: heading content. Defaults to `"Something went wrong"`.
+- `message`: optional supporting copy.
+- `details`: optional string shown in a collapsed disclosure with a bounded,
+  scrollable monospace region.
+- `onRetry`: when supplied, renders a `Retry` button and calls the handler once
+  per activation.
+- `actions`: optional host-provided action content rendered after Retry.
+- `className`: optional classes merged onto the outer renderer.
+
+## States and interaction
+
+Omit `details` when there is no safe diagnostic text to show. Omit both
+`onRetry` and `actions` for a read-only failure. Keep retry state in the caller
+and pass `loading` to a custom action when retrying is asynchronous.
+
+## Keyboard and accessibility
+
+The details use native `details` and `summary` semantics. The title is the
+surface heading, the Retry control keeps native button behavior, and diagnostic
+text remains selectable.
+
+## Platform behavior
+
+The component has no host calls or platform branches. `AppErrorBoundary`
+supplies Moldable-specific reload and chat-prefill actions.
+
+## Do
+
+- Keep the title calm and literal.
+- Give the message a concrete recovery path.
+- Redact secrets before passing diagnostic details.
+- Use semantic theme tokens in custom actions.
+
+## Don't
+
+- Do not add decorative error art or nested cards.
+- Do not put binary data or unbounded logs in `details`.
+- Do not make this presentational component report or reload implicitly.
+
+## Testing
+
+Contract tests should verify copy, disclosure behavior, Retry activation, and
+host action rendering. Error-catching and reporting tests belong to the owning
+boundary.

package/src/components/ui/grid.md

@@ -18,7 +18,7 @@ import {
   GridItemTitle,
 } from '@moldable-ai/ui'
 
-<Grid
+;<Grid
   aria-label="Artifacts"
   columns={3}
   selectionMode="single"
@@ -56,14 +56,18 @@ Prefer changing this value at deliberate window breakpoints. A smaller window sh
 
 ## Interaction contract
 
-- Arrow Left/Right moves one tile.
-- Arrow Up/Down moves by `columns`.
-- Home and End move to the first and last available tile.
+- Arrow Left/Right moves within the current row and stops at its edge.
+- Arrow Up/Down moves within the current column and stops at its edge.
+- Home and End move to the first and last available tile in the current row.
+- Control/Command + Home and End move to the first and last available tile in
+  the entire grid.
 - Space changes selection.
 - Enter changes selection and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled tiles are skipped.
 - Buttons and links inside a tile preserve their own pointer behavior.
+- When the grid first mounts, the first selected, enabled tile receives the
+  roving tab stop. If nothing is selected, the first enabled tile receives it.
 
 ## API summary
 

package/src/components/ui/icon-button.md

@@ -7,10 +7,10 @@
 ## Usage
 
 ```tsx
-import { IconButton } from '@moldable-ai/ui'
 import { RefreshCw } from 'lucide-react'
+import { IconButton } from '@moldable-ai/ui'
 
-<IconButton
+;<IconButton
   label="Refresh events"
   tooltip
   size="sm"

package/src/components/ui/list.md

@@ -17,7 +17,7 @@ import {
   ListItemTitle,
 } from '@moldable-ai/ui'
 
-<List
+;<List
   aria-label="Documents"
   selectionMode="single"
   defaultSelectedValues={['brief']}
@@ -38,6 +38,28 @@ import {
 </List>
 ```
 
+## Sections
+
+Group related options with `ListSection` and give every section an accessible
+name. `ListSectionHeader` automatically labels its containing section:
+
+```tsx
+<List aria-label="Documents" selectionMode="single">
+  <ListSection>
+    <ListSectionHeader>Recent</ListSectionHeader>
+    <ListItem value="brief">Project brief</ListItem>
+    <ListItem value="notes">Research notes</ListItem>
+  </ListSection>
+  <ListSection aria-label="Archived documents">
+    <ListItem value="archive">Archive</ListItem>
+  </ListSection>
+</List>
+```
+
+Use either `ListSectionHeader`, `aria-label`, or an explicit
+`aria-labelledby` value for each section. Keyboard movement follows the
+rendered DOM order across section boundaries.
+
 For controlled selection, pass an iterable to `selectedValues` and replace it when `onSelectionChange` fires:
 
 ```tsx
@@ -63,8 +85,9 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 - Enter changes selection and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled items are skipped during keyboard navigation and cannot be selected or activated.
-- Interactive descendants such as buttons and links keep their own click behavior. They do not select or activate the containing item.
+- Interactive descendants such as buttons and links keep their own pointer behavior. They do not select or activate the containing item.
 - Focus uses a roving `tabIndex`, so the collection contributes one stop to the tab order.
+- When the list first mounts, the first selected, enabled item receives the roving tab stop. If nothing is selected, the first enabled item receives it.
 
 ## API summary
 
@@ -86,9 +109,16 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 `ListItemContent`, `ListItemTitle`, `ListItemDescription`, and `ListItemActions` provide compact row layout without changing semantics.
 
+### `ListSection`
+
+- Groups related items with `role="group"`.
+- Use `ListSectionHeader` for an automatically connected visible label.
+- Alternatively, provide `aria-label` or `aria-labelledby`.
+
 ## Do
 
 - Give every collection a visible label or `aria-label`.
+- Give every section an accessible label.
 - Keep values stable when filtering or reordering.
 - Put the primary row identity in `ListItemTitle` and secondary metadata in `ListItemDescription`.
 - Use selection to represent durable collection state and action to open or execute.
@@ -98,6 +128,9 @@ const [selected, setSelected] = useState<ReadonlySet<string>>(
 
 - Do not put a `List` inside another list item.
 - Do not use array indexes as values when rows can reorder.
+- Do not put buttons, links, or other interactive controls inside selectable
+  listbox items. Put independent actions outside the listbox or use a pattern
+  whose child-interaction model supports them.
 - Do not rely on double click as the only way to perform an important action.
 - Do not add a second manual arrow-key handler to the same collection.
 - Do not visually mark focus and selection as if they were the same state.

package/src/components/ui/material.md

@@ -0,0 +1,51 @@
+# Material
+
+Adaptive material for navigation and control chrome.
+
+```tsx
+<Material asChild variant="regular" elevation="none">
+  <Toolbar>{/* context and actions */}</Toolbar>
+</Material>
+
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+## Variants
+
+- `regular` provides a frosted, legible control or navigation layer.
+- `clear` is less frosted and is only for compact controls floating over
+  photos, maps, video, or another richly colored canvas.
+
+Both variants start with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it. Reduced transparency and forced colors keep the
+fallback opaque.
+
+## Grouping
+
+`MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
+ghost or transparent controls inside it. Do not wrap each child in another
+`Material`; nested sampling creates muddy, inconsistent results.
+
+Use separate `Material` instances only when controls are spatially detached and
+do not read as one group.
+
+## Rules
+
+- Use material for toolbars, compact floating controls, menus, and other
+  temporary control layers.
+- Keep documents, calendars, tables, forms, cards, sheets, and primary content
+  canvases opaque.
+- Prefer `regular`. A `clear` surface needs stable contrast across every part
+  of the media behind it.
+- Use `interactive` only when the material surface itself is the control.
+- Do not animate blur or saturation. Shared motion tokens provide restrained
+  press feedback and remove it when reduced motion is requested.
+- CSS material samples content inside the renderer. Native behind-window
+  material remains owned by the host.

package/src/components/ui/navigation-button-group.md

@@ -0,0 +1,46 @@
+# NavigationButtonGroup
+
+`NavigationButtonGroup` presents paired back and forward actions with one
+consistent compact treatment.
+
+```tsx
+<NavigationButtonGroup
+  canGoBack={historyIndex > 0}
+  canGoForward={historyIndex < history.length - 1}
+  onBack={goBack}
+  onForward={goForward}
+/>
+```
+
+## API
+
+- `canGoBack` and `canGoForward` disable unavailable directions.
+- `onBack` and `onForward` perform caller-owned navigation.
+- `backLabel` and `forwardLabel` customize accessible names.
+- `size` accepts the `IconButton` size scale.
+- `variant` is `ghost` or `outline`.
+- Native `ButtonGroup` props apply to the group.
+
+## Keyboard and accessibility
+
+The root has `role="group"` and the default accessible name “Navigation”.
+Each icon button has a stable accessible name and participates in normal Tab
+order. The component does not install global keyboard shortcuts.
+
+## Platform behavior
+
+This component is portable. It does not own browser history, Moldable
+navigation state, or native window history. Connect it to the navigation owner
+for the current surface.
+
+## Do
+
+- Put it in a leading toolbar group.
+- Disable unavailable directions.
+- Keep back and forward behavior scoped to the visible pane or app.
+
+## Don't
+
+- Do not render a fake forward action when no forward history exists.
+- Do not use it for undo and redo.
+- Do not add a second tooltip around its buttons.

package/src/components/ui/popover.md

@@ -0,0 +1,31 @@
+# Popover
+
+Use `Popover` for a small, interactive surface anchored to a control. Use
+`Tooltip` for terse non-interactive help, `HoverCard` for a preview, and
+`Dialog` for a blocking task.
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">View options</Button>
+  </PopoverTrigger>
+  <PopoverContent size="sm" material="regular">
+    <PopoverHeader>
+      <PopoverTitle>View options</PopoverTitle>
+      <PopoverDescription>Choose what appears in the list.</PopoverDescription>
+    </PopoverHeader>
+    {/* interactive controls */}
+  </PopoverContent>
+</Popover>
+```
+
+Sizes are `content`, `sm`, `default`, and `lg`. Content is capped to the
+collision-aware available width and height and scrolls when necessary.
+`material="regular"` is the standard temporary overlay. Use `clear` only above
+media or a richly colored canvas where the stronger sampled effect has a clear
+layering purpose.
+
+`PopoverClose`, `PopoverPortal`, and `PopoverArrow` are available when the
+composition needs them. Provide an accessible name on an icon-only close
+action. Keep required instructions and critical actions discoverable without
+hover.

package/src/components/ui/scroll-area.md

@@ -11,10 +11,8 @@ For simple content, a native `overflow-y-auto` region is often sufficient. The i
 ```tsx
 import { ScrollArea } from '@moldable-ai/ui'
 
-;<ScrollArea className="h-full min-h-0">
-  <div className="px-3 pb-[calc(var(--chat-safe-padding,0px)+1rem)] pt-3">
-    {/* Long list */}
-  </div>
+;<ScrollArea className="h-full min-h-0" safeBottom>
+  <div className="px-3 pt-3">{/* Long list */}</div>
 </ScrollArea>
 ```
 
@@ -28,12 +26,17 @@ For a grouped list:
 </ScrollArea>
 ```
 
-The current `ScrollArea` composition installs a vertical scrollbar automatically.
+The current `ScrollArea` composition installs a vertical scrollbar by default.
+Set `scrollbars` to `horizontal`, `both`, or `none` for another explicit
+configuration.
 
 ## API summary
 
 - `ScrollArea`: Radix Scroll Area root with a full-size viewport, vertical `ScrollBar`, and corner.
 - Accepts Radix root props, forwarded `ref`, and `className`.
+- `scrollbars`: `vertical`, `horizontal`, `both`, or `none`.
+- `viewportClassName`: styles the actual scrolling viewport.
+- `safeBottom`: adds the shared chat-safe padding to the viewport exactly once.
 - `ScrollBar`: exported scrollbar primitive with `orientation="vertical" | "horizontal"`; defaults to vertical.
 - The root’s direct children are rendered inside the viewport.
 - The viewport supplies focus-visible outline and ring treatment.
@@ -43,7 +46,7 @@ The current `ScrollArea` composition installs a vertical scrollbar automatically
 - Give the scroll area a definite height through its own class and full-height ancestors.
 - Put padding on an inner content wrapper when it should scroll with the content.
 - Add `min-h-0` to flex or grid ancestors.
-- Add bottom chat-safe padding inside every scroll region that reaches the webview bottom.
+- Enable `safeBottom` on every owning scroll region that reaches the webview bottom.
 - Keep sticky headers inside the same scrolling context as their content.
 - Test keyboard, wheel, trackpad, and scrollbar-thumb interaction.
 
@@ -54,7 +57,8 @@ The current `ScrollArea` composition installs a vertical scrollbar automatically
 - Do not put fixed controls inside the moving content when they must remain reachable.
 - Do not hide focus outlines.
 - Do not assume padding on a sibling pane protects this viewport from desktop chat.
-- Do not assume adding `ScrollBar` as a child of `ScrollArea` creates a second root scrollbar; children belong to the viewport in the current composition.
+- Do not add `ScrollBar` as a child of `ScrollArea`; children belong to its
+  viewport. Use the `scrollbars` prop.
 
 ## Moldable considerations
 

package/src/components/ui/search-field.md

@@ -9,7 +9,7 @@
 ```tsx
 import { SearchField } from '@moldable-ai/ui'
 
-<SearchField
+;<SearchField
   aria-label="Search projects"
   value={query}
   onValueChange={setQuery}

package/src/components/ui/segmented-control.md

@@ -9,12 +9,9 @@ Use it for choices such as list/grid, week/month, or preview/edit. Use `Tabs` wh
 ## Usage
 
 ```tsx
-import {
-  SegmentedControl,
-  SegmentedControlItem,
-} from '@moldable-ai/ui'
+import { SegmentedControl, SegmentedControlItem } from '@moldable-ai/ui'
 
-<SegmentedControl
+;<SegmentedControl
   aria-label="Calendar view"
   value={view}
   onValueChange={setView}

package/src/components/ui/sheet.md

@@ -0,0 +1,30 @@
+# Sheet
+
+`Sheet` presents a secondary region from an edge while preserving the current
+workspace. It is appropriate for narrow-window navigation, filters, or an
+inspector that cannot remain beside the canvas.
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button variant="outline">Filters</Button>
+  </SheetTrigger>
+  <SheetContent side="right" size="default">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+      <SheetDescription>Limit the visible results.</SheetDescription>
+    </SheetHeader>
+    <SheetBody>{/* scrolling controls */}</SheetBody>
+    <SheetFooter>{/* persistent actions */}</SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+Side sheets support `sm`, `default`, and `lg`. All sides respect host window
+insets; their bottom edge also clears the embedded chat safe area. `SheetBody`
+is the only flexing scroll owner, leaving its header, close action, and footer
+reachable.
+
+Use `Dialog` when the task is centered and blocking, `Drawer` for touch-first
+presentation, and `Inspector` when contextual properties should remain visible
+beside the canvas. Do not use a sheet as permanent desktop navigation.

package/src/components/ui/table.md

@@ -29,7 +29,9 @@ Use `compact` for inspector-like datasets, `default` for general work, and
 `comfortable` where scanning matters more than density.
 
 When a row is selectable, selection is controlled by the caller and can be
-toggled with pointer, Enter, or Space. Put independent actions inside buttons
-and call `event.stopPropagation()` if activating them must not select the row.
+toggled with pointer, Enter, or Space. Independent buttons, links, form
+controls, and editable descendants keep their own pointer and keyboard
+behavior without toggling the containing row. Call `event.preventDefault()` in
+a row event handler only when an app needs to cancel the built-in row response.
 For rich grid navigation, column sorting, or cell editing, use a dedicated data
 grid rather than layering those interactions onto a basic table.

package/src/components/ui/toggle-button.md

@@ -0,0 +1,48 @@
+# ToggleButton
+
+`ToggleButton` is a single pressed/unpressed action. It is a semantic facade
+over `Toggle`, so both share one Radix interaction model and one style source.
+
+```tsx
+<ToggleButton pressed={showGrid} onPressedChange={setShowGrid}>
+  Show grid
+</ToggleButton>
+```
+
+For an icon-only toggle, opt in explicitly and provide its accessible name:
+
+```tsx
+<ToggleButton
+  iconOnly
+  aria-label="Pin inspector"
+  pressed={pinned}
+  onPressedChange={setPinned}
+>
+  <PinIcon />
+</ToggleButton>
+```
+
+## Variants and sizes
+
+- `variant`: `default`, `outline`, or `filled`.
+- `size`: `xs`, `sm`, `default`, or `lg`.
+- `iconOnly` makes the control square and requires `aria-label`.
+
+## Choosing the right control
+
+- Use `Button` for a momentary action.
+- Use `ToggleButton` for one independent visible mode or tool.
+- Use `SegmentedControl` for exactly one choice from a small set.
+- Use `Switch` for a persistent setting that takes effect immediately.
+
+## Keyboard and accessibility
+
+Radix supplies button and `aria-pressed` semantics. Space and Enter toggle the
+state. A visible text label or `aria-label` must identify the action; state
+must not be communicated through color alone.
+
+## Don't
+
+- Do not use a toggle for a one-time command.
+- Do not group unrelated toggles into a segmented control.
+- Do not put a checkbox inside a toggle button.