@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/dialog.md

@@ -0,0 +1,252 @@
+<!-- index: ./index.md -->
+# dialog
+
+`data-ui="dialog"` · Modal dialog and alert dialog.
+
+## Import
+
+```tsx
+import { Dialog, DialogBody, DialogClose, DialogContent, DialogDefaultsProvider, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@slotted/react';
+```
+
+```tsx
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogIcon, DialogBody, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { TextField } from '@slotted/react/text-field';
+import { Text } from '@slotted/react/typography';
+
+export default function DialogBasic() {
+  const [open, setOpen] = useState(false);
+  const [email, setEmail] = useState('ap@northwindtraders.com');
+  const [draft, setDraft] = useState(email);
+
+  return (
+    <Inline align="center" gap={3}>
+      <Text size="sm">{email}</Text>
+      <Dialog
+        open={open}
+        onOpenChange={(next) => {
+          if (next) setDraft(email);
+          setOpen(next);
+        }}
+      >
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} size="sm" tone="secondary" variant="outline">
+              Edit billing email
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Billing email</DialogTitle>
+            <DialogDescription>
+              Invoices and payment receipts for Northwind Traders go to this address.
+            </DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Field>
+              <FieldLabel>Email</FieldLabel>
+              <TextField type="email" value={draft} onValueChange={setDraft} />
+            </Field>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => {
+                setEmail(draft);
+                setOpen(false);
+              }}
+            >
+              Save
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </Inline>
+  );
+}
+```
+
+## Anatomy
+
+### dialog
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, in a portal | yes |
+| `trigger` | button, or the element render returns | no |
+| `backdrop` | div | yes |
+| `viewport` | div | yes |
+| `content` | div | yes |
+| `header` | header, or the element render returns | no |
+| `title` | h2, or the element render returns | no |
+| `description` | p, or the element render returns | no |
+| `body` | div, or the element render returns | no |
+| `footer` | footer, or the element render returns | no |
+| `close` | button | no |
+| `fullscreen` | button | no |
+
+### alertDialog
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, in a portal | yes |
+| `trigger` | button, or the element render returns | no |
+| `backdrop` | div | yes |
+| `viewport` | div | yes |
+| `content` | div | yes |
+| `header` | header, or the element render returns | no |
+| `title` | h2, or the element render returns | no |
+| `description` | p, or the element render returns | yes |
+| `body` | div, or the element render returns | no |
+| `footer` | footer, or the element render returns | no |
+| `icon` | span | no |
+| `cancel` | button | yes |
+| `action` | button | yes |
+
+## Props
+
+### dialog
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | Dialog, AlertDialog | Whether the dialog is open. Passing it makes the state controlled: the dialog asks through onOpenChange and waits for the new value. |
+| `defaultOpen` | `boolean` | — | Dialog, AlertDialog | Whether an uncontrolled dialog starts open. Read once. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | md | Dialog, DialogDefaultsProvider | The maximum width of the panel: 24rem, 32rem, 42rem, 56rem, or the whole layer less its padding. For another width, set --slotted-dialog-measure. |
+| `placement` | `'center' \| 'top'` | center | Dialog, AlertDialog, DialogDefaultsProvider | Where the panel sits in the layer. Use top for content that grows while the reader types, so the panel does not move with each new line. |
+| `scroll` | `'content' \| 'viewport'` | content | Dialog, AlertDialog, DialogDefaultsProvider | What scrolls when the content is long. content keeps the panel inside the layer and scrolls the body, so the actions stay on screen; viewport lets the panel grow and scrolls the layer. With content, the layer still scrolls when the header and footer alone are taller than it. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | Dialog, AlertDialog, DialogDefaultsProvider | When the layer is in the document. active renders it while open and removes it after the closing animation, lazy renders it on the first open and keeps it, eager renders it from the start and hides it with content-visibility and inert while closed. |
+| `escape` | `'close' \| 'none'` | close | Dialog, AlertDialog, DialogDefaultsProvider | Whether Escape asks the dialog to close. Escape reaches the topmost dialog only. |
+| `loading` | `boolean` | false | Dialog, AlertDialog | Marks the body with aria-busy and gives it a minimum height while the content is on its way. The header, the close button and Escape stay available. |
+| `messages` | `Partial<DialogMessages>` | — | Dialog, AlertDialog | Replaces words of the language in force, key by key: the accessible names of the close and full-screen buttons (close, fullScreen). An aria-label on DialogClose takes precedence. |
+| `initialFocus` | `'first' \| 'container' \| 'cancel' \| RefObject \| false` | first | Dialog | Where focus goes when the dialog opens: the first focusable element, the panel itself (container), the cancel part, the element of a ref, or nowhere (false). Use container for content that is read before it is used, such as a list or a table. |
+| `finalFocus` | `RefObject \| false` | — | Dialog, AlertDialog | Where focus goes when the dialog closes. Unset, focus returns to the element that had it when the dialog opened, usually the trigger. false leaves focus where it is. |
+| `value` | `string` | — | DialogClose, AlertDialogCancel, AlertDialogAction | The result this button closes the dialog with, read from request.result in onOpenChange. AlertDialogCancel defaults to "cancel" and AlertDialogAction to "confirm". |
+| `modal` | `boolean` | true | Dialog, DialogDefaultsProvider | Whether the page behind is inert, its scroll locked and focus kept inside the panel. false does none of this, paints no scrim, lets the pointer reach the page and writes no aria-modal. |
+| `outsidePress` | `'close' \| 'none'` | close | Dialog, DialogDefaultsProvider | Whether a press outside the panel asks the dialog to close. AlertDialog fixes it at none. |
+| `back` | `'close' \| 'none'` | close | Dialog, DialogDefaultsProvider | Whether the browser’s way back, a back button or a phone’s back gesture, closes a modal dialog instead of leaving the page. Each open modal dialog adds one history entry, and the close request carries the reason back. |
+| `surface` | `'panel' \| 'plain'` | panel | Dialog, DialogDefaultsProvider | Whether Dialog paints the panel. plain removes the background, border, radius, shadow, rows and padding, and keeps the portal, the scrim, focus handling and the dismissal policy, for a panel of your own such as a Card or an image viewer. A plain panel does not keep its footer on screen for a long body. |
+| `fullScreen` | `'never' \| 'narrow' \| 'always'` | narrow | Dialog, DialogDefaultsProvider | When the panel fills the whole layer, without margins or radius. narrow does so while the layer is narrower than 480 pixels, measured with a container query on the layer. |
+| `fullscreenToggle` | `boolean` | false | Dialog | Adds a button to the header that expands the panel to the whole layer and restores it, for content the reader wants more room for. |
+| `fullscreen` | `boolean` | — | Dialog | Whether the panel is expanded by the toggle. Passing it makes the state controlled, with onFullscreenChange. |
+| `defaultFullscreen` | `boolean` | false | Dialog | Whether an uncontrolled panel opens expanded. Read once. |
+| `render` | `(props) => ReactNode` | — | every part | Replaces the element a part renders and passes it every attribute the part writes. Use it to make the trigger, the cancel and the action a Button. |
+| `ref` | `Ref<DialogHandle> on Dialog, Ref<HTMLElement> on every part` | — | Dialog, AlertDialog, every part | On a part, the element. On Dialog and AlertDialog, a handle with open(), close(result), focus() and content, the panel element once it is rendered. |
+| `--slotted-dialog-measure` | `length` | from size | the root part | The maximum width of the panel, for a width the five sizes do not hold, such as a two-column form at 46rem. Set it with a style attribute on one dialog, with a rule for a region, or once in the theme. It takes precedence over size. |
+| `container` | `Element \| null` | — | Dialog, AlertDialog | The element this dialog is rendered into, instead of the shared portal root. To change the portal root for the whole document, call setPortalContainer from @slotted/core/portal. |
+| `useDialog()` | `() => DialogContextValue` | — | inside Dialog or AlertDialog | What the parts read: the open state, the ids, the resolved axes and close(reason, result). It throws outside Dialog and AlertDialog. |
+| `DialogDefaultsProvider` | `{ size, placement, scroll, surface, mount, fullScreen, modal, escape, outsidePress, back }` | — | a subtree | Sets these ten values once for every dialog under it. A value set on one dialog takes precedence. |
+
+### alertDialog
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | — | Dialog, AlertDialog | Whether the dialog is open. Passing it makes the state controlled: the dialog asks through onOpenChange and waits for the new value. |
+| `defaultOpen` | `boolean` | — | Dialog, AlertDialog | Whether an uncontrolled dialog starts open. Read once. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | sm | AlertDialog | The maximum width of the panel. AlertDialog defaults to sm, 24rem. |
+| `placement` | `'center' \| 'top'` | center | Dialog, AlertDialog, DialogDefaultsProvider | Where the panel sits in the layer. Use top for content that grows while the reader types, so the panel does not move with each new line. |
+| `scroll` | `'content' \| 'viewport'` | content | Dialog, AlertDialog, DialogDefaultsProvider | What scrolls when the content is long. content keeps the panel inside the layer and scrolls the body, so the actions stay on screen; viewport lets the panel grow and scrolls the layer. With content, the layer still scrolls when the header and footer alone are taller than it. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | Dialog, AlertDialog, DialogDefaultsProvider | When the layer is in the document. active renders it while open and removes it after the closing animation, lazy renders it on the first open and keeps it, eager renders it from the start and hides it with content-visibility and inert while closed. |
+| `escape` | `'close' \| 'none'` | close | Dialog, AlertDialog, DialogDefaultsProvider | Whether Escape asks the dialog to close. Escape reaches the topmost dialog only. |
+| `loading` | `boolean` | false | Dialog, AlertDialog | Marks the body with aria-busy and gives it a minimum height while the content is on its way. The header, the close button and Escape stay available. |
+| `messages` | `Partial<DialogMessages>` | — | Dialog, AlertDialog | Replaces words of the language in force, key by key: the accessible names of the close and full-screen buttons (close, fullScreen). An aria-label on DialogClose takes precedence. |
+| `initialFocus` | `'first' \| 'container' \| 'cancel' \| RefObject \| false` | cancel | AlertDialog | Where focus goes when the dialog opens. The default, cancel, is the least destructive answer. |
+| `finalFocus` | `RefObject \| false` | — | Dialog, AlertDialog | Where focus goes when the dialog closes. Unset, focus returns to the element that had it when the dialog opened, usually the trigger. false leaves focus where it is. |
+| `value` | `string` | — | DialogClose, AlertDialogCancel, AlertDialogAction | The result this button closes the dialog with, read from request.result in onOpenChange. AlertDialogCancel defaults to "cancel" and AlertDialogAction to "confirm". |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | danger | AlertDialog | The kind of decision. It sets the mark AlertDialogIcon draws and its colour. |
+| `modal` | `boolean` | true | AlertDialog | Fixed: an alert dialog is always modal. |
+| `outsidePress` | `'close' \| 'none'` | none | AlertDialog | Fixed: a press outside never closes an alert dialog. |
+| `back` | `'close' \| 'none'` | close | AlertDialog | Whether the browser’s way back cancels the confirmation, as Escape does. The close request carries the reason back. |
+| `surface` | `'panel' \| 'plain'` | panel | AlertDialog | Whether AlertDialog paints the panel. plain removes the paint and keeps the behaviour. |
+| `fullScreen` | `'never' \| 'narrow' \| 'always'` | never | AlertDialog | When the panel fills the whole layer. AlertDialog keeps its margins at every width by default. |
+| `render` | `(props) => ReactNode` | — | every part | Replaces the element a part renders and passes it every attribute the part writes. Use it to make the trigger, the cancel and the action a Button. |
+| `ref` | `Ref<DialogHandle> on Dialog, Ref<HTMLElement> on every part` | — | Dialog, AlertDialog, every part | On a part, the element. On Dialog and AlertDialog, a handle with open(), close(result), focus() and content, the panel element once it is rendered. |
+| `--slotted-dialog-measure` | `length` | from size | the root part | The maximum width of the panel, for a width the five sizes do not hold, such as a two-column form at 46rem. Set it with a style attribute on one dialog, with a rule for a region, or once in the theme. It takes precedence over size. |
+| `container` | `Element \| null` | — | Dialog, AlertDialog | The element this dialog is rendered into, instead of the shared portal root. To change the portal root for the whole document, call setPortalContainer from @slotted/core/portal. |
+| `useDialog()` | `() => DialogContextValue` | — | inside Dialog or AlertDialog | What the parts read: the open state, the ids, the resolved axes and close(reason, result). It throws outside Dialog and AlertDialog. |
+| `DialogDefaultsProvider` | `{ size, placement, scroll, surface, mount, fullScreen, modal, escape, outsidePress, back }` | — | a subtree | Sets these ten values once for every dialog under it. A value set on one dialog takes precedence. |
+
+## Events
+
+### dialog
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: DialogChangeRequest)` | Before the dialog opens or closes, whatever caused it. The request carries the new value, the previous value, the reason (pointer, keyboard, dismiss, escape, outsidePress, back, submit or programmatic), the result of the close, the originating event, and cancel(), which keeps the dialog as it is. One handler therefore guards the ✕, Escape, a press outside, the way back and the ref handle together. |
+| `onFullscreenChange` | `(fullscreen: boolean, request: DialogFullscreenRequest)` | Before the panel expands to the whole layer or is restored. The request carries the new value, the previous value, the reason (pointer, keyboard or programmatic), the originating event, and cancel(), which keeps the panel as it is. |
+| `onClick, onKeyDown and the other native events, on every part` | `the element’s own event` | Whenever the element fires them. Your handler runs before the dialog’s own, and calling preventDefault() in it cancels the dialog’s behaviour, such as opening on a trigger press or closing on a close press. |
+
+### alertDialog
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `(open: boolean, request: DialogChangeRequest)` | Before the dialog opens or closes, whatever caused it. The request carries the new value, the previous value, the reason (pointer, keyboard, dismiss, escape, outsidePress, back, submit or programmatic), the result of the close, the originating event, and cancel(), which keeps the dialog as it is. One handler therefore guards the ✕, Escape, a press outside, the way back and the ref handle together. |
+| `onFullscreenChange` | `(fullscreen: boolean, request: DialogFullscreenRequest)` | Before the panel expands to the whole layer or is restored. The request carries the new value, the previous value, the reason (pointer, keyboard or programmatic), the originating event, and cancel(), which keeps the panel as it is. |
+| `onClick, onKeyDown and the other native events, on every part` | `the element’s own event` | Whenever the element fires them. Your handler runs before the dialog’s own, and calling preventDefault() in it cancels the dialog’s behaviour, such as opening on a trigger press or closing on a close press. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg`, `xl`, `full` | `md`, `sm` |
+| `placement` | `center`, `top` | `center` |
+| `scroll` | `content`, `viewport` | `content` |
+| `surface` | `panel`, `plain` | `panel` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `fullScreen` | `never`, `narrow`, `always` | `narrow`, `never` |
+| `modal` | `true`, `false` | `true` |
+| `escape` | `close`, `none` | `close` |
+| `outsidePress` | `close`, `none` | `close`, `none` |
+| `back` | `close`, `none` | `close` |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `danger` |
+| `initialFocus` | `first`, `container`, `cancel` | `first`, `cancel` |
+
+## Rules
+
+- Dialog follows the WAI-ARIA dialog (modal) pattern. While a modal dialog is open, Tab and Shift+Tab move through the focusable elements inside it and wrap from the last to the first and back. Escape closes the topmost dialog only; a dialog that refuses the close keeps the Escape from reaching the dialog beneath it.
+- The panel carries role="dialog", aria-labelledby pointing at the title and aria-describedby pointing at the description, each only while that part is rendered. An aria-label of your own on DialogContent replaces aria-labelledby.
+- aria-modal="true" is written only while the dialog is modal. A modal dialog makes everything outside it inert, which removes the page from the accessibility tree and from the pointer, and locks the page scroll. modal={false} does none of this and writes no aria-modal.
+- When the dialog opens, focus moves to its first focusable element, to the element initialFocus names, or to the panel itself with initialFocus="container", for content that is read before it is used. When it closes, focus returns to the element that had it when the dialog opened, or to the element finalFocus names. If that element has left the document, focus goes to its nearest ancestor still in the document.
+- Containment, inertness and Escape are implemented in JavaScript rather than with the native dialog element, so every overlay of the library shares one stacking order: a select opened inside a dialog paints above it. Without JavaScript, there is no dialog.
+- The close button’s target is at least 24 by 24 pixels, and its mark is drawn from a glyph, not a character.
+- The panel has a border as well as a shadow, so its edge stays visible under forced colours, where shadows are removed and the scrim becomes opaque.
+- AlertDialog follows the WAI-ARIA alert dialog pattern: the modal dialog pattern with role="alertdialog" and a required description. The keyboard is the same: Tab and Shift+Tab wrap inside the panel, and Escape closes it.
+- aria-describedby is required. AlertDialog throws an error when no DialogDescription is rendered, so a confirmation is never announced without the sentence that says what it does.
+- Focus starts on AlertDialogCancel, the least destructive answer, as the pattern advises for a step that cannot be undone easily.
+- A press outside never closes an alert dialog, and it is always modal. Escape closes it, which answers with the cancel; set escape="none" when cancelling is not safe either.
+- There is no close part: the reader answers with the cancel or the action. Rendering DialogClose inside AlertDialog throws an error.
+- The tone is carried by the icon’s shape as well as by its colour, so it survives forced colours and readers who cannot tell the colours apart.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-icon-size-lg`, `--slotted-control-inner-size-lg`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-dialog-body-color`, `--slotted-dialog-border-color`, `--slotted-dialog-close-active-background`, `--slotted-dialog-close-color`, `--slotted-dialog-close-hover-background`, `--slotted-dialog-color`, `--slotted-dialog-description-color`, `--slotted-dialog-footer-surface`, `--slotted-dialog-measure`, `--slotted-dialog-radius`, `--slotted-dialog-rule-color`, `--slotted-dialog-scrim`, `--slotted-dialog-surface`, `--slotted-dialog-title-color`, `--slotted-dialog-title-font-family`, `--slotted-duration-long`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-md`, `--slotted-font-size-xl`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-scrim`, `--slotted-shadow-lg`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-overlay`
+
+## Examples
+
+See [dialog.examples.md](./dialog.examples.md).

package/dist/docs/divider.json

@@ -0,0 +1,155 @@
+{
+  "family": "divider",
+  "ui": "divider",
+  "binding": "react",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Line that separates content."
+  },
+  "axes": {
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "align": [
+      "start",
+      "center",
+      "end"
+    ]
+  },
+  "members": {
+    "divider": {
+      "nativeElement": "hr",
+      "defaults": {
+        "orientation": "horizontal",
+        "decorative": false,
+        "inset": false,
+        "align": "center"
+      },
+      "capabilities": [
+        "orientation",
+        "decorative"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "divider": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "Divider",
+          "description": "Direction the rule runs in"
+        },
+        {
+          "name": "decorative",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Divider",
+          "description": "Removes the rule from the accessibility tree"
+        },
+        {
+          "name": "inset",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Divider",
+          "description": "Stops the rule short of both ends of its container"
+        },
+        {
+          "name": "label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Divider",
+          "description": "Short string the rule is interrupted by, and its name"
+        },
+        {
+          "name": "align",
+          "type": "'start' | 'center' | 'end'",
+          "defaultValue": "center",
+          "appliesTo": "Divider",
+          "description": "Where the label sits"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Divider",
+          "description": "Renders a different root element"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "The plain rule is an hr, which already exposes the separator role, so the component writes no role of its own.",
+        "A vertical rule receives aria-orientation, because a separator is horizontal unless it says otherwise.",
+        "decorative sets role=\"none\". Use it when the rule groups content visually and a screen reader user loses nothing by not hearing it.",
+        "A labelled rule renders a div, because an hr takes no content. Its name comes from aria-label: the separator role makes its children presentational, so the visible label alone would leave the rule announced as empty.",
+        "A decorative rule carries no name, because role=\"none\" prohibits one. Its label is read in document order, like any other text.",
+        "A rule rendered into another element — the li a menu separator has to be — receives role=\"separator\", because only the hr carries that meaning by itself.",
+        "A role or an aria-label the consumer passes is kept, so a rule that has to say something else keeps saying it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-padding-inline-md",
+    "--slotted-divider-color",
+    "--slotted-divider-gap",
+    "--slotted-divider-inset",
+    "--slotted-divider-label-color",
+    "--slotted-divider-min-length",
+    "--slotted-divider-thickness",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-xs",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-text-muted"
+  ],
+  "examples": [
+    {
+      "id": "divider-react-sections",
+      "title": "Separating two regions",
+      "note": null,
+      "language": "tsx",
+      "source": "<section>\n  <h2>Billing</h2>\n  <Divider />\n  <h2>Members</h2>\n</section>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-react-toolbar",
+      "title": "A vertical rule between groups of controls",
+      "note": null,
+      "language": "tsx",
+      "source": "<div className=\"toolbar\">\n  <Button>Bold</Button>\n  <Divider orientation=\"vertical\" />\n  <Button>Align left</Button>\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-react-label",
+      "title": "A rule interrupted by a label",
+      "note": null,
+      "language": "tsx",
+      "source": "<>\n  <SignInWithGoogle />\n  <Divider label=\"Or\" />\n  <EmailAndPassword />\n</>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "divider-react-menu",
+      "title": "A separator between two groups of menu items",
+      "note": null,
+      "language": "tsx",
+      "source": "<ul role=\"menu\">\n  <li role=\"menuitem\">Rename</li>\n  <Divider inset render={(props) => <li {...props} />} />\n  <li role=\"menuitem\">Delete</li>\n</ul>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/divider.md

@@ -0,0 +1,86 @@
+<!-- index: ./index.md -->
+# divider
+
+`data-ui="divider"` · Line that separates content.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<section>
+  <h2>Billing</h2>
+  <Divider />
+  <h2>Members</h2>
+</section>;
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | Divider | Direction the rule runs in |
+| `decorative` | `boolean` | false | Divider | Removes the rule from the accessibility tree |
+| `inset` | `boolean` | false | Divider | Stops the rule short of both ends of its container |
+| `label` | `string` | — | Divider | Short string the rule is interrupted by, and its name |
+| `align` | `'start' \| 'center' \| 'end'` | center | Divider | Where the label sits |
+| `render` | `(props) => ReactNode` | — | Divider | Renders a different root element |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `align` | `start`, `center`, `end` | `center` |
+
+## Rules
+
+- The plain rule is an hr, which already exposes the separator role, so the component writes no role of its own.
+- A vertical rule receives aria-orientation, because a separator is horizontal unless it says otherwise.
+- decorative sets role="none". Use it when the rule groups content visually and a screen reader user loses nothing by not hearing it.
+- A labelled rule renders a div, because an hr takes no content. Its name comes from aria-label: the separator role makes its children presentational, so the visible label alone would leave the rule announced as empty.
+- A decorative rule carries no name, because role="none" prohibits one. Its label is read in document order, like any other text.
+- A rule rendered into another element — the li a menu separator has to be — receives role="separator", because only the hr carries that meaning by itself.
+- A role or an aria-label the consumer passes is kept, so a rule that has to say something else keeps saying it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-padding-inline-md`, `--slotted-divider-color`, `--slotted-divider-gap`, `--slotted-divider-inset`, `--slotted-divider-label-color`, `--slotted-divider-min-length`, `--slotted-divider-thickness`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-xs`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-text-muted`
+
+## Examples
+
+### A vertical rule between groups of controls
+
+Excerpt — not a complete module
+
+```tsx
+<div className="toolbar">
+  <Button>Bold</Button>
+  <Divider orientation="vertical" />
+  <Button>Align left</Button>
+</div>;
+```
+
+### A rule interrupted by a label
+
+Excerpt — not a complete module
+
+```tsx
+<>
+  <SignInWithGoogle />
+  <Divider label="Or" />
+  <EmailAndPassword />
+</>;
+```
+
+### A separator between two groups of menu items
+
+Excerpt — not a complete module
+
+```tsx
+<ul role="menu">
+  <li role="menuitem">Rename</li>
+  <Divider inset render={(props) => <li {...props} />} />
+  <li role="menuitem">Delete</li>
+</ul>;
+```