@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/dialog.md

@@ -0,0 +1,127 @@
+# Dialog
+
+**Status:** stable
+
+Modal surface over Base UI Dialog (focus trap, scroll lock, Esc/outside dismissal). Centered on desktop; max-width 500px. size="fullscreen" is the full-bleed media viewer (image, video, Carousel) over a near-opaque scrim.
+
+**Keywords:** dialog, modal, overlay, confirmation, alert, form, focus trap, sheet, lightbox, fullscreen, image viewer, media overlay, gallery
+
+## Usage
+
+Use Dialog for focused decisions, short modal forms, confirmations, and content that temporarily blocks the underlying page. Prefer Sheet for side-panel workflows, Popover for lightweight anchored content, and inline sections for content that should remain part of the page.
+
+### Best practices
+
+- Do: Always include DialogTitle and usually DialogDescription so the modal has an accessible name and context.
+- Do: Keep the footer actions explicit: a safe escape path plus the primary or destructive action.
+- Do: Use showCloseButton for dismissible informational dialogs; keep destructive confirmations action-led.
+- Do: In a destructive confirmation, state the consequence in DialogDescription ("This is permanent.") and reserve the destructive button variant for actions that cannot be undone.
+- Do: Use size="fullscreen" when an image, video, or gallery needs a larger view than the layout can give it. Give the popup an accessible name (aria-label on DialogContent, or a visually hidden DialogTitle) and alt text on the media.
+- Do: Use the AlertDialog family for a confirmation that must be answered (discard changes, leave without saving). It looks identical but is role="alertdialog" and a backdrop click does not dismiss it — only Cancel, Esc, or the action. For irreversible deletes, use DestructiveActionModal, which is built on it.
+- Don't: Put large multipage workflows in a centered dialog. Use Sheet or a page route when the task needs space.
+- Don't: Use size="fullscreen" for forms, confirmations, or anything that isn't media. A dialog that happens to need room is a Sheet or a page; the fullscreen affordances (dark scrim, corner close, centred content) all assume something to look at.
+- Don't: Hide the close button at size="fullscreen" without another visible way out. A full-bleed viewer that only Esc dismisses is a dead end for anyone who doesn't know the key.
+- Don't: Open a dialog for passive status updates. Use Toast, Banner, or InlineStatus instead.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Trigger | no | The element that opens the dialog when using the composed trigger pattern. |
+| Overlay | yes | The dimming backdrop behind the modal content. |
+| Content | yes | The modal surface that receives focus trap, labelled-by, and described-by wiring. |
+| Header | yes | Title and optional description that explain the decision or task. |
+| Footer | no | Action row for cancel, confirm, submit, or destructive choices. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| DialogContent | Base UI Popup props + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. |
+| DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/50 by default, near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
+| DialogTrigger | Base UI Dialog.Trigger props (render) | Element that opens the dialog. Compose via render prop. |
+| DialogClose | Base UI Dialog.Close props (render) | Element that dismisses the dialog. Compose via render prop. |
+| DialogHeader | ComponentProps<"div"> | Top section holding DialogTitle/DialogDescription. |
+| DialogTitle | Base UI Dialog.Title props + className | The dialog's accessible name — wires aria-labelledby on the popup. |
+| DialogDescription | Base UI Dialog.Description props + className | Muted supporting line; wires aria-describedby. |
+| DialogFooter | ComponentProps<"div"> | Bottom action row (right-aligned buttons). |
+| AlertDialog (Root) | Base UI AlertDialog.Root props (open, defaultOpen, onOpenChange) | Root for a confirmation that needs an answer. Always modal; the popup is role="alertdialog" and a click outside does not dismiss — only an AlertDialogClose, an action that sets open to false, or Esc. |
+| AlertDialogTrigger | Base UI AlertDialog.Trigger props (render) | Opens the alert dialog. |
+| AlertDialogContent / AlertDialogOverlay / AlertDialogTitle / AlertDialogDescription / AlertDialogHeader / AlertDialogFooter / AlertDialogClose | Same props as the matching Dialog part | The Dialog parts under AlertDialog names — Base UI shares the popup, backdrop, title, description and close parts between the two, so the surface is identical. Pass initialFocus to AlertDialogContent (a ref to the Cancel button) to open focus on the safe action. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Dialog (Root) | Base UI Dialog.Root props (open, defaultOpen, onOpenChange, modal) | — | Controls open state. Uncontrolled by default. |
+
+## Variants
+
+- **size**: default, fullscreen
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `muted-foreground`, `overlay`, `overlay-foreground`, `accent`, `accent-foreground`, `ring`
+
+## Motion
+
+- **arrival** · DialogOverlay · `motion-fade` — The scrim is what tells the reader the page behind is no longer live. Appearing at full opacity in one frame reads as a page navigation — the surrounding context vanishes instead of receding.
+- **arrival** · DialogContent · `motion-pop` — The panel scales up as the scrim darkens, so the two read as one event. Overlay and panel arriving on separate timings is the most common way a modal feels cheap.
+- **response** · DialogClose · `motion-interactive` — The close affordance is a small icon in a corner and is often the only control a reader looks for. Its hover state has to be findable, not just present.
+- **transition** · DialogContent · `motion-pop` — Exit runs the same recipe in reverse so dismissal is legibly the inverse of opening. A modal that fades out having scaled in leaves the reader unsure whether it closed or navigated away.
+- **activity** · DialogContent · _no motion_ — The dialog is a container. Work happening inside it is the content's to report — a dialog-level indicator would claim the whole surface is busy when usually one field is.
+
+## Accessibility
+
+- Base UI provides focus trapping, scroll lock, aria-modal, and labelled-by wiring (DialogTitle).
+- Content taller than the viewport scrolls inside the dialog (thin scrollbar, contained overscroll) rather than overflowing off screen — the page behind is scroll-locked, so anything past the edge would be unreachable.
+- Esc and click-outside dismiss by default. AlertDialog keeps Esc but ignores click-outside, and its popup is role="alertdialog".
+- Animate via data-[starting-style]/data-[ending-style] attributes.
+- size="fullscreen" has no title chrome, so name the popup yourself: aria-label on DialogContent (or a visually hidden DialogTitle), plus alt text on the media — the zoomed image is a separate image to assistive technology. Its built-in close button carries aria-label="Close" and clears the safe-area insets (notch, home indicator).
+
+## Related
+
+- Components: Sheet, Popover, Toast, Button, Form, Note, Carousel, Video
+- Patterns: SettingsPage, AuthPage
+
+## Examples
+
+### Fullscreen media
+
+```tsx
+import { Button, Dialog, DialogContent, DialogTrigger } from "@sableui/react"
+
+<Dialog><DialogTrigger render={<Button variant="secondary">View full size</Button>} /><DialogContent size="fullscreen" aria-label="Studio, 2026"><img src={url} alt="Studio, 2026" className="max-h-full max-w-full object-contain p-8" /></DialogContent></Dialog>
+```
+
+### Fullscreen gallery
+
+```tsx
+import { Button, Carousel, Dialog, DialogContent, DialogTrigger } from "@sableui/react"
+
+<Dialog><DialogTrigger render={<Button>Open gallery</Button>} /><DialogContent size="fullscreen" aria-label="Gallery"><Carousel loop dots counter label="Gallery" className="w-full max-w-4xl px-8">{images.map((src) => <img key={src} src={src} alt="" className="size-full object-contain" />)}</Carousel></DialogContent></Dialog>
+```
+
+### Basic
+
+```tsx
+import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from "@sableui/react"
+
+<Dialog><DialogTrigger render={<Button>Open</Button>} /><DialogContent><DialogHeader><DialogTitle>Edition details</DialogTitle><DialogDescription>A limited run of 100, stored permanently on Arweave.</DialogDescription></DialogHeader><DialogFooter><DialogClose render={<Button variant="secondary">Close</Button>} /><DialogClose render={<Button>Collect</Button>} /></DialogFooter></DialogContent></Dialog>
+```
+
+### Settings form
+
+```tsx
+import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, Field, Form, Input } from "@sableui/react"
+
+<Dialog><DialogTrigger render={<Button variant="secondary">Rename collection</Button>} /><DialogContent showCloseButton><DialogHeader><DialogTitle>Rename collection</DialogTitle><DialogDescription>Update the display name shown to collectors.</DialogDescription></DialogHeader><Form><Field label="Collection name"><Input defaultValue="Midnight Archive" /></Field><DialogFooter><DialogClose render={<Button variant="secondary">Cancel</Button>} /><Button type="submit">Save changes</Button></DialogFooter></Form></DialogContent></Dialog>
+```
+
+### Destructive confirmation
+
+```tsx
+import { AlertDialog, AlertDialogClose, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, AlertDialogTrigger, Button } from "@sableui/react"
+
+<AlertDialog><AlertDialogTrigger render={<Button variant="destructive">Delete edition</Button>} /><AlertDialogContent><AlertDialogHeader><AlertDialogTitle>Delete edition?</AlertDialogTitle><AlertDialogDescription>This removes the edition and cannot be undone.</AlertDialogDescription></AlertDialogHeader><AlertDialogFooter><AlertDialogClose render={<Button variant="secondary">Cancel</Button>} /><Button variant="destructive" onClick={deleteEdition}>Delete edition</Button></AlertDialogFooter></AlertDialogContent></AlertDialog>
+```

package/llms/components/dots-menu.md

@@ -0,0 +1,64 @@
+# DotsMenu
+
+**Status:** stable
+
+An overflow ellipsis icon button that opens a Menu. Composes our Menu + Button + Icon — pass MenuItems as children and it wires the ghost icon trigger, accessible label, and portal-rendered content. All keyboard, focus, and dismissal behavior comes through Menu.
+
+**Keywords:** dots menu, more actions, overflow, kebab
+
+## Usage
+
+Use DotsMenu for compact overflow actions when the primary action is already visible elsewhere.
+
+### Best practices
+
+- Do: Use it for secondary commands that belong to a row, card, or toolbar item.
+- Do: Keep labels explicit so the icon-only trigger does not obscure the command meaning.
+- Don't: Do not hide the most important or most frequent action inside DotsMenu.
+- Don't: Do not use it as the only affordance on a touch surface. It is revealed on hover in most layouts, and hover does not exist on touch — pair it with a visible action or make it always-visible there.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| children | ReactNode | — | The menu rows — MenuItem / MenuSeparator / MenuGroup, etc. Rendered inside MenuContent. |
+| align | 'start' \| 'center' \| 'end' | end | Alignment of the popup along its side. Overflow menus typically right-align under the trigger; 'start' anchors the popup's left edge to the trigger instead. |
+| label | string | More actions | Accessible label (aria-label) for the icon-only trigger button. |
+| icon | string | ellipsis | Semantic icon name rendered in the trigger. |
+| size | 'icon' \| 'icon-sm' \| 'icon-xs' | icon | The trigger's rung on the icon-button ladder. 'icon' for a card or page header; 'icon-sm' or 'icon-xs' in a list row or dense toolbar, so the trigger does not set the row height. |
+
+## Variants
+
+- **size**: icon, icon-sm, icon-xs
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `accent`, `accent-foreground`, `muted-foreground`
+
+## Accessibility
+
+- The icon-only trigger is labeled via aria-label (label prop, default 'More actions').
+- Menu provides role=menu/menuitem, roving tabindex, arrow-key navigation, and typeahead via Base UI.
+- Esc and outside-press dismiss; focus returns to the trigger on close.
+
+## Related
+
+- Components: Menu, ContextMenu
+
+## Examples
+
+### Basic
+
+```tsx
+import { DotsMenu, MenuItem, MenuSeparator } from "@sableui/react"
+
+<DotsMenu label="Post actions"><MenuItem>Edit</MenuItem><MenuItem>Share</MenuItem><MenuSeparator /><MenuItem variant="destructive">Delete</MenuItem></DotsMenu>
+```
+
+### With leading icons
+
+```tsx
+import { DotsMenu, Icon, MenuItem, MenuSeparator } from "@sableui/react"
+
+<DotsMenu><MenuItem><Icon name="check" className="text-sm" />Mark as read</MenuItem><MenuSeparator /><MenuItem variant="destructive"><Icon name="xmark" className="text-sm" />Delete</MenuItem></DotsMenu>
+```

package/llms/components/empty-state.md

@@ -0,0 +1,113 @@
+# EmptyState
+
+**Status:** stable
+
+The centered empty / error block: optional icon disc or error code, title, description and an action. tone="destructive" makes it an announced error, size="lg" a page-level state, surface="card" a self-contained card.
+
+**Keywords:** empty, zero state, blank slate, no results, placeholder, onboarding, no data
+
+## Usage
+
+Use EmptyState when a content area has no items, no search results, or no first-time setup yet. The title should name the empty condition and the description/action should give the user a next step.
+
+### Best practices
+
+- Do: Explain what is empty in plain language, such as "No posts yet" or "No matching collectors".
+- Do: Offer one next step when the user can recover, create, clear filters, or start setup.
+- Do: Keep the icon decorative and make the title carry the meaning.
+- Do: For a search or filter result, name the query back to the user and offer the way out, such as "No results for 'quarterly'" with a Clear filters action. An empty result that does not say what was searched leaves the user unsure whether the query or the data was wrong.
+- Don't: Use generic copy like "No data"; it gives users and agents no useful path forward.
+- Don't: Park anything the user needs permanently here, such as setup instructions, billing notices, or keyboard shortcuts. An empty state is the one surface guaranteed to disappear the moment content exists, so information that matters after the first item is lost exactly when the user has learned enough to want it.
+- Don't: Use it for a field's validation error — that is Field error messaging. Reserve tone="destructive" for a view or block that failed to load.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Icon | no | A decorative cue that reinforces the empty condition. |
+| Title | yes | The short message naming what is empty. |
+| Description | no | Supporting copy that explains why the state exists or what to try next. |
+| Action | no | One clear button or link that moves the user forward. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| icon | ReactNode | — | Optional leading glyph — pass an `<Icon />`. Rendered in a soft muted disc. |
+| title | ReactNode | — | The headline. Short and direct. |
+| description | ReactNode | — | Optional supporting line beneath the title. |
+| action | ReactNode | — | Optional action below the copy — typically a `<Button />`. |
+| code | ReactNode | — | A large figure above the title, such as an error code (404). |
+| tone | "neutral" \| "destructive" | "neutral" | destructive is an error state: a destructive icon disc (a warning by default) and role="alert" so it is announced. |
+| size | "md" \| "lg" | "md" | lg is page-level: the title is an h2 and the block takes more room. md sits in a panel, list or card. |
+| surface | "none" \| "card" | "none" | card draws it as a Card, for an error or empty block standing on its own in a page. |
+
+## Variants
+
+- **tone**: neutral, destructive
+- **size**: md, lg
+- **surface**: none, card
+
+## Tokens used
+
+`muted`, `muted-foreground`, `foreground`, `destructive`
+
+## Accessibility
+
+- Decorative icon discs should not carry meaning the title doesn't already convey.
+- Pair with an actionable next step so the zero-state is a path forward, not a dead end.
+
+## Related
+
+- Components: Button, Icon, Card, Banner, DataTable
+- Patterns: FeedPage, ListDetailPage, DashboardPage
+
+## Examples
+
+### With icon and action
+
+```tsx
+import { Button, EmptyState, Icon } from "@sableui/react"
+
+<EmptyState icon={<Icon name="info" />} title="No posts yet" description="Create your first." action={<Button>New post</Button>} />
+```
+
+### No search results
+
+```tsx
+import { Button, EmptyState, Icon } from "@sableui/react"
+
+<EmptyState icon={<Icon name="search" />} title="No matching posts" description="Try a different keyword or clear your filters." action={<Button variant="secondary">Clear filters</Button>} />
+```
+
+### First-run setup
+
+```tsx
+import { Button, EmptyState, Icon, Row } from "@sableui/react"
+
+<EmptyState surface="card" icon={<Icon name="sparkles" />} title="Start your collection" description="Create a first edition, import an existing drop, or invite collaborators." action={<Row gap={1}><Button>Create edition</Button><Button variant="ghost">Import</Button></Row>} />
+```
+
+### Page-level error
+
+```tsx
+import { Button, EmptyState } from "@sableui/react"
+
+<EmptyState tone="destructive" size="lg" code="404" title="Page not found" description="The page you are looking for has moved or never existed." action={<Button>Go home</Button>} />
+```
+
+### Error card
+
+```tsx
+import { Button, EmptyState } from "@sableui/react"
+
+<EmptyState tone="destructive" surface="card" title="Could not load this edition" description="Check your connection and try again." action={<Button variant="secondary">Retry</Button>} />
+```
+
+### Empty table body
+
+```tsx
+import { DataTable, EmptyState } from "@sableui/react"
+
+<DataTable data={[]} columns={[{ key: "name", header: "Collector" }, { key: "status", header: "Status" }]} empty={<EmptyState title="No collectors yet" description="Collectors appear here after the first mint." />} />
+```

package/llms/components/entity.md

@@ -0,0 +1,67 @@
+# Entity
+
+**Status:** stable
+
+A list-row record: leading visual + title/subtitle column + trailing action, with truncating text. Presentational by default (no hover); `interactive` rows gain the hover highlight, focus ring, and keyboard activation. Compact/comfortable density.
+
+**Keywords:** entity, identity, object, avatar row
+
+## Usage
+
+Use Entity to show a compact identity block for a person, organization, file, project, or other object.
+
+### Best practices
+
+- Do: Use a clear title and one or two useful metadata lines.
+- Do: Pair with Avatar or Badge (dot for a status) when identity needs state or type.
+- Do: For a list, stack Entity rows directly in a column; each row owns its padding. For a list in a card, put the rows in CardList, which insets them to the card's own padding and divides them, so the rows line up with the card's header instead of being tuned by hand with px-* classes.
+- Don't: Do not use Entity for long descriptions, editable fields, or full card content.
+- Don't: Do not make the whole row a link when it also carries a trailing action. Nesting an interactive element inside a link is invalid, and the action becomes unreachable by keyboard.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| leading | ReactNode | — | Leading visual — typically an Avatar or an Icon. |
+| title | ReactNode | — | Primary line (text-title-sm, truncated). Required. |
+| subtitle | ReactNode | — | Secondary line (text-body-sm muted, truncated). |
+| action | ReactNode | — | Trailing slot — typically a ghost icon Button or a StatusDot. |
+| interactive | boolean | false | Make the whole row a target: the leading visual and text become a native <button> whose hit area stretches over the row (focus ring, Enter/Space). The action stays outside it. Requires onSelect. |
+| onSelect | () => void | — | Activation handler for an interactive row (fired on click and Enter/Space). Required when interactive. |
+| density | "compact" \| "comfortable" | "compact" | Row padding: compact (12px × 10px, the default) or comfortable (16px × 12px), on the spacing scale. The insets read --entity-px / --entity-py first, which CardList sets from the card's own padding so rows in a card line up with its header. |
+
+## Variants
+
+- **density**: compact, comfortable
+
+## Tokens used
+
+`muted`, `foreground`, `muted-foreground`, `ring`
+
+## Accessibility
+
+- Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.
+- interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row — native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.
+- Give any interactive action an accessible label (e.g. aria-label on a ghost icon Button).
+
+## Related
+
+- Components: Avatar, Badge, Description
+
+## Examples
+
+### Person row
+
+```tsx
+import { Avatar, Button, Entity, Icon } from "@sableui/react"
+
+<Entity leading={<Avatar fallback="AM" />} title="Alex Morgan" subtitle="@alex" action={<Button variant="ghost" size="icon" aria-label="More"><Icon name="ellipsis" /></Button>} />
+```
+
+### Interactive (selectable) row
+
+```tsx
+import { Avatar, Entity } from "@sableui/react"
+
+<Entity interactive onSelect={() => selectUser(user)} leading={<Avatar fallback="AM" />} title="Alex Morgan" subtitle="@alex" />
+```

package/llms/components/feedback.md

@@ -0,0 +1,63 @@
+# Feedback
+
+**Status:** stable
+
+A compact feedback popover. Composes Popover + Textarea + Button + Toggle into a rating row plus a message field; submitting reports the rating + message and closes the popover.
+
+**Keywords:** feedback, sentiment, rating, prompt
+
+## Usage
+
+Use Feedback to collect lightweight sentiment, usefulness, or quality signals from users.
+
+### Best practices
+
+- Do: Ask for feedback at a moment when the user has enough context to answer.
+- Do: Keep the prompt short and optional unless feedback is required by the workflow.
+- Don't: Do not use Feedback for errors, alerts, or required support forms.
+- Don't: Do not require the message field. Most feedback is a rating with no comment, and forcing prose is how a feedback control stops being used.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | string | "Feedback" | Trigger button text. |
+| heading | string | "Send feedback" | Heading shown above the rating row. |
+| placeholder | string | "What can we improve?" | Placeholder for the message field. |
+| submitLabel | string | "Send" | Submit button text. |
+| ratings | FeedbackRating[] | 🙁 / 😐 / 🙂 | The rating options shown as a row of toggles. Each is { value, label }. |
+| onSubmit | (data: { rating?: string; message: string }) => void | — | Called with the selected rating + message when the form is submitted. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `input`, `card`, `foreground`, `muted-foreground`, `accent`, `accent-foreground`, `ring`
+
+## Accessibility
+
+- Trigger opens the popover on press; Base UI manages focus into the form and restores it to the trigger on close.
+- The rating row is a Base UI ToggleGroup with arrow-key roving focus; each toggle carries an aria-label.
+- The form is named by its heading (aria-labelledby), so it is announced as "Send feedback" rather than an unnamed form.
+- The message field carries an aria-label matching its placeholder.
+- Submit is disabled until there is a rating or a non-whitespace message. Either alone is a complete answer.
+
+## Related
+
+- Components: Toast, Banner, Form
+
+## Examples
+
+### Basic
+
+```tsx
+import { Feedback } from "@sableui/react"
+
+<Feedback onSubmit={({ rating, message }) => console.log(rating, message)} />
+```
+
+### Custom labels
+
+```tsx
+import { Feedback } from "@sableui/react"
+
+<Feedback label="Tell us" submitLabel="Send it" placeholder="Describe the issue…" />
+```

package/llms/components/fieldset.md

@@ -0,0 +1,106 @@
+# Fieldset
+
+**Status:** stable
+
+Form section panel (Card-like bordered surface) over Base UI Fieldset, with Legend/Description/Content/Footer parts.
+
+**Keywords:** fieldset, form group, legend, fields
+
+## Usage
+
+Use Fieldset to group related controls under a shared label or explanation.
+
+### Best practices
+
+- Do: Use it for grouped form sections such as contact details, preferences, or permissions.
+- Do: Keep the legend meaningful so assistive tech and agents understand the group purpose.
+- Don't: Do not use Fieldset as a generic spacing wrapper outside forms.
+- Don't: Do not use a Legend that is really a heading. A legend names the group's question for assistive technology; using it as a section title puts a question mark where the outline should be.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Fieldset | yes | The bordered group: a native <fieldset> whose disabled state reaches every control inside it. |
+| Legend | yes | FieldsetLegend: the question the group's controls answer, announced before each of them. |
+| Description | no | FieldsetDescription: muted copy under the legend. |
+| Content | yes | FieldsetContent: the stacked body, one Field per control. |
+| Footer | no | FieldsetFooter: the group's actions on a muted wash. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| FieldsetLegend | ComponentPropsWithRef<typeof Fieldset.Legend> | The group's name — the question its controls answer. Base UI renders it as a <div> wired to the <fieldset> through aria-labelledby, so a screen reader announces it before each control in the group. This is the whole reason to reach for Fieldset. |
+| FieldsetDescription | ComponentPropsWithRef<"p"> | Muted supporting copy under the legend. |
+| FieldsetContent | ComponentPropsWithRef<"div"> | The stacked body holding one Field per control. |
+| FieldsetFooter | ComponentPropsWithRef<"div"> | Optional right-aligned action bar on a muted wash. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| disabled | boolean | — | Disables the whole group. Renders <fieldset disabled> (native control disabling) and surfaces data-[disabled] for dimming. |
+| render | ReactElement \| function | — | Base UI render prop to replace or compose the underlying element. |
+| className | string | — | Merged onto each part via cn() for one-off overrides. |
+
+## Tokens used
+
+`card`, `card-foreground`, `border`, `foreground`, `muted-foreground`, `muted`
+
+## Accessibility
+
+- Base.Root renders a native <fieldset>; Base.Legend renders an auto-associated label, so screen readers announce the group name.
+- disabled propagates as native <fieldset disabled>, disabling all contained controls.
+- Wrap each control inside FieldsetContent in a Field, which wires its own label, description and error to the control.
+
+## Related
+
+- Components: Form, Label, Description
+
+## Examples
+
+### A grouped question
+
+```tsx
+import { Button, Checkbox, Field, Fieldset, FieldsetContent, FieldsetDescription, FieldsetFooter, FieldsetLegend } from "@sableui/react"
+
+<Fieldset>
+	<FieldsetLegend>Notify me about</FieldsetLegend>
+	<FieldsetDescription>Pick what reaches your inbox.</FieldsetDescription>
+	<FieldsetContent>
+		<Field label="Mentions" orientation="horizontal"><Checkbox defaultChecked /></Field>
+		<Field label="Replies" orientation="horizontal"><Checkbox /></Field>
+		<Field label="Direct messages" orientation="horizontal"><Checkbox /></Field>
+	</FieldsetContent>
+	<FieldsetFooter>
+		<Button>Save preferences</Button>
+	</FieldsetFooter>
+</Fieldset>
+```
+
+### Why a fieldset, and when it is wrong
+
+```tsx
+import { Field, Fieldset, FieldsetContent, FieldsetLegend, Radio, RadioGroup } from "@sableui/react"
+
+// Fieldset groups inputs that are ONE question with multiple parts, and gives
+// the group a single accessible name — which is the part you cannot do with a
+// div and a heading.
+
+<Fieldset>
+  <FieldsetLegend>Digest frequency</FieldsetLegend>
+  <FieldsetContent>
+    <RadioGroup defaultValue="weekly">
+      <Field label="Daily" orientation="horizontal"><Radio value="daily" /></Field>
+      <Field label="Weekly" orientation="horizontal"><Radio value="weekly" /></Field>
+    </RadioGroup>
+  </FieldsetContent>
+</Fieldset>
+
+// ✓ Required for radio groups: without a fieldset the options have no shared
+//   name, so a screen reader announces "Weekly, radio" with no question.
+// ✗ Not for visual grouping of unrelated fields. Use PanelSection on a panel or
+//   a Card section on a page; a legend that is really a heading lies to
+//   assistive technology about the form's structure.
+```

package/llms/components/file-dropzone.md

@@ -0,0 +1,103 @@
+# FileDropzone
+
+**Status:** stable
+
+Drag-and-drop target and file picker in one keyboard-operable button. Checks accept, maxSize and maxFiles on every selection, announces each rejection with how to fix it, and hands accepted files to you to list as Attachments.
+
+**Keywords:** file upload, dropzone, drag and drop, file picker, upload, attach file, file input, import
+
+## Usage
+
+Use FileDropzone where adding files is the main job of a section — an upload step, an import screen, a document request. It gives the drag gesture a visible target and the same action a button for everyone who does not drag. It holds no list: render accepted files as Attachments beneath it, where progress, retry and remove belong.
+
+### Best practices
+
+- Do: State the constraints in `description` ("PNG or PDF, up to 10 MB") and give `acceptLabel` the same words, so a rejection repeats the rule the user already read.
+- Do: Pair it with a list of Attachment rows that you own. Once files are added, switch to `size="sm"` so the target stays available without pushing the list below the fold.
+- Do: Cap the total by passing `maxFiles={limit - files.length}`; the dropzone only sees one selection at a time. When none remain, set `disabled` and say why in `description` ("Remove one to add another").
+- Don't: Do not use it for an incidental attach action inside a composer or a toolbar. A paperclip Button that opens the picker is the right weight there; ChatComposer already has one.
+- Don't: Do not rely on `accept` alone to protect the server. The dropzone's checks are for the user's benefit; validate type and size again where the file is received.
+- Don't: Do not silently drop rejected files. The zone announces each one, but if you also discard files later (a server-side limit), say so on the Attachment with `status="error"` and a fix.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Zone | yes | A full-width button with a dashed border. Click, Enter or Space opens the picker; it is also the drop target. |
+| Icon | no | A decorative mark that lifts while a file is dragged over the zone. |
+| Label and description | yes | The call to action and the constraints. Together they form the button's accessible name. |
+| Status | yes | A role=status region, present from the first render, that lists each rejected file and how to fix it. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| accept | string | — | Native accept syntax — `.pdf`, `application/pdf`, `image/*`, comma-separated. Enforced on drop and on pick. |
+| maxSize | number | — | Largest accepted file, in bytes. |
+| multiple | boolean | false | Accept more than one file per selection. |
+| maxFiles | number | — | Most files accepted from one selection when `multiple`. Pass the remaining capacity to cap a total. |
+| onFilesAccepted | (files: File[]) => void | — | Files that passed every check, in selection order. |
+| onFilesRejected | (rejections: FileRejection[]) => void | — | Files that failed, each with `code` (file-invalid-type, file-too-large, too-many-files) and the announced `message`. |
+| label | ReactNode | "Drop a file here or browse" | The visible call to action. Pluralised automatically when `multiple`. |
+| description | ReactNode | — | The constraints in words, shown under the label. |
+| acceptLabel | string | — | How the accepted types complete "Use … instead" in an error ("PNG or PDF", "an image or PDF"). Without it a type error can only say "Choose a different file". |
+| formatError | (rejection) => string | — | Replace the rejection copy, e.g. to localize it. |
+| icon | string | "arrow-up" | Semantic icon name. |
+| size | "md" \| "sm" | "md" | `md` is the empty-section target; `sm` is a single-row strip above an existing list. |
+| disabled / required / id / aria-invalid | — | — | Standard form-control props. `id` lands on the button, so `<Field>` labels it; `aria-invalid` draws the destructive border. |
+
+## Variants
+
+- **size**: md, sm
+
+## Tokens used
+
+`card`, `foreground`, `muted`, `muted-foreground`, `border-strong`, `primary`, `primary-foreground`, `accent`, `accent-foreground`, `ring`, `destructive`
+
+## Motion
+
+- **arrival** · Zone · _no motion_ — The zone is the section's content, present from the start. An entrance would only delay the drop target someone is already dragging toward.
+- **response** · Zone · `motion-interactive` — Hover strengthens the border to primary, which confirms the whole dashed area — not just the word "browse" — is the click target.
+- **transition** · Icon · `motion-interactive` — When a file crosses into the zone the icon fills and lifts and the surface tints. That is the only signal that releasing here will work; without it users drop on the page and the browser opens the file instead.
+- **activity** · Zone · _no motion_ — The zone hands files off immediately and never uploads. Transfer progress belongs on each Attachment, where it can be per-file and retryable.
+
+## Accessibility
+
+- The zone is a native button: Enter or Space opens the system picker, so dragging is never the only way in.
+- Rejections render into a role=status region that exists from the first render, and the button's aria-describedby points at it while it has content, so the reason is still read when focus returns.
+- Every error names the file and says how to fix it ("Choose a smaller file"), rather than only what failed.
+- The underlying file input is visually hidden and removed from the tab order; the button is the single focus stop.
+
+## Related
+
+- Components: Attachment, Input, Button, Progress
+
+## Examples
+
+### Images and PDFs
+
+```tsx
+import { FileDropzone } from "@sableui/react"
+
+<FileDropzone accept="image/*,.pdf" acceptLabel="an image or PDF" maxSize={10 * 1024 * 1024} multiple description="Images or PDFs, up to 10 MB each" onFilesAccepted={(files) => console.log(files)} />
+```
+
+### With an Attachment list
+
+```tsx
+import { Attachment, FileDropzone } from "@sableui/react"
+
+<div className="flex flex-col gap-3">
+	<FileDropzone size="sm" multiple description="Up to 5 files" onFilesAccepted={(files) => console.log(files)} />
+	<Attachment name="contract.pdf" meta="2.4 MB · PDF" />
+	<Attachment name="site-photo.jpg" meta="Uploading…" status="uploading" progress={42} />
+</div>
+```
+
+### In a field
+
+```tsx
+import { Field, FileDropzone } from "@sableui/react"
+
+<Field label="Proof of address" description="A bill or statement from the last 3 months."><FileDropzone accept=".pdf" acceptLabel="a PDF" maxSize={5 * 1024 * 1024} description="PDF, up to 5 MB" /></Field>
+```