@plastic-js/tsumiki 0.1.22 → 0.1.24

package/docs/api.md

@@ -0,0 +1,670 @@
+# Tsumiki Component API Reference
+
+> Public API contract for `@plastic-js/tsumiki` (v0.1.x).
+
+This document is the authoritative reference for the components exported from the package root (`@plastic-js/tsumiki`). It is part of the version 1.0 API contract: anything documented here is stable; anything not documented here (deep imports into `dist/components`, `.origin` internals, or `...rest` passthrough behavior) is **not** part of the contract and may change without a major version bump.
+
+> Components still **in development** (`Accordion`, `Carousel`, `Combobox`, `Listbox`, `Tour`, `TreeView`) are intentionally **not documented** here — their APIs are not yet frozen. They remain importable but are outside the v1 contract.
+
+## Conventions
+
+### Controlled-only
+
+Tsumiki is **controlled-only**. State-managing components (`value`, `open`, `checked`, …) receive state as a signal and report changes via a callback. There are no `defaultValue` / `defaultOpen` / `defaultChecked` props.
+
+```jsx
+const isOpen = createSignal(false)
+<Dialog open={isOpen} onOpenChange={v => isOpen(v.open)} />
+```
+
+### Reactive props
+
+Any prop may be a static value **or** a Plastic reactive getter function:
+
+```jsx
+<Switch size="md" />            // static
+<Switch size={() => mySignal()} /> // reactive
+```
+
+### Passthrough
+
+Ark-backed components forward all props **not listed** in their table to the underlying Ark primitive's `Root` (unless stated otherwise). This includes Ark/Zag props, ARIA attributes, and DOM event handlers.
+
+### Escape hatch
+
+Every Ark-backed component exposes `.origin` — a mapping to the raw `@plastic-js/ark` sub-parts, for when you need the full headless API:
+
+```jsx
+<Checkbox.origin.Root>
+  <Checkbox.origin.Control>
+    <Checkbox.origin.Indicator />
+  </Checkbox.origin.Control>
+</Checkbox.origin.Root>
+```
+
+### Size values
+
+The shared `size` prop accepts: `xs | sm | md | lg | xl | xxl` (default `md`).
+
+---
+
+## Inputs & Forms
+
+### Field
+
+A labeled field wrapper combining a label, an error message and helper text.
+
+**Exports:** `Field`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `''` | Field label text. |
+| `error` | `string` | `''` | Error message; when non-empty the field renders in its error state. |
+| `helper` | `string` | `''` | Helper text below the control. |
+| `required` | `boolean` | `false` | Marks the label with a required indicator. |
+| `compact` | `boolean` | `false` | Renders in a compact (smaller) layout. |
+| `children` | `node` | — | The input control (e.g. `<Input />`). |
+
+### Fieldset
+
+Groups several `Field`s with a legend.
+
+**Exports:** `Fieldset`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `legend` | `string` | `''` | Fieldset legend text. |
+| `helper` | `string` | `''` | Helper text below the fields. |
+| `children` | `node` | — | `Field` components to group. |
+
+### Input
+
+**Exports:** `Input` · Escape hatch: `Input.origin.Root`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `solid` | `boolean` | `false` | Filled background instead of outlined. |
+| `size` | `string` | `md` | See size values. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+| `invalid` | `boolean` | `false` | Renders the error/invalid style. |
+| `inputClassName` | `string` | — | Class applied to the raw `<input>` element. |
+| `type` | `string` | — | Input type (e.g. `text`, `password`). |
+| `prefix` | `node` | — | Content rendered before the input (e.g. an icon). |
+| `suffix` | `node` | — | Content rendered after the input. |
+| `ref` | `ref` | — | Ref to the underlying `<input>`. |
+
+### CardNumberInput
+
+Credit-card number input with automatic `XXXX-XXXX-XXXX-XXXX` grouping.
+
+**Exports:** `CardNumberInput`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| (() => string)` | — | Card number (digits only). |
+| `onValueChange` | `(value) => void` | — | Called with the raw digits. |
+| `invalid` | `boolean` | `false` | Error state. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `placeholder` | `string` | — | Placeholder text. |
+
+### MoneyInput
+
+Currency-formatted numeric input.
+
+**Exports:** `MoneyInput`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number \| (() => number)` | — | Numeric value. |
+| `onValueChange` | `(value) => void` | — | Called with the parsed number. |
+| `invalid` | `boolean` | `false` | Error state. |
+| `currency` | `string` | — | Currency code (e.g. `TWD`, `USD`). |
+| `affix` | `node` | — | Custom prefix/suffix content. |
+| `placeholder` | `string` | — | Placeholder text. |
+| `disabled` | `boolean` | `false` | Disabled. |
+
+### NumberInput
+
+**Exports:** `NumberInput` · Escape hatch: `NumberInput.origin.{Root, DecrementTrigger, Input, IncrementTrigger}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `children` | `node` | — | Custom triggers, if any. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `min`, `max`, `step`, `formatOptions`, …).
+
+### SearchInput
+
+**Exports:** `SearchInput`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `placeholder` | `string` | — | Placeholder text. |
+| `onInput` | `(value) => void` | — | Called with the current query. |
+
+### TagsInput
+
+**Exports:** `TagsInput` · Escape hatch: `TagsInput.origin.{Root, Label, Control, Input, Item, ItemPreview, ItemText, ItemDeleteTrigger, ItemInput, ClearTrigger, HiddenInput}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Root class. |
+| `label` | `string` | — | Optional label text. |
+| `placeholder` | `string` | — | Input placeholder. |
+| `children` | `node` | — | Custom item rendering. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `allowOverflow`, `validate`, …).
+
+### DateInput
+
+Mobile date picker built on the `DateWheel` utility.
+
+**Exports:** `DateInput`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| (() => string)` | — | ISO date string. |
+| `onValueChange` | `(value) => void` | — | Called with the new ISO date. |
+| `placeholder` | `string` | — | Placeholder text. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `className` | `string` | — | Root class. |
+
+### ColorPicker
+
+**Exports:** `ColorPicker` · Escape hatch: `ColorPicker.origin.*` (full Ark surface: `Root`, `Label`, `Control`, `Trigger`, `Positioner`, `Content`, `ValueSwatch`, `ValueText`, `Area`, `ChannelSlider`, `ChannelInput`, `TransparencyGrid`, `EyeDropperTrigger`, …)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Optional label text. |
+| `showAlpha` | `boolean` | — | Show the alpha channel. |
+| `eyedropper` | `boolean` | — | Show the eyedropper trigger. |
+| `hiddenInput` | `boolean` | — | Render a hidden input. |
+| `onChange` | `(value) => void` | — | Called on color change. |
+| `size` | `string` | `md` | See size values. |
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Custom content. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `format`, …).
+
+### Clipboard
+
+**Exports:** `Clipboard`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `copiedDuration` | `number` | `2000` | ms to keep the "copied" state after copying. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, …).
+
+---
+
+## Buttons & Toggles
+
+### Button
+
+**Exports:** `Button` · Escape hatch: `Button.origin.Root`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `solid` | `boolean` | `false` | Filled (solid) variant instead of outline. |
+| `danger` | `boolean` | `false` | Destructive (red) variant. |
+| `size` | `string` | `md` | See size values. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `loading` | `boolean` | `false` | Shows a spinner and blocks interaction. |
+| `children` | `node` | — | Button content. |
+
+### Checkbox
+
+**Exports:** `Checkbox` · Escape hatch: `Checkbox.origin.{Root, Label, Control, Indicator, HiddenInput, Group}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `rounded` | `boolean` | `true` | Rounded (pill) control shape. |
+| `invalid` | `boolean` | `false` | Error state. |
+| `children` | `node` | — | Label content. |
+
+Passthrough: Ark `Root` props (`checked`, `onCheckedChange`, `disabled`, `indeterminate`, …).
+
+### Switch
+
+**Exports:** `Switch` · Escape hatch: `Switch.origin.{Root, Control, Thumb, Label, HiddenInput}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `children` | `node` | — | Label content. |
+
+Passthrough: Ark `Root` props (`checked`, `onCheckedChange`, `disabled`, …).
+
+### Toggle
+
+**Exports:** `Toggle` · Escape hatch: `Toggle.origin.Root`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Content. |
+
+Passthrough: Ark `Root` props (`pressed`, `onPressedChange`, …).
+
+### ToggleGroup
+
+**Exports:** `ToggleGroup`, `ToggleGroupItem` · Escape hatch: `ToggleGroup.origin.{Root, Item}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `children` | `node` | — | `ToggleGroupItem` elements. |
+
+### RadioGroup
+
+**Exports:** `RadioGroup` · Escape hatch: `RadioGroup.origin.{Root, Label, Item, ItemControl, ItemText, ItemHiddenInput, Indicator}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Group label text. |
+| `items` | `array` | — | Data items (see `SelectPc` collection semantics). |
+| `className` | `string` | — | Root class. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `disabled`, …).
+
+### RatingGroup
+
+**Exports:** `RatingGroup` · Escape hatch: `RatingGroup.origin.{Root, Label, Control, Item, ItemText, HiddenInput}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `count` | `number` | `5` | Number of rating items. |
+| `label` | `string` | — | Optional label. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `readOnly`, …).
+
+---
+
+## Selection & Capture
+
+### Select
+
+Mobile-optimized bottom-sheet select (draggable sheet overlay).
+
+**Exports:** `Select`, `SelectTrigger`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string \| (() => string)` | — | Selected value. |
+| `onValueChange` | `(value) => void` | — | Called when an item is selected. |
+| `items` | `array \| (() => array)` | `[]` | Data array. |
+| `itemToValue` | `(item) => string` | `item.value` | Extract value from an item. |
+| `itemToLabel` | `(item) => node` | `item.label` | Extract label from an item. |
+| `open` | `(() => boolean)` | — | **Required** controlled open state. |
+| `onOpenChange` | `(open) => void` | — | Open/close callback. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `clearable` | `boolean` | `false` | Show a clear trigger. |
+| `clearLabel` | `string` | — | Accessible label for the clear trigger. |
+| `filter` | `(item, query, itemToLabel) => boolean` | — | Custom filter for the search box. |
+| `placeholder` | `string` | — | Trigger placeholder. |
+| `backdropClassName` | `string` | — | Backdrop class. |
+| `backdropStyle` | `object` | — | Backdrop inline styles. |
+| `children` | `node` | — | Custom trigger (`SelectTrigger`). |
+| `item` | `node` | — | Custom item renderer. |
+
+### SelectPc
+
+Desktop (popover-style) select built on Ark `Select`.
+
+**Exports:** `SelectPc` · Escape hatch: `SelectPc.origin.{Root, Trigger, Indicator, Positioner, Content, List, Item, ItemText, ValueText, HiddenSelect}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `solid` | `boolean` | `false` | Filled trigger variant. |
+| `size` | `string` | `md` | See size values. |
+| `disabled` | `boolean` | `false` | Disabled. |
+| `invalid` | `boolean` | `false` | Error state. |
+| `positioning` | `object` | `{ sameWidth: true }` | Positioning options. |
+| `children` | `node` | — | `SelectPc.origin.Item` elements or custom content. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `collection`, …). Note: unlike `Select`, it is **not** controlled-only at the tsumiki level — state flows through the Ark props.
+
+### FileUpload
+
+**Exports:** `FileUpload`, `FileUploadItemGroup`, `FileUploadItem`, `FileUploadClearTrigger` · Escape hatch: `FileUpload.origin.{Root, Label, Dropzone, Trigger, ItemGroup, Item, ItemName, ItemSizeText, ItemDeleteTrigger, ClearTrigger, HiddenInput}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Root class. |
+| `file` | `object` | — | A controlled file object. |
+| `children` | `node` | — | `FileUploadItemGroup` / `FileUploadItem` elements. |
+
+Passthrough: Ark `Root` props (`accept`, `multiple`, `maxFiles`, `onFileAccept`, …).
+
+### SignaturePad
+
+**Exports:** `SignaturePad`, `ClearTrigger` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `'Signature'` | Accessible label / placeholder. |
+| `height` | `number` | `160` | Canvas height in px. |
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Custom content. |
+
+---
+
+## Navigation & Data
+
+### Tabs
+
+**Exports:** `Tabs` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `triggers` | `array` | — | Tab trigger definitions (`{ value, label }`). |
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Tab panels keyed by value. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `orientation`, …).
+
+### Steps
+
+**Exports:** `Steps` · Escape hatch: `Steps.origin.{Root, List, Item, Trigger, Content, CompletedContent, Separator, PrevTrigger, NextTrigger, Indicator, Progress}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `array` | — | Step definitions (`{ title, description, ... }`). |
+| `vertical` | `boolean` | `false` | Vertical layout. |
+| `value` | `number` | `0` | Active step index. |
+| `onValueChange` | `(value) => void` | — | Step-change callback. |
+| `completedContent` | `node` | — | Content shown on the last step. |
+| `className` | `string` | — | Root class. |
+
+### Menu
+
+**Exports:** `Menu`, `MenuTrigger`, `MenuContent`, `MenuItem`, `MenuSeparator` · Escape hatch: `Menu.origin.{Root, Trigger, Positioner, Content, Item, Separator}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | `MenuTrigger` / `MenuContent` elements. |
+
+### Pagination
+
+**Exports:** `Pagination` · Escape hatch: `Pagination.origin.Root`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `prevLabel` | `string` | — | Previous-page label. |
+| `nextLabel` | `string` | — | Next-page label. |
+| `prevChildren` | `node` | — | Custom previous trigger content. |
+| `nextChildren` | `node` | — | Custom next trigger content. |
+| `className` | `string` | — | Root class. |
+
+Passthrough: Ark `Root` props (`count`, `pageSize`, `page`, `onPageChange`, …).
+
+---
+
+## Content & Layout
+
+### Collapsible
+
+**Exports:** `Collapsible` · Escape hatch: `Collapsible.origin.{Root, Trigger, Content}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | `Trigger` / `Content` elements. |
+
+### Splitter
+
+**Exports:** `Splitter`, `SplitterPanel`, `SplitterResizeTrigger`, `SplitterResizeTriggerIndicator` · Escape hatch: `Splitter.origin.{Root, Panel, ResizeTrigger, ResizeTriggerIndicator}`
+
+Passthrough: Ark `Root` props (`size`, `onSizeChange`, `orientation`, …).
+
+### SwipeReveal
+
+Touch-driven swipe-to-reveal row.
+
+**Exports:** `SwipeReveal` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `actions` | `array` | — | Action definitions; each item supplies `{ color, label, ... }` (background is consumer-defined). |
+| `activeId` | `string` | — | The id of the currently open row. |
+| `thisId` | `string` | — | This row's id (used to coordinate with `activeId`). |
+| `onSwipeStart` | `() => void` | — | Called when a swipe begins. |
+| `onOpenChange` | `(open) => void` | — | Open/close callback. |
+| `children` | `node` | — | Row content. |
+
+---
+
+## Elements
+
+### Avatar
+
+**Exports:** `Avatar`, `AvatarImage`, `AvatarFallback` · Escape hatch: `Avatar.origin.{Root, Image, Fallback}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `string` | `'image'` | `'image'` (photo) or `'initials'` (initial letter). |
+| `name` | `string` | `''` | Person's name (used for initials/alt). |
+| `gender` | `string` | `'male'` | Initials color treatment. |
+| `src` | `string` | `''` | Image source. |
+| `alt` | `string` | `''` | Image alt text. |
+| `style` | `object` | — | Root inline styles. |
+| `children` | `node` | — | Fallback content. |
+
+### Icon
+
+**Exports:** `Icon` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `svg` | `node` | — | The SVG element to render. |
+| `size` | `number` | `22` | Icon size in px. |
+| `strokeWidth` | `number` | `1.25` | Stroke width. |
+| `className` | `string` | — | Root class. |
+
+### CloseButton
+
+**Exports:** `CloseButton` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Close icon (defaults to ✕). |
+
+### Skeleton
+
+Pure-CSS loading placeholder.
+
+**Exports:** `Skeleton` · no `.origin`
+
+Accepts no tsumiki-specific props; `className`/style/DOM props pass through.
+
+### Spinner
+
+Pure-CSS spinner.
+
+**Exports:** `Spinner` · no `.origin`
+
+Accepts no tsumiki-specific props; `className`/style/DOM props pass through.
+
+---
+
+## Feedback
+
+### Slider
+
+**Exports:** `Slider` · Escape hatch: `Slider.origin.{Root, Label, Control, Track, Range, Thumb, DraggingIndicator, ValueText, HiddenInput}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | — | Accessible label. |
+| `className` | `string` | — | Root class. |
+| `children` | `node` | — | Custom value rendering. |
+
+Passthrough: Ark `Root` props (`value`, `onValueChange`, `min`, `max`, `step`, `thumbAlignment`, …) — defaults `min: 0`, `max: 100`, `step: 1`, `thumbAlignment: 'center'` are supplied by tsumiki.
+
+### Progress
+
+**Exports:** `Progress`, `ProgressLabel` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `string` | `md` | See size values. |
+| `striped` | `boolean` | `false` | Animated striped fill. |
+| `className` | `string` | — | Root class. |
+
+Passthrough: Ark `Root` props (`value`, `min`, `max`, …).
+
+---
+
+## Overlays
+
+### Dialog
+
+**Exports:** `Dialog` · Escape hatch: `Dialog.origin.{Root, Trigger, Backdrop, Positioner, Content, Title, Description, CloseTrigger}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `string` | `'modal'` | `'modal'` or `'nonModal'`. |
+| `open` | `boolean \| (() => boolean)` | — | **Required** controlled open state. |
+| `onOpenChange` | `(v) => void` | — | Receives `{ open }`; sync your state here. |
+| `onOpen` | `() => void` | — | Fired when opened. |
+| `onClose` | `() => void` | — | Fired when closed. |
+| `title` | `string` | — | Dialog title. |
+| `icon` | `node` | — | Optional icon above the title. |
+| `message` | `string` | — | Body text. |
+| `showCancel` | `boolean` | `true` | Show the cancel button. |
+| `showConfirm` | `boolean` | `true` | Show the confirm button. |
+| `cancelText` | `string` | `'Cancel'` | Cancel button label. |
+| `confirmText` | `string` | `'Confirm'` | Confirm button label. |
+| `onCancel` | `() => void` | — | Cancel callback. |
+| `onConfirm` | `() => void` | — | Confirm callback. |
+| `loading` | `boolean` | `false` | Confirm button shows a spinner. |
+| `danger` | `boolean` | `false` | Confirm button uses the danger style. |
+| `closeable` | `boolean` | `true` | Show the close (✕) trigger. |
+| `lazyMount` | `boolean` | `true` | Mount content lazily. |
+| `unmountOnExit` | `boolean` | `true` | Unmount content when closed. |
+| `closeOnInteractOutside` | `boolean` | `false` | Close when clicking outside. |
+| `footer` | `node` | — | Custom footer replacing the default buttons. |
+| `class` | `string` | — | Content class. |
+| `children` | `node` | — | Custom body content. |
+
+### ConfirmDialog
+
+Imperative + declarative confirm dialog built on `Dialog`.
+
+**Exports:** `ConfirmDialog`, `confirm`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `string` | — | `'alert'` / `'confirm'` / `'prompt'`-style mode. |
+| `open` | `boolean \| (() => boolean)` | — | Controlled open state. |
+| `onOpenChange` | `(v) => void` | — | Open/close callback. |
+| `onConfirm` | `() => void` | — | Confirm callback. |
+| `onCancel` | `() => void` | — | Cancel callback. |
+| `loading` | `boolean` | `false` | Confirm button loading. |
+| `title` | `string` | — | Title. |
+| `message` | `string` | — | Body message. |
+| `confirmText` | `string` | — | Confirm button label. |
+| `cancelText` | `string` | — | Cancel button label. |
+| `danger` | `boolean` | `false` | Danger-styled confirm button. |
+
+Imperative API:
+
+```js
+await confirm({ title, message, danger, confirmText })
+// resolves true/false
+```
+
+### Drawer
+
+Side drawer overlay.
+
+**Exports:** `Drawer`, `DrawerTrigger`, `DrawerContent` · Escape hatch: `Drawer.origin.{Root, Trigger, Backdrop, Positioner, Content, Title, Description, CloseTrigger}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean \| (() => boolean)` | — | **Required** controlled open state. |
+| `onOpenChange` | `(v) => void` | — | Open/close callback. |
+| `onOpen` | `() => void` | — | Fired when opened. |
+| `onClose` | `() => void` | — | Fired when closed. |
+| `closeOnInteractOutside` | `boolean` | — | Close when clicking outside. |
+| `lazyMount` | `boolean` | — | Mount lazily. |
+| `zIndex` | `number` | — | Overlay z-index. |
+| `title` | `string` | — | Drawer title. |
+| `icon` | `node` | — | Optional icon. |
+| `description` | `string` | — | Subtitle text. |
+| `children` | `node` | — | Drawer body. |
+
+### Toast
+
+**Exports:** `Toast`, `ToastTitle`, `ToastDescription`, `ToastCloseTrigger`, `ToastIcon`, `ToastToaster`, `createToaster` · Escape hatch: `Toast.origin.{Root, Title, Description, CloseTrigger, Toaster}`
+
+Imperative API:
+
+```js
+const toaster = createToaster()
+<ToastToaster toaster={toaster} />
+toaster.create({ title, description, type: 'success' })
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `toaster` | `object` | — | Toaster instance (on `ToastToaster`). |
+| `className` | `string` | — | Root class. |
+
+### Popover
+
+**Exports:** `Popover` · Escape hatch: `Popover.origin.{Root, Trigger, Positioner, Content, Arrow, ArrowTip, CloseTrigger, Title, Description}`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `lazyMount` | `boolean` | `true` | Mount content lazily. |
+| `unmountOnExit` | `boolean` | `true` | Unmount when closed. |
+| `closeable` | `boolean` | `false` | Show the close (✕) trigger. |
+
+Passthrough: Ark `Root` props (`open`, `onOpenChange`, `positioning`, …).
+
+### BottomSheet
+
+Mobile bottom sheet (drag-to-dismiss).
+
+**Exports:** `BottomSheet` · no `.origin`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `dismissible` | `boolean` | `true` | Allow dismiss. |
+| `backdropBlur` | `boolean` | `true` | Blur the backdrop. |
+
+Passthrough: DOM props (`open`, `onOpenChange`, `title`, `children`, …).
+
+---
+
+## Utilities
+
+### Portal
+
+**Exports:** `Portal` · no `.origin`
+
+Renders children into `document.body` (or a `container` prop if provided).
+
+### Presence
+
+**Exports:** `Presence` · no `.origin`
+
+Applies presence/mount transitions; used internally by overlay components. Pass-through component.
+
+### FocusTrap
+
+**Exports:** `FocusTrap` · no `.origin`
+
+Traps focus within its children; accepts `disabled`, `initialFocus`, `returnFocus` DOM props.
+
+---
+