@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/context-card.md

@@ -0,0 +1,73 @@
+# ContextCard
+
+**Status:** stable
+
+Hover/focus-triggered rich preview card over Base UI PreviewCard. Reveals contextual content (a profile, an edition summary) from an inline anchor; 20rem-wide surface with delayed open and collision-aware positioning.
+
+**Keywords:** context card, rich tooltip, hover card, preview
+
+## Usage
+
+Use ContextCard to show richer contextual content near a trigger without taking users out of flow.
+
+### Best practices
+
+- Do: Use it for previews, summaries, or supporting context tied to a specific element.
+- Do: Keep the card read-only and make the trigger the action: it is a real link to the full profile or item. Keyboard users cannot reach a button inside the card, because moving focus off the trigger closes it. If the preview needs an action (Follow, Add), use a Popover instead.
+- Don't: Do not put critical decisions, long forms, or required workflow steps inside ContextCard.
+- Don't: Do not open it on click. It is a hover/focus preview; making it click-triggered gives you a Popover with no dismiss affordance and no way to reach the content it previews.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| ContextCardTrigger | yes | The element that anchors the card. |
+| ContextCardContent | yes | The contextual surface shown near the trigger. |
+| ContextCardArrow | no | An optional arrow connecting card and trigger. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ContextCardTrigger | Base UI Trigger props + render + delay \| closeDelay | The inline anchor (renders an <a>). Use render={<a href='…'/>} to compose with a link. delay defaults to 600ms, closeDelay to 300ms. |
+| ContextCardContent | Base UI Popup props + side \| align \| sideOffset + className | Portals + positions + paints the popup; surface is a fixed 20rem-wide card. side is which side of the trigger to render against (auto-flips on collision), align the alignment along it, sideOffset the gap in px. Defaults to side="bottom", align="center", sideOffset=8. |
+| ContextCardArrow | Base UI Arrow props + className | Optional pointer connecting the popup to its trigger. Place inside ContextCardContent. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ContextCard (Root) | Base UI PreviewCard.Root props (open, defaultOpen, onOpenChange) | — | Groups the trigger and content. Uncontrolled by default; opens on hover/focus of the trigger. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `muted-foreground`, `accent`
+
+## Accessibility
+
+- Opens on hover and on keyboard focus of the trigger, after a short delay; dismisses on Esc, outside press, and blur.
+- The trigger renders an <a> by default — compose render={<a href='…'/>} so it stays a real, navigable link.
+- Base UI wires the popup's ARIA association with the trigger; the card holds non-interactive context, not focusable controls.
+- Animate via data-[starting-style]/data-[ending-style] opacity attributes on the popup.
+
+## Related
+
+- Components: Popover, Tooltip
+
+## Examples
+
+### Profile preview
+
+```tsx
+import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Entity } from "@sableui/react"
+
+<ContextCard><ContextCardTrigger render={<a href='/u/ada' className='text-title-sm underline-offset-2 hover:underline'>@ada</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='AL' size='lg' />} title='Ada Lovelace' subtitle='@ada' /><p className='mt-3 text-body-sm text-muted-foreground'>Minting generative editions on Solana. Permanently on Arweave.</p></ContextCardContent></ContextCard>
+```
+
+### With stat row
+
+```tsx
+import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Description, DescriptionItem, Entity } from "@sableui/react"
+
+<ContextCard><ContextCardTrigger render={<a href='/u/nyx' className='text-title-sm underline-offset-2 hover:underline'>@nyx</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='NY' size='lg' />} title='Nyx' subtitle='@nyx' /><Description cols='2' className='mt-4 border-t border-border pt-3'><DescriptionItem term='Posts' detail='128' /><DescriptionItem term='Followers' detail='4.2k' /></Description></ContextCardContent></ContextCard>
+```

package/llms/components/context-menu.md

@@ -0,0 +1,79 @@
+# ContextMenu
+
+**Status:** stable
+
+Right-click menu over Base UI ContextMenu — opens on the native contextmenu event or long press and positions at the pointer. Shares Menu's roving focus, typeahead, ARIA menu/menuitem wiring, collision-aware positioning, and Esc/outside dismissal.
+
+**Keywords:** context menu, right click, overflow, menu
+
+## Usage
+
+Use ContextMenu for actions that are specific to the object or area the user invoked.
+
+### Best practices
+
+- Do: Use it for secondary object actions such as rename, duplicate, move, or delete.
+- Do: Group destructive or uncommon actions away from frequent safe actions.
+- Don't: Do not make ContextMenu the only way to access a primary or required action.
+- Don't: Do not rely on it for touch. There is no right-click on a touchscreen — the long-press fallback is discoverable by nobody, so anything in here needs a visible route too.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| ContextMenuTrigger | yes | The target area or element that opens the menu. |
+| ContextMenuContent | yes | The menu surface. |
+| ContextMenuItem | yes | One actionable command. |
+| ContextMenuSeparator | no | A divider between command groups. |
+| ContextMenuGroup | no | A semantic group of related commands. |
+| ContextMenuGroupLabel | no | An optional label for a command group. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ContextMenuTrigger | Base UI ContextMenu.Trigger props + className + render | The right-clickable area that opens the menu on contextmenu (right click) or long press. Renders a <div>. |
+| ContextMenuContent | Base UI Popup props + { side, align, sideOffset, className } | Portal + Positioner + Popup. Positions at the pointer. side is which side of the anchor the popup renders against (auto-flips on collision), align its alignment along that side, sideOffset the gap in px. Defaults to side='bottom', align='start', sideOffset=6. |
+| ContextMenuItem | Base UI ContextMenu.Item props + variant?: "default" \| "destructive" + className (disabled, closeOnClick, onClick) | An interactive row. Lays out as a flex row, so a leading Icon sits inline before the label. Highlights via data-[highlighted]; dims via data-[disabled], and disabled items are skipped by keyboard focus. variant="destructive" marks a destructive command (Delete, Remove) and keeps its destructive ink while highlighted; never fake it with a text-destructive class, which the highlight repaints. |
+| ContextMenuSeparator | Base UI Separator props + className | Hairline rule between item runs. |
+| ContextMenuGroup | Base UI ContextMenu.Group props + className | Groups related items under an accessible label auto-associated with the group. |
+| ContextMenuGroupLabel | Base UI ContextMenu.GroupLabel props + className | The label for a ContextMenuGroup. Auto-associated with the group it sits in. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ContextMenu (Root) | Base UI ContextMenu.Root props (open, defaultOpen, onOpenChange, orientation, loopFocus) | — | Groups all parts and controls open state. Renders no element. Uncontrolled by default. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `muted-foreground`
+
+## Accessibility
+
+- Base UI provides role=menu/menuitem, roving tabindex, arrow-key navigation, and typeahead.
+- Opens on right click (contextmenu) or long press; Esc and outside-press dismiss and restore focus.
+- Animate open/close via data-[starting-style]/data-[ending-style] attributes.
+- ContextMenuGroupLabel is auto-associated with its ContextMenuGroup for screen readers.
+
+## Related
+
+- Components: Menu, DotsMenu
+
+## Examples
+
+### Basic
+
+```tsx
+import { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger } from "@sableui/react"
+
+<ContextMenu><ContextMenuTrigger className="rounded-md border border-dashed border-border p-8 text-center text-body-sm text-muted-foreground">Right-click here</ContextMenuTrigger><ContextMenuContent><ContextMenuItem>Cut</ContextMenuItem><ContextMenuItem>Copy</ContextMenuItem><ContextMenuItem>Paste</ContextMenuItem><ContextMenuSeparator /><ContextMenuItem variant="destructive">Delete</ContextMenuItem></ContextMenuContent></ContextMenu>
+```
+
+### Grouped
+
+```tsx
+import { ContextMenu, ContextMenuContent, ContextMenuGroup, ContextMenuGroupLabel, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger } from "@sableui/react"
+
+<ContextMenu><ContextMenuTrigger className="rounded-md border border-dashed border-border p-8">Right-click here</ContextMenuTrigger><ContextMenuContent><ContextMenuGroup><ContextMenuGroupLabel>Layout</ContextMenuGroupLabel><ContextMenuItem>Move up</ContextMenuItem><ContextMenuItem>Move down</ContextMenuItem></ContextMenuGroup><ContextMenuSeparator /><ContextMenuItem>Duplicate</ContextMenuItem></ContextMenuContent></ContextMenu>
+```

package/llms/components/data-table.md

@@ -0,0 +1,99 @@
+# DataTable
+
+**Status:** stable
+
+A data-driven table over the Table primitives — a columns def + data array with built-in client-side sorting (click a sortable header to cycle asc → desc → none), optional row click / selection, and an empty state. For server data or paging, sort/page the data and pair with Pagination.
+
+**Keywords:** data table, table, sortable, columns, rows, empty state, pagination, list
+
+## Usage
+
+Use DataTable when a data array and column definition should render a sortable, semantic table with optional row actions and an empty state. Use the lower-level Table parts for hand-authored markup or highly custom row layouts.
+
+### Best practices
+
+- Do: Put a table that fills a card in <CardContent flush>. The table runs edge to edge and its first and last columns inset to the card padding on their own; do not hand-set pl-6 / pr-6 on columns.
+- Do: Provide stable rowKey values for dynamic data so selection and sorting do not jump.
+- Do: Use sortable only on columns where ordering is obvious and useful.
+- Do: Pair server-side datasets with Pagination and pass already-sorted/paged rows.
+- Don't: Make every row clickable and also fill it with competing buttons. Choose a clear row interaction model.
+- Don't: Use DataTable for heterogeneous cards or timeline content. A list or card layout will scan better.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Columns | yes | Definitions for headers, cell renderers, sorting, alignment, and classes. |
+| Rows | yes | The data array rendered through the column definitions. |
+| Empty state | no | Content spanning all columns when the row array is empty. |
+| Caption | no | Accessible table caption rendered by the underlying Table. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| columns | DataTableColumn<Row>[] | — | Column defs: { key, header, cell?, sortValue?, sortable?, align?, className? }. cell defaults to row[key]; sortValue defaults to row[key]. When cell renders a formatted string (e.g. a date), pass sortValue returning the underlying value (e.g. date.getTime()) so the column sorts by the real value, not the rendered text. |
+| data | Row[] | — | The rows to render. |
+| rowKey | (row, index) => string \| number | index | Stable React key per row. |
+| onRowClick | (row) => void | — | Row click handler — makes rows pointer-interactive. |
+| isRowSelected | (row) => boolean | — | Mark a row visually selected (data-selected). Derive it from a stable id (row.id === selectedId), not the row index, so selection survives re-sorts. |
+| defaultSort | { key: string; direction: "asc" \| "desc" } | — | Initial sort column + direction. |
+| empty | ReactNode | "No results." | Rendered spanning all columns when data is empty. Pass an EmptyState for the full treatment (icon, title, next step). |
+| caption | ReactNode | — | Bottom table caption. |
+
+## Tokens used
+
+`muted-foreground`, `foreground`, `ring`
+
+## Accessibility
+
+- Sorted columns set aria-sort=ascending/descending on the header cell.
+- Sortable headers are real <button>s with a focus-visible ring, keyboard-operable.
+- Inherits the Table's scrollable frame and semantic <table>/<th>/<td> structure.
+
+## Related
+
+- Components: Table, Pagination, EmptyState, Badge
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### Sortable columns
+
+```tsx
+import { DataTable } from "@sableui/react"
+
+<DataTable data={users} columns={[{ key: "name", header: "Name", sortable: true }, { key: "role", header: "Role" }, { key: "joined", header: "Joined", sortable: true, sortValue: (u) => u.joinedAt, cell: (u) => formatDate(u.joinedAt) }]} />
+```
+
+### Clickable rows
+
+```tsx
+import { DataTable } from "@sableui/react"
+
+<DataTable data={posts} columns={cols} onRowClick={(p) => navigate(`/post/${p.id}`)} rowKey={(p) => p.id} />
+```
+
+### Rich status column
+
+```tsx
+import { Avatar, Badge, DataTable, Entity } from "@sableui/react"
+
+<DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "name", header: "Name", sortable: true }, { key: "status", header: "Status", cell: (row) => <Badge appearance="plain" tone={row.status === "failed" ? "destructive" : row.status === "building" ? "warning" : "success"} dot>{row.statusLabel}</Badge> }, { key: "owner", header: "Owner", cell: (row) => <Entity className="[--entity-px:0] [--entity-py:0]" leading={<Avatar src={row.owner.avatar} alt={row.owner.name} fallback={row.owner.initials} size="sm" />} title={row.owner.name} /> }]} />
+```
+
+### In a card, edge to edge
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle, DataTable } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Deployments</CardTitle></CardHeader><CardContent flush><DataTable data={deployments} rowKey={(row) => row.id} columns={[{ key: "project", header: "Project", sortable: true }, { key: "duration", header: "Duration", align: "end" }]} /></CardContent></Card>
+```
+
+### Empty state
+
+```tsx
+import { Button, DataTable, EmptyState, Icon } from "@sableui/react"
+
+<DataTable data={[]} columns={[{ key: "name", header: "Name" }, { key: "status", header: "Status" }]} empty={<EmptyState icon={<Icon name="search" />} title="No deployments" description="Try a different filter or create a deployment." action={<Button>Create deployment</Button>} />} />
+```

package/llms/components/date-picker.md

@@ -0,0 +1,97 @@
+# DatePicker
+
+**Status:** stable
+
+Date (and optionally time) picker: a field-shaped trigger (the Input / SelectTrigger shell) opens a Popover holding Sable's Calendar. With granularity="day" selecting a day fires onValueChange and closes; granularity="minute" adds an hour + minute row of Selects and keeps the time-of-day when the day changes.
+
+**Keywords:** date picker, calendar, date input, date time picker, time, schedule, form
+
+## Usage
+
+Use DatePicker when users need to choose one date — or, with granularity="minute", one date and time — from a compact control.
+
+### Best practices
+
+- Do: Use it in forms where a typed date alone would be error-prone.
+- Do: Show clear selected and disabled states when date rules apply.
+- Do: Set granularity="minute" when a time matters, with a minuteStep that matches the real precision (15 for meetings, 5 for scheduled posts).
+- Don't: Do not show a time without saying which zone it is in. A meeting time with no zone is wrong for everyone not in yours — wrap the picker in a Field whose description names the zone.
+- Don't: Do not leave the format ambiguous. `03/04` is two different dates depending on the reader's locale — the trigger shows a formatted date precisely so the interpretation is not guessed.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | Date | — | The selected date (controlled). When absent, the trigger shows a muted placeholder. |
+| defaultValue | Date | — | Initial value when uncontrolled (no `value` prop). |
+| onValueChange | (date: Date \| undefined) => void | — | Fired when the day is chosen or cleared, and under granularity="minute" when the hour or minute changes. With granularity="day" it also closes the popover. |
+| onChange | (date: Date \| undefined) => void | — | Deprecated alias for onValueChange, kept for backwards compatibility. Both fire when set; prefer onValueChange. |
+| granularity | "day" \| "minute" | "day" | What the picker chooses. "minute" adds an hour + minute row and keeps the popover open so day and time can be set in any order. |
+| minuteStep | number | 5 | Minute increment for the time row (granularity="minute" only). |
+| defaultTime | string | "00:00" | Time-of-day shown and applied while nothing is selected yet, as 24h "HH:mm" — the first day pick lands on this time instead of midnight (granularity="minute" only). |
+| placeholder | string | "Pick a date" ("Pick date & time" with granularity="minute") | Trigger label shown when no date is selected. |
+| disabled | boolean | — | Disable the trigger and block selection. |
+| minDate | Date | — | Earliest selectable day (inclusive). Earlier days are disabled and navigation is bounded. |
+| maxDate | Date | — | Latest selectable day (inclusive). Later days are disabled and navigation is bounded. |
+| className | string | — | Extra classes merged onto the trigger. |
+| id / aria-label / aria-labelledby / aria-describedby / aria-invalid / aria-required | button attributes | — | Forwarded to the trigger, so a wrapping Field ties its label to the picker and announces its description and error. Pass them yourself only when labelling the picker without a Field. |
+
+## Tokens used
+
+`primary`, `primary-foreground`, `accent`, `accent-foreground`, `foreground`, `muted-foreground`, `popover`, `popover-foreground`, `border`, `input`, `card`, `ring`
+
+## Accessibility
+
+- Trigger opens on click/Enter/Space; the popover traps focus and restores it to the trigger on close (Base UI Popover).
+- The calendar grid (react-day-picker) provides a roving tabindex, arrow-key day navigation, and aria-selected on the chosen day.
+- Navigation chevrons render through the Icon adapter and inherit the calendar's button labels.
+- Esc and outside press dismiss the popover.
+- With granularity="minute" the hour and minute Selects are full Base UI listboxes (typeahead, ARIA) labelled "Hour" and "Minute"; selecting a day keeps the chosen time-of-day, so day and time can be set in any order.
+
+## Related
+
+- Components: Calendar, Field
+
+## Examples
+
+### Controlled
+
+```tsx
+import { DatePicker } from "@sableui/react"
+
+const [date, setDate] = useState<Date>()
+<DatePicker value={date} onValueChange={setDate} />
+```
+
+### Custom placeholder
+
+```tsx
+import { DatePicker } from "@sableui/react"
+
+<DatePicker placeholder="Schedule for…" value={date} onValueChange={setDate} />
+```
+
+### Date and time
+
+```tsx
+import { DatePicker } from "@sableui/react"
+
+const [start, setStart] = useState<Date>()
+<DatePicker granularity="minute" value={start} onValueChange={setStart} minDate={new Date()} defaultTime="09:00" minuteStep={15} />
+```
+
+### Disabled
+
+```tsx
+import { DatePicker } from "@sableui/react"
+
+<DatePicker disabled />
+```
+
+### Bounded (no past dates)
+
+```tsx
+import { DatePicker } from "@sableui/react"
+
+<DatePicker value={date} onValueChange={setDate} minDate={new Date()} />
+```

package/llms/components/description.md

@@ -0,0 +1,96 @@
+# Description
+
+**Status:** stable
+
+A labeled key/value list (definition list). Compose with DescriptionTerm + DescriptionDetail, or the ergonomic DescriptionItem shorthand. Aligns terms and details into a grid; cols="2" packs pairs two-wide.
+
+**Keywords:** description list, metadata, details, key value
+
+## Usage
+
+Use Description to present label-value details where each term needs a clear corresponding value.
+
+### Best practices
+
+- Do: Use it for object metadata, settings summaries, and read-only record details.
+- Do: Keep terms brief and values scannable so the list works as reference material.
+- Don't: Do not use Description for editable forms; pair Label and form controls instead.
+- Don't: Do not use it for a single key/value. A definition list of one is a labelled value — use a Label and the value, and keep the list semantics for actual lists.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| DescriptionItem | yes | One term and detail pair. |
+| DescriptionTerm | yes | The label for the value. |
+| DescriptionDetail | yes | The value or explanatory detail. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| DescriptionTerm | <dt> props + className | The key. Muted label tier; sits in the first grid column. |
+| DescriptionDetail | <dd> props + tone?: "default" \| "muted" \| "success" \| "warning" \| "destructive" + className | The value. Body tier on the foreground; sits in the second grid column. tone colors the value to encode a status (e.g. Ended → muted, Active → success), replacing inline conditional color classes; defaults to "default". |
+| DescriptionItem | { term: ReactNode; detail?: ReactNode; tone?: "default" \| "muted" \| "success" \| "warning" \| "destructive"; children? } | Ergonomic shorthand for one term/detail pair — renders a DescriptionTerm followed by a DescriptionDetail. Pass the value via detail or children; tone (defaults to "default") colors the detail value the same way it does on DescriptionDetail. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| cols | "1" \| "2" | "1" | Column density. One term/detail column, or two pairs per row once the list's container is at least @md (28rem) wide; narrower, it stays one column. A container query, not a viewport breakpoint, so a narrow card on a wide screen stays one column. With cols="2" the <dl> is wrapped in an @container div. |
+
+## Variants
+
+- **cols**: 1, 2
+- **tone**: default, muted, success, warning, destructive
+
+## Tokens used
+
+`muted-foreground`, `foreground`, `success`, `tone-warning`, `destructive`
+
+## Accessibility
+
+- Renders semantic <dl>/<dt>/<dd> elements so assistive tech announces the term/detail relationship.
+- tone is a visual emphasis only — keep the value text itself meaningful (e.g. "Ended"), never color alone.
+
+## Related
+
+- Components: Fieldset, Entity
+
+## Examples
+
+### Metadata list
+
+```tsx
+import { Description, DescriptionItem } from "@sableui/react"
+
+<Description>
+	<DescriptionItem term="Network" detail="Solana" />
+	<DescriptionItem term="Supply" detail="100" />
+	<DescriptionItem term="Royalty" detail="5%" />
+</Description>
+```
+
+### Composed term/detail
+
+```tsx
+import { Description, DescriptionDetail, DescriptionTerm } from "@sableui/react"
+
+<Description>
+	<DescriptionTerm>Network</DescriptionTerm>
+	<DescriptionDetail>Solana</DescriptionDetail>
+	<DescriptionTerm>Contract</DescriptionTerm>
+	<DescriptionDetail className="text-mono-sm">7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU</DescriptionDetail>
+</Description>
+```
+
+### Toned status value
+
+```tsx
+import { Description, DescriptionItem } from "@sableui/react"
+
+<Description>
+	<DescriptionItem term="Edition" detail="Midnight Archive" />
+	<DescriptionItem term="Status" detail={isEnded ? "Ended" : "Active"} tone={isEnded ? "muted" : "success"} />
+</Description>
+```

package/llms/components/destructive-action-modal.md

@@ -0,0 +1,76 @@
+# DestructiveActionModal
+
+**Status:** stable
+
+Confirmation modal for irreversible actions, built on AlertDialog (role=alertdialog; a backdrop click does not dismiss). Pairs a secondary Cancel with a destructive confirm; awaits an async onConfirm (spinner + stays open on failure) or takes an external pending flag; optional body slot and type-to-confirm guard for high-stakes deletions.
+
+**Keywords:** destructive, modal, confirmation, danger
+
+## Usage
+
+Use DestructiveActionModal to confirm irreversible or high-risk actions before they run.
+
+### Best practices
+
+- Do: Name the affected object and the consequence of the action in plain language.
+- Do: Make the destructive action visually distinct from the cancel path.
+- Don't: Do not use it for routine low-risk actions where undo or inline confirmation would be faster.
+- Don't: Do not put the destructive action where Cancel usually sits, or make it the default focus. A confirmation dialog exists to add friction; autofocusing Delete removes the friction it was added for.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| open | boolean | — | Controlled open state. |
+| onOpenChange | (open: boolean) => void | — | Called when the open state should change (Esc, Cancel, or confirm). A backdrop click does not dismiss. |
+| title | ReactNode | — | Modal heading — names the irreversible action. |
+| description | ReactNode | — | Optional supporting copy explaining the consequence. |
+| confirmLabel | string | "Delete" | Label for the destructive confirm button. |
+| cancelLabel | string | "Cancel" | Label for the dismissing secondary button. |
+| onConfirm | () => void \| Promise<void> | — | Called when the user confirms. If it returns a Promise the modal shows an in-flight spinner, closes on resolve, and stays open on reject; if void it closes immediately (unless pending is controlled). |
+| pending | boolean | — | Externally-driven in-flight state. Overrides the internal await tracking; the parent owns closing (the modal stays open on a synchronous confirm). |
+| confirmingLabel | string | confirmLabel | Confirm-button label shown while the action is in flight. |
+| children | ReactNode | — | Body content rendered between the description and the type-to-confirm Input / footer — e.g. a warning <Note>. |
+| confirmText | string | — | When set, renders an Input the user must type matching to enable the destructive confirm button. |
+
+## Tokens used
+
+`card`, `card-foreground`, `border`, `muted-foreground`, `foreground`, `input`, `destructive`, `destructive-foreground`, `secondary`, `secondary-foreground`
+
+## Accessibility
+
+- Built on AlertDialog (Base UI): role="alertdialog", focus trapping, scroll lock, and aria-modal. Esc dismisses; a click on the backdrop does not, so a stray click can't throw away the decision.
+- Focus opens on Cancel — the safe action — even when a type-to-confirm Input comes first, so a reflexive Enter never fires the destructive action.
+- The title labels the modal; the description describes it.
+- The type-to-confirm Input is wired to its label via htmlFor; the destructive Button is disabled (not just hidden) until the text matches.
+- While a confirm is in flight (awaited onConfirm or pending), both buttons disable, the confirm Button sets aria-busy, and Esc dismissal is blocked so the action can't be interrupted or double-fired.
+
+## Related
+
+- Components: Dialog, Button, Banner
+
+## Examples
+
+### Basic
+
+```tsx
+import { DestructiveActionModal } from "@sableui/react"
+
+<DestructiveActionModal open={open} onOpenChange={setOpen} title='Delete post?' description='This permanently removes the post. This cannot be undone.' onConfirm={handleDelete} />
+```
+
+### Async confirm (awaited spinner)
+
+```tsx
+import { DestructiveActionModal } from "@sableui/react"
+
+<DestructiveActionModal open={open} onOpenChange={setOpen} title='Block user?' description='They can no longer interact with you.' confirmLabel='Block' confirmingLabel='Blocking…' onConfirm={() => blockUser(id)} />
+```
+
+### Body slot + type-to-confirm
+
+```tsx
+import { DestructiveActionModal, Note } from "@sableui/react"
+
+<DestructiveActionModal open={open} onOpenChange={setOpen} title='Delete this post?' confirmText='gold rush' confirmLabel='Delete forever' onConfirm={handleDelete}><Note tone='warning'>Collectors who minted this edition keep their copies.</Note></DestructiveActionModal>
+```