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

package/dist/docs/dialog.examples.md

@@ -0,0 +1,2403 @@
+<!-- index: ./index.md -->
+# dialog
+
+`data-ui="dialog"` · Modal dialog and alert dialog.
+
+## Examples
+
+### Playground
+
+A layer opened inside the scene rather than over the page. Press the trigger, then Tab: focus is contained, Escape closes, and focus returns to the button it came from.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog>
+  <DialogTrigger>Edit project</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Edit project</DialogTitle>
+      <DialogDescription>The name is visible to the whole space.</DialogDescription>
+      <DialogClose />
+    </DialogHeader>
+    <DialogBody>
+      <TextField aria-label="Name" defaultValue="Home page redesign" />
+    </DialogBody>
+    <DialogFooter>
+      <Button variant="ghost" tone="secondary">
+        Cancel
+      </Button>
+      <Button>Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>;
+```
+
+### How wide the panel is allowed to be
+
+Five named steps rather than a pixel string, because a theme can retune a step and cannot retune width: 600px. full spends the whole layer minus its padding, for a dialog that is a document.
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  type DialogSize,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+const SIZES: { size: DialogSize; title: string; body: string }[] = [
+  {
+    size: 'sm',
+    title: 'Rename warehouse',
+    body: 'Small, 24rem: one field or one question.',
+  },
+  {
+    size: 'md',
+    title: 'Edit customer',
+    body: 'Medium, 32rem, the default: a short form of one column.',
+  },
+  {
+    size: 'lg',
+    title: 'Invoice INV-2041',
+    body: 'Large, 42rem: a record with a table of line items.',
+  },
+  {
+    size: 'xl',
+    title: 'Compare price lists',
+    body: 'Extra large, 56rem: two columns side by side.',
+  },
+  {
+    size: 'full',
+    title: 'Shipment manifest',
+    body: 'Full: the whole layer less its padding, for a document.',
+  },
+];
+
+export default function DialogSizes() {
+  return (
+    <Inline gap={2}>
+      {SIZES.map((option) => (
+        <Dialog key={option.size} size={option.size}>
+          <DialogTrigger
+            render={(props) => (
+              <Button {...props} tone="secondary" variant="outline">
+                {option.size}
+              </Button>
+            )}
+          />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>{option.title}</DialogTitle>
+              <DialogClose />
+            </DialogHeader>
+            <DialogBody>
+              <Text size="sm">{option.body}</Text>
+            </DialogBody>
+          </DialogContent>
+        </Dialog>
+      ))}
+    </Inline>
+  );
+}
+```
+
+### Where the panel sits in the layer
+
+center is right for a panel whose height is settled; top is right for one that grows as the reader types, because a centred panel moves under the cursor every time a line is added.
+
+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 { Textarea } from '@slotted/react/textarea';
+
+export default function DialogPlacement() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen} placement="top">
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            Add a note
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Note on order SO-1182</DialogTitle>
+          <DialogDescription>The warehouse team sees the note on the pick list.</DialogDescription>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <Field>
+            <FieldLabel>Note</FieldLabel>
+            <Textarea rows={3} maxRows={12} placeholder="Leave at the loading dock after 2 pm." />
+          </Field>
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+            Cancel
+          </Button>
+          <Button onClick={() => setOpen(false)}>Add note</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### What scrolls when the content is long
+
+content bounds the panel to the layer and scrolls the body, so the actions stay on screen; viewport scrolls the whole panel, for content that is read rather than acted on. Radix and React Aria ship neither, and a footer past the fold is the default of following their examples.
+
+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 { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const ITEMS = Array.from({ length: 24 }, (_, index) => ({
+  sku: `NW-${String(4100 + index * 7)}`,
+  name: [
+    'Chai, 10 boxes',
+    'Aniseed syrup, 12 bottles',
+    'Cajun seasoning, 48 jars',
+    'Olive oil, 36 bottles',
+    'Dried pears, 12 packs',
+    'Curry sauce, 12 jars',
+  ][index % 6],
+}));
+
+const TERMS = [
+  'Prices are in US dollars and exclude sales tax, which is added at the rate of the delivery address.',
+  'Payment is due 30 days from the invoice date. Balances unpaid after 45 days accrue interest at 1% a month.',
+  'Goods travel at the risk of Northwind Traders until they are signed for at the delivery address.',
+  'Damaged goods are reported within 5 business days of delivery, with photos of the packaging and the label.',
+  'Returns of undamaged goods are accepted within 30 days and are refunded less a 10% restocking fee.',
+  'Orders above $5,000 may be split into several shipments, each invoiced when it leaves the warehouse.',
+  'Either party may end a standing order with 14 days of written notice; shipments already picked are invoiced.',
+  'These terms are governed by the law of the State of Washington.',
+];
+
+export default function DialogScroll() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Inline gap={2}>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Review 24 line items
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Purchase order PO-7730</DialogTitle>
+            <DialogDescription>Only the list scrolls; the actions stay in view.</DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Stack gap={2}>
+              {ITEMS.map((item) => (
+                <Inline key={item.sku} gap={3} justify="between">
+                  <Text size="sm">{item.name}</Text>
+                  <Text size="sm" tone="muted">
+                    {item.sku}
+                  </Text>
+                </Inline>
+              ))}
+            </Stack>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={() => setOpen(false)}>Approve order</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <Dialog scroll="viewport">
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Read the terms of sale
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Terms of sale</DialogTitle>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Stack gap={4}>
+              {TERMS.map((term) => (
+                <Text key={term}>{term}</Text>
+              ))}
+            </Stack>
+          </DialogBody>
+        </DialogContent>
+      </Dialog>
+    </Inline>
+  );
+}
+```
+
+### The layer, around a box you painted
+
+surface="plain" turns the family’s own paint off — no ground, no border, no radius, no shadow, no rows — and keeps the portal, the scrim, the containment and the dismissal policy. It is what a headless library ships by default, offered here as an axis rather than as the only shape.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog surface="plain">
+  <DialogTrigger>View the media</DialogTrigger>
+  <DialogContent>
+    <Card fill="elevated">
+      <DialogTitle>A card, inside the layer</DialogTitle>
+      <DialogDescription>The family paints nothing here.</DialogDescription>
+    </Card>
+  </DialogContent>
+</Dialog>;
+```
+
+### Taking the whole layer on a narrow one
+
+A container query at a literal breakpoint, not a viewport query: the layer answers its own inline size, so a dialog inside a named portal container is as narrow as that container rather than as the window.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog fullScreen="always">
+  <DialogTrigger>New invoice</DialogTrigger>
+  <DialogContent>…</DialogContent>
+</Dialog>;
+```
+
+### A layer the page behind can still be used
+
+modal={false} writes no aria-modal, makes nothing inert, locks no scroll and contains no focus. The APG warns that marking a dialog modal without doing all four has severe consequences for the readers who rely on the mark.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog modal={false}>
+  <DialogTrigger>Order details</DialogTrigger>
+  <DialogContent>…</DialogContent>
+</Dialog>;
+```
+
+### Refusing a close, and refusing it once
+
+Six ways to close and one request. A guard on onOpenChange covers Escape, an outside press, the close button and the imperative handle together; Radix reports the same policy through four callbacks.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog
+  open={open}
+  onOpenChange={(next, request) => {
+    if (!next && saving) return request.cancel();
+    setOpen(next);
+  }}
+>
+  …
+</Dialog>;
+```
+
+### Where focus goes, and where it comes back to
+
+By default the first tabbable element, and the trigger again on close. initialFocus names another element — a search input, or the panel itself for content that has to be read before it is operated, which is the APG’s own note.
+
+Excerpt — not a complete module
+
+```tsx
+const search = useRef<HTMLInputElement>(null);
+
+<Dialog initialFocus={search}>
+  <DialogTrigger>Search</DialogTrigger>
+  <DialogContent>
+    <DialogBody>
+      <TextField aria-label="Search" ref={search} />
+    </DialogBody>
+  </DialogContent>
+</Dialog>;
+```
+
+### Open before the content arrived
+
+The body carries aria-busy and keeps a floor so the panel does not jump to size when the data lands. The header, the close button and Escape all stay operable: a loading dialog a reader cannot leave is the worse failure of the two.
+
+Example
+
+```tsx
+import { useEffect, useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from '@slotted/react/description-list';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Skeleton, SkeletonRegion } from '@slotted/react/skeleton';
+
+interface Invoice {
+  customer: string;
+  issued: string;
+  due: string;
+  amount: string;
+}
+
+const FIELDS: { key: keyof Invoice; term: string; width: string }[] = [
+  { key: 'customer', term: 'Customer', width: '9rem' },
+  { key: 'issued', term: 'Issued', width: '6rem' },
+  { key: 'due', term: 'Due', width: '6rem' },
+  { key: 'amount', term: 'Amount', width: '5rem' },
+];
+
+export default function DialogLoading() {
+  const [open, setOpen] = useState(false);
+  const [invoice, setInvoice] = useState<Invoice | null>(null);
+
+  useEffect(() => {
+    if (!open) return;
+    setInvoice(null);
+    const timer = setTimeout(
+      () =>
+        setInvoice({
+          customer: 'Northwind Traders',
+          issued: '12 August 2026',
+          due: '11 September 2026',
+          amount: '$1,240.00',
+        }),
+      1200,
+    );
+    return () => clearTimeout(timer);
+  }, [open]);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen} loading={invoice === null}>
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            View invoice INV-2041
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Invoice INV-2041</DialogTitle>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <SkeletonRegion
+            delay={200}
+            loading={invoice === null}
+            messages={{ label: 'Loading invoice' }}
+          >
+            <DescriptionList>
+              {FIELDS.map((field) => (
+                <DescriptionListItem key={field.key}>
+                  <DescriptionListTerm>{field.term}</DescriptionListTerm>
+                  <DescriptionListDescription>
+                    {invoice === null ? <Skeleton inlineSize={field.width} /> : invoice[field.key]}
+                  </DescriptionListDescription>
+                </DescriptionListItem>
+              ))}
+            </DescriptionList>
+          </SkeletonRegion>
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### A layer opened from a layer
+
+Escape reaches the topmost one only, and a layer that refuses stops the request reaching the one beneath it. The depth comes from the single stack dismissable-layer keeps, so nothing here states a z-index.
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from '@slotted/react/description-list';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+
+const CARRIERS = [
+  { value: 'ups', label: 'UPS Ground' },
+  { value: 'fedex', label: 'FedEx Ground' },
+  { value: 'usps', label: 'USPS Priority Mail' },
+];
+
+const labelOf = (value: string) => CARRIERS.find((carrier) => carrier.value === value)?.label;
+
+export default function DialogNested() {
+  const [carrier, setCarrier] = useState('ups');
+  const [changing, setChanging] = useState(false);
+  const [draft, setDraft] = useState(carrier);
+
+  return (
+    <Dialog>
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            Open order SO-1182
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Order SO-1182</DialogTitle>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <DescriptionList>
+            <DescriptionListItem>
+              <DescriptionListTerm>Customer</DescriptionListTerm>
+              <DescriptionListDescription>Contoso Foods</DescriptionListDescription>
+            </DescriptionListItem>
+            <DescriptionListItem>
+              <DescriptionListTerm>Carrier</DescriptionListTerm>
+              <DescriptionListDescription>{labelOf(carrier)}</DescriptionListDescription>
+            </DescriptionListItem>
+          </DescriptionList>
+        </DialogBody>
+        <DialogFooter>
+          <Dialog
+            open={changing}
+            onOpenChange={(next) => {
+              if (next) setDraft(carrier);
+              setChanging(next);
+            }}
+            size="sm"
+          >
+            <DialogTrigger
+              render={(props) => (
+                <Button {...props} tone="secondary" variant="outline">
+                  Change carrier
+                </Button>
+              )}
+            />
+            <DialogContent>
+              <DialogHeader>
+                <DialogTitle>Change carrier</DialogTitle>
+                <DialogClose />
+              </DialogHeader>
+              <DialogBody>
+                <Field>
+                  <FieldLabel>Carrier</FieldLabel>
+                  <Select
+                    items={CARRIERS}
+                    value={draft}
+                    onValueChange={(next) => {
+                      if (typeof next === 'string') setDraft(next);
+                    }}
+                  >
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {CARRIERS.map((option) => (
+                        <SelectItem key={option.value} value={option.value}>
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </Field>
+              </DialogBody>
+              <DialogFooter>
+                <Button variant="ghost" tone="secondary" onClick={() => setChanging(false)}>
+                  Cancel
+                </Button>
+                <Button
+                  onClick={() => {
+                    setCarrier(draft);
+                    setChanging(false);
+                  }}
+                >
+                  Use carrier
+                </Button>
+              </DialogFooter>
+            </DialogContent>
+          </Dialog>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### Content the family did not choose
+
+A ninety-character unbroken token in the title would widen a centred panel past both edges of the layer at once; overflow-wrap and a zero minimum are the pair that answer it. Long German and right-to-left strings are in the same scene.
+
+Excerpt — not a complete module
+
+```tsx
+<DialogTitle>deployment-pipeline-eu-west-1-production-rollback-2026-09-04T01</DialogTitle>;
+```
+
+### Replacing a part, and reaching the instance
+
+render substitutes the element of every part, which is how the trigger becomes a Button. The ref on Dialog is a handle with open, close and focus — the three actions a consumer cannot express declaratively.
+
+Excerpt — not a complete module
+
+```tsx
+<DialogTrigger render={(props) => <Button {...props}>Edit project</Button>} />;
+```
+
+### Deciding once for the application
+
+Eight decisions an application takes once instead of eight props on every dialog in a product. Angular Material is the only surveyed library with an equivalent, and a dialog that states one itself still wins.
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDefaultsProvider,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+export default function DialogDefaults() {
+  return (
+    <DialogDefaultsProvider placement="top" size="lg">
+      <Inline gap={2}>
+        <Dialog>
+          <DialogTrigger
+            render={(props) => (
+              <Button {...props} tone="secondary" variant="outline">
+                Purchase order PO-7730
+              </Button>
+            )}
+          />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Purchase order PO-7730</DialogTitle>
+              <DialogClose />
+            </DialogHeader>
+            <DialogBody>
+              <Text size="sm">Large and at the top, from the provider.</Text>
+            </DialogBody>
+          </DialogContent>
+        </Dialog>
+        <Dialog size="sm">
+          <DialogTrigger
+            render={(props) => (
+              <Button {...props} tone="secondary" variant="outline">
+                Rename supplier
+              </Button>
+            )}
+          />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Rename supplier</DialogTitle>
+              <DialogClose />
+            </DialogHeader>
+            <DialogBody>
+              <Text size="sm">At the top from the provider, and small because it says so.</Text>
+            </DialogBody>
+          </DialogContent>
+        </Dialog>
+      </Inline>
+    </DialogDefaultsProvider>
+  );
+}
+```
+
+### The pattern’s table, and what it costs
+
+Tab and Shift+Tab wrap inside the layer, Escape closes the topmost one, and the background is inert to the pointer and to the accessibility tree at once. All three are JavaScript here, because the platform’s dialog element is declined.
+
+Excerpt — not a complete module
+
+```tsx
+<Dialog onOpenChange={(open, request) => report(request.reason, request.result)}>…</Dialog>;
+```
+
+### Playground
+
+A confirmation opened inside the scene. Focus lands on the least destructive action, an outside press does nothing at all, and Escape answers because a member with a cancel action can always cancel.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDialog>
+  <DialogTrigger>Delete project</DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <AlertDialogIcon />
+      <DialogTitle>Delete this project?</DialogTitle>
+      <DialogDescription>
+        The project and its 42 documents leave for everyone. This cannot be undone.
+      </DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <AlertDialogCancel
+        render={(props) => <Button {...props} variant="outline" tone="secondary" />}
+      >
+        Keep project
+      </AlertDialogCancel>
+      <AlertDialogAction render={(props) => <Button {...props} tone="danger" />}>
+        Delete project
+      </AlertDialogAction>
+    </DialogFooter>
+  </DialogContent>
+</AlertDialog>;
+```
+
+### What kind of decision this is
+
+Each tone carries its own mark, so the register survives a reader who cannot tell the colours apart and forced colours, where every tone ground becomes one system colour and the silhouette is all that is left.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDialog tone="warning">
+  <DialogTrigger>Leave without saving</DialogTrigger>
+  <DialogContent>…</DialogContent>
+</AlertDialog>;
+```
+
+### Two controls, each saying what it does
+
+Labels name the action rather than answering a question — “Excluir projeto”, not “Sim”. The action closes with submit and the cancel with dismiss, so a consumer reading the reason knows which one the reader chose.
+
+Excerpt — not a complete module
+
+```tsx
+<DialogFooter>
+  <AlertDialogCancel>Keep project</AlertDialogCancel>
+  <AlertDialogAction value="deleted">Delete project</AlertDialogAction>
+</DialogFooter>;
+```
+
+### What can and cannot dismiss it
+
+An outside press never closes an alert dialog, whatever the consumer asks for. Ark and React Aria make the role a prop, so setting role="alertdialog" and forgetting the policy ships a destructive confirmation a stray click dismisses.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDialog escape="none">
+  <DialogTrigger>End the migration</DialogTrigger>
+  <DialogContent>…</DialogContent>
+</AlertDialog>;
+```
+
+### The safest thing under the reader’s hands
+
+Focus lands on the cancel action rather than on the first tabbable element, which is what the APG advises for a step that is not easily reversible. It is a default of the member, not something a consumer remembers to set.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDialog initialFocus="cancel">
+  <DialogTrigger>Delete</DialogTrigger>
+  <DialogContent>…</DialogContent>
+</AlertDialog>;
+```
+
+### A confirmation that has more to say
+
+A body between the header and the actions holds the list of what is about to go. The description stays the one sentence aria-describedby announces, so the reader hears the consequence before the detail.
+
+Excerpt — not a complete module
+
+```tsx
+<DialogHeader>
+  <AlertDialogIcon />
+  <DialogTitle>Delete 3 documents?</DialogTitle>
+  <DialogDescription>This cannot be undone.</DialogDescription>
+</DialogHeader>;
+```
+
+### The actions are the consumer’s own buttons
+
+render hands each control every attribute the family wrote, so the danger button is the library’s Button with the family’s behaviour on it — nothing is reimplemented and nothing is wrapped.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDialogAction render={(props) => <Button {...props} tone="danger" />}>
+  Delete project
+</AlertDialogAction>;
+```
+
+### What the role changes, and what it does not
+
+role="alertdialog" and a mandatory aria-describedby are the two things the pattern adds; the keyboard is the modal dialog’s. The trigger still says aria-haspopup="dialog", because the property has no alertdialog token.
+
+Excerpt — not a complete module
+
+```tsx
+<DialogDescription>The project and its 42 documents leave for everyone.</DialogDescription>;
+```
+
+### alert-tones.tsx
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogIcon,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  type DialogTone,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+
+const CONFIRMATIONS: {
+  tone: DialogTone;
+  trigger: string;
+  title: string;
+  description: string;
+  action: string;
+}[] = [
+  {
+    tone: 'accent',
+    trigger: 'Send invoices',
+    title: 'Send 214 invoices?',
+    description: 'Each customer receives the September invoice by email within the hour.',
+    action: 'Send invoices',
+  },
+  {
+    tone: 'warning',
+    trigger: 'Publish prices',
+    title: 'Publish the new prices?',
+    description: 'Open quotes keep their prices; new orders use the new ones from now on.',
+    action: 'Publish prices',
+  },
+  {
+    tone: 'success',
+    trigger: 'Close September',
+    title: 'Close the books for September?',
+    description: 'All 1,180 entries reconcile. Entries dated September can no longer be edited.',
+    action: 'Close September',
+  },
+];
+
+export default function DialogAlertTones() {
+  return (
+    <Inline gap={2}>
+      {CONFIRMATIONS.map((confirmation) => (
+        <AlertDialog key={confirmation.tone} tone={confirmation.tone}>
+          <DialogTrigger
+            render={(props) => (
+              <Button {...props} tone="secondary" variant="outline">
+                {confirmation.trigger}
+              </Button>
+            )}
+          />
+          <DialogContent>
+            <DialogHeader>
+              <AlertDialogIcon />
+              <DialogTitle>{confirmation.title}</DialogTitle>
+              <DialogDescription>{confirmation.description}</DialogDescription>
+            </DialogHeader>
+            <DialogFooter>
+              <AlertDialogCancel
+                render={(props) => (
+                  <Button {...props} tone="secondary" variant="outline">
+                    Not now
+                  </Button>
+                )}
+              />
+              <AlertDialogAction
+                render={(props) => (
+                  <Button {...props} tone={confirmation.tone}>
+                    {confirmation.action}
+                  </Button>
+                )}
+              />
+            </DialogFooter>
+          </DialogContent>
+        </AlertDialog>
+      ))}
+    </Inline>
+  );
+}
+```
+
+### async-submit.tsx
+
+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 { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+export default function DialogAsyncSubmit() {
+  const [open, setOpen] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [sent, setSent] = useState(false);
+
+  const refund = () => {
+    setSaving(true);
+    setTimeout(() => {
+      setSaving(false);
+      setSent(true);
+      setOpen(false);
+    }, 1500);
+  };
+
+  return (
+    <Inline align="center" gap={3}>
+      <Dialog
+        open={open}
+        onOpenChange={(next, request) => {
+          if (!next && saving) return request.cancel();
+          if (next) setSent(false);
+          setOpen(next);
+        }}
+      >
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Refund order SO-1182
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Refund $1,240.00</DialogTitle>
+            <DialogDescription>To the card ending 4242, for order SO-1182.</DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Text size="sm">
+              The payment provider takes a moment to confirm. The dialog stays open until it does.
+            </Text>
+          </DialogBody>
+          <DialogFooter>
+            <Button
+              disabled={saving}
+              variant="ghost"
+              tone="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button loading={saving} messages={{ loading: 'Issuing refund' }} onClick={refund}>
+              Issue refund
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {sent ? (
+        <Text role="status" size="sm" tone="muted">
+          Refund issued.
+        </Text>
+      ) : null}
+    </Inline>
+  );
+}
+```
+
+### bulk-edit.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Badge } from '@slotted/react/badge';
+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 {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+  TableRowHeader,
+  TableSelect,
+  TableSelectAll,
+} from '@slotted/react/table';
+import { Text } from '@slotted/react/typography';
+
+const STATUSES = [
+  { value: 'processing', label: 'Processing', tone: 'accent' },
+  { value: 'hold', label: 'On hold', tone: 'warning' },
+  { value: 'ready', label: 'Ready to ship', tone: 'success' },
+] as const;
+
+const WAREHOUSES = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+type Status = (typeof STATUSES)[number]['value'];
+
+const INITIAL: { id: string; customer: string; status: Status; warehouse: string }[] = [
+  { id: 'SO-1182', customer: 'Contoso Foods', status: 'processing', warehouse: 'RNO' },
+  { id: 'SO-1183', customer: 'Fabrikam Grocers', status: 'processing', warehouse: 'CMH' },
+  { id: 'SO-1184', customer: 'Tailspin Market', status: 'hold', warehouse: 'RNO' },
+  { id: 'SO-1185', customer: 'Woodgrove Deli', status: 'processing', warehouse: 'SAV' },
+];
+
+const statusOf = (value: Status) => STATUSES.find((status) => status.value === value)!;
+const warehouseOf = (value: string) => WAREHOUSES.find((option) => option.value === value)?.label;
+
+export default function DialogBulkEdit() {
+  const [orders, setOrders] = useState(INITIAL);
+  const [chosen, setChosen] = useState<readonly string[]>([]);
+  const [editing, setEditing] = useState<readonly string[]>([]);
+  const [open, setOpen] = useState(false);
+  const [status, setStatus] = useState<Status>('ready');
+  const [warehouse, setWarehouse] = useState('RNO');
+  const count = chosen.length;
+  const noun = editing.length === 1 ? 'order' : 'orders';
+
+  const apply = () => {
+    setOrders((rows) =>
+      rows.map((row) => (editing.includes(row.id) ? { ...row, status, warehouse } : row)),
+    );
+    setChosen([]);
+    setOpen(false);
+  };
+
+  return (
+    <Stack gap={3}>
+      <Inline align="center" gap={3}>
+        <Text size="sm" tone="muted">
+          {count === 0 ? 'Select orders to edit them together.' : `${count} selected`}
+        </Text>
+        <Dialog
+          open={open}
+          onOpenChange={(next) => {
+            if (next) setEditing(chosen);
+            setOpen(next);
+          }}
+        >
+          <DialogTrigger
+            render={(props) => (
+              <Button
+                {...props}
+                disabled={count === 0}
+                focusableWhenDisabled
+                size="sm"
+                tone="secondary"
+                variant="outline"
+              >
+                Edit selected
+              </Button>
+            )}
+          />
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>
+                Edit {editing.length} {noun}
+              </DialogTitle>
+              <DialogDescription>{editing.join(', ')}</DialogDescription>
+              <DialogClose />
+            </DialogHeader>
+            <DialogBody>
+              <Stack gap={4}>
+                <Field>
+                  <FieldLabel>Status</FieldLabel>
+                  <Select
+                    items={[...STATUSES]}
+                    value={status}
+                    onValueChange={(next) => {
+                      if (typeof next === 'string') setStatus(next as Status);
+                    }}
+                  >
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {STATUSES.map((option) => (
+                        <SelectItem key={option.value} value={option.value}>
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </Field>
+                <Field>
+                  <FieldLabel>Ships from</FieldLabel>
+                  <Select
+                    items={WAREHOUSES}
+                    value={warehouse}
+                    onValueChange={(next) => {
+                      if (typeof next === 'string') setWarehouse(next);
+                    }}
+                  >
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {WAREHOUSES.map((option) => (
+                        <SelectItem key={option.value} value={option.value}>
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </Field>
+              </Stack>
+            </DialogBody>
+            <DialogFooter>
+              <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+                Cancel
+              </Button>
+              <Button onClick={apply}>
+                Update {editing.length} {noun}
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </Inline>
+      <Table columns={5} selectionMode="multiple" value={chosen} onValueChange={setChosen}>
+        <TableContent>
+          <TableHead>
+            <TableRow>
+              <TableSelectAll />
+              <TableColumnHeader>Order</TableColumnHeader>
+              <TableColumnHeader>Customer</TableColumnHeader>
+              <TableColumnHeader>Status</TableColumnHeader>
+              <TableColumnHeader>Ships from</TableColumnHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {orders.map((row) => (
+              <TableRow key={row.id} value={row.id}>
+                <TableSelect />
+                <TableRowHeader>{row.id}</TableRowHeader>
+                <TableCell>{row.customer}</TableCell>
+                <TableCell>
+                  <Badge tone={statusOf(row.status).tone}>{statusOf(row.status).label}</Badge>
+                </TableCell>
+                <TableCell>{warehouseOf(row.warehouse)}</TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableContent>
+      </Table>
+    </Stack>
+  );
+}
+```
+
+### cancel-order.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Badge } from '@slotted/react/badge';
+import { Button } from '@slotted/react/button';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogIcon,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Text } from '@slotted/react/typography';
+
+const REASONS = [
+  { value: 'customer', label: 'The customer asked to cancel' },
+  { value: 'stock', label: 'Items are out of stock' },
+  { value: 'payment', label: 'The payment was flagged' },
+  { value: 'duplicate', label: 'Duplicate order' },
+];
+
+export default function DialogCancelOrder() {
+  const [cancelled, setCancelled] = useState(false);
+  const [reason, setReason] = useState<string | null>(null);
+
+  return (
+    <Inline align="center" gap={3}>
+      <Text weight="medium">Order SO-1182</Text>
+      <Badge tone={cancelled ? 'danger' : 'accent'}>{cancelled ? 'Cancelled' : 'Processing'}</Badge>
+      <AlertDialog onOpenChange={(open) => open && setReason(null)}>
+        <DialogTrigger
+          render={(props) => (
+            <Button
+              {...props}
+              disabled={cancelled}
+              focusableWhenDisabled
+              size="sm"
+              tone="danger"
+              variant="outline"
+            >
+              Cancel order
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <AlertDialogIcon />
+            <DialogTitle>Cancel order SO-1182?</DialogTitle>
+            <DialogDescription>
+              Contoso Foods is refunded $1,240.00 and the 6 items go back to stock. The order cannot
+              be reopened.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogBody>
+            <Field required>
+              <FieldLabel>Reason</FieldLabel>
+              <Select
+                items={REASONS}
+                value={reason}
+                onValueChange={(next) => setReason(typeof next === 'string' ? next : null)}
+              >
+                <SelectTrigger>
+                  <SelectValue placeholder="Choose a reason" />
+                </SelectTrigger>
+                <SelectContent>
+                  {REASONS.map((option) => (
+                    <SelectItem key={option.value} value={option.value}>
+                      {option.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </Field>
+          </DialogBody>
+          <DialogFooter>
+            <AlertDialogCancel
+              render={(props) => (
+                <Button {...props} tone="secondary" variant="outline">
+                  Keep order
+                </Button>
+              )}
+            />
+            <AlertDialogAction
+              onClick={() => setCancelled(true)}
+              render={(props) => (
+                <Button {...props} disabled={reason === null} tone="danger">
+                  Cancel order
+                </Button>
+              )}
+            />
+          </DialogFooter>
+        </DialogContent>
+      </AlertDialog>
+    </Inline>
+  );
+}
+```
+
+### create-shipment.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+
+import { Button } from '@slotted/react/button';
+import { Checkbox } from '@slotted/react/checkbox';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@slotted/react/select';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+import { Text } from '@slotted/react/typography';
+
+const CARRIERS = [
+  { value: 'ups', label: 'UPS Ground', description: '3–5 business days' },
+  { value: 'fedex', label: 'FedEx 2Day', description: '2 business days' },
+  { value: 'usps', label: 'USPS Priority Mail', description: '1–3 business days' },
+];
+
+function weightError(value: string): string {
+  if (value.trim() === '') return 'Enter the total weight of the packages.';
+  const weight = Number(value);
+  if (!Number.isFinite(weight) || weight <= 0) return 'Enter a weight above 0, such as 18.4.';
+  return '';
+}
+
+export default function DialogCreateShipment() {
+  const [open, setOpen] = useState(false);
+  const [carrier, setCarrier] = useState('ups');
+  const [weight, setWeight] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [created, setCreated] = useState<string | null>(null);
+  const error = submitted ? weightError(weight) : '';
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    if (weightError(weight) !== '') return;
+    setSaving(true);
+    setTimeout(() => {
+      const label = CARRIERS.find((option) => option.value === carrier)?.label;
+      setSaving(false);
+      setCreated(`Shipment SH-4472 created with ${label}.`);
+      setOpen(false);
+    }, 1200);
+  };
+
+  return (
+    <Inline align="center" gap={3}>
+      <Dialog
+        open={open}
+        onOpenChange={(next, request) => {
+          if (!next && saving) return request.cancel();
+          if (next) {
+            setWeight('');
+            setSubmitted(false);
+          }
+          setOpen(next);
+        }}
+        size="lg"
+      >
+        <DialogTrigger render={(props) => <Button {...props}>Create shipment</Button>} />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Create a shipment</DialogTitle>
+            <DialogDescription>
+              Order SO-1182 for Contoso Foods: 6 items to 1200 Pike St, Seattle.
+            </DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <form id="create-shipment" noValidate onSubmit={submit}>
+              <Stack gap={5}>
+                <Field>
+                  <FieldLabel>Carrier</FieldLabel>
+                  <Select
+                    items={CARRIERS}
+                    name="carrier"
+                    value={carrier}
+                    onValueChange={(next) => {
+                      if (typeof next === 'string') setCarrier(next);
+                    }}
+                  >
+                    <SelectTrigger>
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {CARRIERS.map((option) => (
+                        <SelectItem
+                          key={option.value}
+                          description={option.description}
+                          value={option.value}
+                        >
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </Field>
+                <Field required invalid={error !== '' ? true : undefined}>
+                  <FieldLabel>Weight in kilograms</FieldLabel>
+                  <FieldDescription>
+                    All packages together, as weighed at the dock.
+                  </FieldDescription>
+                  <TextField
+                    inputMode="decimal"
+                    name="weight"
+                    value={weight}
+                    onValueChange={setWeight}
+                  />
+                  <FieldError live="polite" reserve>
+                    {error}
+                  </FieldError>
+                </Field>
+                <Checkbox defaultChecked name="notify">
+                  Email the tracking number to the customer
+                </Checkbox>
+              </Stack>
+            </form>
+          </DialogBody>
+          <DialogFooter>
+            <Button
+              disabled={saving}
+              variant="ghost"
+              tone="secondary"
+              onClick={() => setOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button
+              form="create-shipment"
+              loading={saving}
+              messages={{ loading: 'Creating shipment' }}
+              type="submit"
+            >
+              Create shipment
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {created === null ? null : (
+        <Text role="status" size="sm" tone="muted">
+          {created}
+        </Text>
+      )}
+    </Inline>
+  );
+}
+```
+
+### destructive.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogIcon,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+export default function DialogDestructive() {
+  const [deleted, setDeleted] = useState(false);
+
+  return (
+    <Inline align="center" gap={3}>
+      <AlertDialog>
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="danger" variant="outline">
+              Delete price list
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <AlertDialogIcon />
+            <DialogTitle>Delete the 2026 wholesale price list?</DialogTitle>
+            <DialogDescription>
+              The 412 prices in it are removed, and 9 customers on this list move to retail prices.
+              This cannot be undone.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <AlertDialogCancel
+              render={(props) => (
+                <Button {...props} tone="secondary" variant="outline">
+                  Keep price list
+                </Button>
+              )}
+            />
+            <AlertDialogAction
+              onClick={() => setDeleted(true)}
+              render={(props) => (
+                <Button {...props} tone="danger">
+                  Delete price list
+                </Button>
+              )}
+            />
+          </DialogFooter>
+        </DialogContent>
+      </AlertDialog>
+      {deleted ? (
+        <Text role="status" size="sm" tone="muted">
+          The 2026 wholesale price list was deleted.
+        </Text>
+      ) : null}
+    </Inline>
+  );
+}
+```
+
+### dismiss.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Text } from '@slotted/react/typography';
+
+export default function DialogDismiss() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen} escape="none" outsidePress="none">
+      <DialogTrigger render={(props) => <Button {...props}>Import products</Button>} />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Import 1,240 products</DialogTitle>
+          <DialogDescription>
+            From spring-catalogue.csv into the Northwind price list.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogBody>
+          <Text size="sm">
+            38 rows update existing products and 1,202 add new ones. Escape and a press outside the
+            panel leave this dialog open; choose one of the actions.
+          </Text>
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+            Cancel import
+          </Button>
+          <Button onClick={() => setOpen(false)}>Start import</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### form.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Field, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+import { Text } from '@slotted/react/typography';
+
+function nameError(value: string): string {
+  return value.trim() === '' ? 'Enter the contact’s full name.' : '';
+}
+
+function emailError(value: string): string {
+  if (value.trim() === '') return 'Enter the address the contact reads.';
+  if (!/^\S+@\S+\.\S+$/.test(value)) return 'Enter an address like ana@contoso.com.';
+  return '';
+}
+
+export default function DialogForm() {
+  const [open, setOpen] = useState(false);
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [submitted, setSubmitted] = useState(false);
+  const [added, setAdded] = useState<string | null>(null);
+  const errors = submitted ? { name: nameError(name), email: emailError(email) } : null;
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    if (nameError(name) !== '' || emailError(email) !== '') return;
+    setAdded(`${name.trim()} was added to Contoso Foods.`);
+    setOpen(false);
+  };
+
+  return (
+    <Inline align="center" gap={3}>
+      <Dialog
+        open={open}
+        onOpenChange={(next) => {
+          if (next) {
+            setName('');
+            setEmail('');
+            setSubmitted(false);
+          }
+          setOpen(next);
+        }}
+      >
+        <DialogTrigger render={(props) => <Button {...props}>Add contact</Button>} />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>New contact</DialogTitle>
+            <DialogDescription>Contoso Foods, Seattle.</DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <form id="new-contact" noValidate onSubmit={submit}>
+              <Stack gap={4}>
+                <Field required invalid={errors?.name ? true : undefined}>
+                  <FieldLabel>Full name</FieldLabel>
+                  <TextField autoComplete="name" value={name} onValueChange={setName} />
+                  <FieldError live="polite" reserve>
+                    {errors?.name}
+                  </FieldError>
+                </Field>
+                <Field required invalid={errors?.email ? true : undefined}>
+                  <FieldLabel>Email</FieldLabel>
+                  <TextField
+                    autoComplete="email"
+                    type="email"
+                    value={email}
+                    onValueChange={setEmail}
+                  />
+                  <FieldError live="polite" reserve>
+                    {errors?.email}
+                  </FieldError>
+                </Field>
+              </Stack>
+            </form>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button type="submit" form="new-contact">
+              Add contact
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {added === null ? null : (
+        <Text role="status" size="sm" tone="muted">
+          {added}
+        </Text>
+      )}
+    </Inline>
+  );
+}
+```
+
+### full-screen.tsx
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const STOPS = [
+  { time: '08:10', place: 'Contoso Foods, 1200 Pike St' },
+  { time: '08:55', place: 'Fabrikam Grocers, 410 Broadway E' },
+  { time: '09:40', place: 'Tailspin Market, 3300 Fremont Ave N' },
+  { time: '10:30', place: 'Woodgrove Deli, 85 Pine St' },
+  { time: '11:15', place: 'Wide World Importers, 2201 1st Ave S' },
+];
+
+export default function DialogFullScreen() {
+  return (
+    <Dialog fullscreenToggle size="lg">
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            Open route plan
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Route 14, Tuesday 6 October</DialogTitle>
+          <DialogDescription>5 stops, 38 km, driver Ana Souza.</DialogDescription>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <Stack gap={3}>
+            {STOPS.map((stop) => (
+              <Inline key={stop.time} gap={4}>
+                <Text size="sm" tone="muted">
+                  {stop.time}
+                </Text>
+                <Text size="sm">{stop.place}</Text>
+              </Inline>
+            ))}
+          </Stack>
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### initial-focus.tsx
+
+Example
+
+```tsx
+import { useRef, useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Stack } from '@slotted/react/stack';
+import { TextField } from '@slotted/react/text-field';
+import { Text } from '@slotted/react/typography';
+
+const CUSTOMERS = [
+  'Contoso Foods',
+  'Fabrikam Grocers',
+  'Northwind Traders',
+  'Tailspin Market',
+  'Wide World Importers',
+  'Woodgrove Deli',
+];
+
+export default function DialogInitialFocus() {
+  const search = useRef<HTMLInputElement>(null);
+  const [query, setQuery] = useState('');
+  const matches = CUSTOMERS.filter((name) => name.toLowerCase().includes(query.toLowerCase()));
+
+  return (
+    <Dialog initialFocus={search} onOpenChange={(open) => open && setQuery('')}>
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            Find a customer
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Find a customer</DialogTitle>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <Stack gap={4}>
+            <TextField
+              ref={search}
+              aria-label="Customer name"
+              placeholder="Search by name"
+              type="search"
+              value={query}
+              onValueChange={setQuery}
+            />
+            <Stack gap={2}>
+              {matches.map((name) => (
+                <Text key={name} size="sm">
+                  {name}
+                </Text>
+              ))}
+            </Stack>
+          </Stack>
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### menu-action.tsx
+
+Example
+
+```tsx
+import { useRef, useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@slotted/react/dialog';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger } from '@slotted/react/menu';
+import { TextField } from '@slotted/react/text-field';
+
+export default function DialogMenuAction() {
+  const actions = useRef<HTMLButtonElement>(null);
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Menu>
+        <MenuTrigger
+          ref={actions}
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Customer actions
+            </Button>
+          )}
+        />
+        <MenuContent>
+          <MenuItem onSelect={() => setOpen(true)}>Change credit limit…</MenuItem>
+          <MenuItem>Export statement</MenuItem>
+          <MenuSeparator />
+          <MenuItem tone="danger">Suspend account…</MenuItem>
+        </MenuContent>
+      </Menu>
+      <Dialog open={open} onOpenChange={setOpen} finalFocus={actions} size="sm">
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Credit limit</DialogTitle>
+            <DialogDescription>
+              Contoso Foods has $18,420.00 outstanding on open invoices.
+            </DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Field>
+              <FieldLabel>Limit in US dollars</FieldLabel>
+              <TextField inputMode="decimal" defaultValue="25000" />
+            </Field>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={() => setOpen(false)}>Save limit</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+```
+
+### non-modal.tsx
+
+Example
+
+```tsx
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/typography';
+
+const STEPS = [
+  'Pick the 6 lines on the pick list from aisles 4 and 9.',
+  'Pack the olive oil upright, with dividers.',
+  'Print the UPS label and attach it to the top face.',
+];
+
+export default function DialogNonModal() {
+  return (
+    <Dialog modal={false} outsidePress="none" placement="top" size="sm">
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            Show packing steps
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Packing steps</DialogTitle>
+          <DialogDescription>
+            Order SO-1182. The page stays usable behind this panel.
+          </DialogDescription>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <Stack gap={2}>
+            {STEPS.map((step, index) => (
+              <Text key={step} size="sm">
+                {index + 1}. {step}
+              </Text>
+            ))}
+          </Stack>
+        </DialogBody>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### parts.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Badge } from '@slotted/react/badge';
+import { Button } from '@slotted/react/button';
+import {
+  DescriptionList,
+  DescriptionListDescription,
+  DescriptionListItem,
+  DescriptionListTerm,
+} from '@slotted/react/description-list';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+
+const DETAILS = [
+  { term: 'Carrier', value: 'UPS Ground' },
+  { term: 'Tracking number', value: '1Z 999 AA1 01 2345 6784' },
+  { term: 'Packages', value: '3, 18.4 kg in total' },
+  { term: 'Estimated delivery', value: 'Thursday, 8 October' },
+];
+
+export default function DialogParts() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      <DialogTrigger
+        render={(props) => (
+          <Button {...props} tone="secondary" variant="outline">
+            View shipment
+          </Button>
+        )}
+      />
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Shipment SH-4471</DialogTitle>
+          <DialogDescription>Order SO-1182 for Contoso Foods, Seattle.</DialogDescription>
+          <Badge tone="accent">In transit</Badge>
+          <DialogClose />
+        </DialogHeader>
+        <DialogBody>
+          <DescriptionList>
+            {DETAILS.map((detail) => (
+              <DescriptionListItem key={detail.term}>
+                <DescriptionListTerm>{detail.term}</DescriptionListTerm>
+                <DescriptionListDescription>{detail.value}</DescriptionListDescription>
+              </DescriptionListItem>
+            ))}
+          </DescriptionList>
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+            Close
+          </Button>
+          <Button>Print label</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+### result.tsx
+
+Example
+
+```tsx
+import { useRef, useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  type DialogHandle,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from '@slotted/react/dialog';
+import { Inline } from '@slotted/react/inline';
+import { Text } from '@slotted/react/typography';
+
+const OUTCOMES: Record<string, string> = {
+  partial: 'Ships the 4 items in stock today.',
+  wait: 'Holds the order until every item is in stock.',
+};
+
+export default function DialogResult() {
+  const dialog = useRef<DialogHandle>(null);
+  const [outcome, setOutcome] = useState<string | null>(null);
+
+  return (
+    <Inline align="center" gap={3}>
+      <Dialog
+        ref={dialog}
+        onOpenChange={(open, request) => {
+          if (!open) {
+            setOutcome((request.result && OUTCOMES[request.result]) ?? 'Closed without a choice.');
+          }
+        }}
+      >
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Ship order SO-1182
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Two items are out of stock</DialogTitle>
+            <DialogDescription>
+              Aniseed syrup and dried pears are back in stock on 14 October.
+            </DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogFooter>
+            <Button
+              variant="outline"
+              tone="secondary"
+              onClick={() => dialog.current?.close('wait')}
+            >
+              Wait for all items
+            </Button>
+            <Button onClick={() => dialog.current?.close('partial')}>Ship 4 items now</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {outcome === null ? null : (
+        <Text size="sm" tone="muted">
+          {outcome}
+        </Text>
+      )}
+    </Inline>
+  );
+}
+```
+
+### row-action.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@slotted/react/dialog';
+import { Field, FieldLabel } from '@slotted/react/field';
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableColumnHeader,
+  TableContent,
+  TableHead,
+  TableRow,
+  TableRowHeader,
+} from '@slotted/react/table';
+import { TextField } from '@slotted/react/text-field';
+import { VisuallyHidden } from '@slotted/react/visually-hidden';
+
+const ORDERS = [
+  { id: 'SO-1182', customer: 'Contoso Foods', total: '$1,240.00', amount: '1240.00', card: '4242' },
+  { id: 'SO-1183', customer: 'Fabrikam Grocers', total: '$386.50', amount: '386.50', card: '1881' },
+  {
+    id: 'SO-1184',
+    customer: 'Tailspin Market',
+    total: '$2,075.25',
+    amount: '2075.25',
+    card: '0005',
+  },
+];
+
+type Order = (typeof ORDERS)[number];
+
+export default function DialogRowAction() {
+  const [open, setOpen] = useState(false);
+  const [order, setOrder] = useState<Order>(ORDERS[0]!);
+
+  return (
+    <>
+      <Table columns={4}>
+        <TableContent>
+          <TableHead>
+            <TableRow>
+              <TableColumnHeader>Order</TableColumnHeader>
+              <TableColumnHeader>Customer</TableColumnHeader>
+              <TableColumnHeader numeric>Total</TableColumnHeader>
+              <TableColumnHeader>
+                <VisuallyHidden>Actions</VisuallyHidden>
+              </TableColumnHeader>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {ORDERS.map((row) => (
+              <TableRow key={row.id} value={row.id}>
+                <TableRowHeader>{row.id}</TableRowHeader>
+                <TableCell>{row.customer}</TableCell>
+                <TableCell numeric>{row.total}</TableCell>
+                <TableCell>
+                  <Button
+                    aria-label={`Refund ${row.id}`}
+                    size="sm"
+                    tone="secondary"
+                    variant="ghost"
+                    onClick={() => {
+                      setOrder(row);
+                      setOpen(true);
+                    }}
+                  >
+                    Refund
+                  </Button>
+                </TableCell>
+              </TableRow>
+            ))}
+          </TableBody>
+        </TableContent>
+      </Table>
+      <Dialog open={open} onOpenChange={setOpen} size="sm">
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Refund {order.id}</DialogTitle>
+            <DialogDescription>
+              {order.customer} paid {order.total} with the card ending {order.card}.
+            </DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Field>
+              <FieldLabel>Amount in US dollars</FieldLabel>
+              <TextField key={order.id} inputMode="decimal" defaultValue={order.amount} />
+            </Field>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={() => setOpen(false)}>
+              Cancel
+            </Button>
+            <Button onClick={() => setOpen(false)}>Issue refund</Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+```
+
+### unsaved-changes.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+
+import { Button } from '@slotted/react/button';
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogIcon,
+  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 DialogUnsavedChanges() {
+  const [open, setOpen] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [address, setAddress] = useState('Pier 70, Suite 300, Seattle, WA 98121');
+  const [draft, setDraft] = useState(address);
+  const dirty = draft !== address;
+
+  const leave = () => {
+    if (dirty) setConfirming(true);
+    else setOpen(false);
+  };
+
+  return (
+    <Inline align="center" gap={3}>
+      <Dialog
+        open={open}
+        onOpenChange={(next, request) => {
+          if (next) {
+            setDraft(address);
+            setOpen(true);
+          } else if (dirty) {
+            request.cancel();
+            setConfirming(true);
+          } else {
+            setOpen(false);
+          }
+        }}
+      >
+        <DialogTrigger
+          render={(props) => (
+            <Button {...props} tone="secondary" variant="outline">
+              Change delivery address
+            </Button>
+          )}
+        />
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Delivery address</DialogTitle>
+            <DialogDescription>Applies to order SO-1182 and to later orders.</DialogDescription>
+            <DialogClose />
+          </DialogHeader>
+          <DialogBody>
+            <Field>
+              <FieldLabel>Address</FieldLabel>
+              <TextField value={draft} onValueChange={setDraft} />
+            </Field>
+          </DialogBody>
+          <DialogFooter>
+            <Button variant="ghost" tone="secondary" onClick={leave}>
+              Cancel
+            </Button>
+            <Button
+              onClick={() => {
+                setAddress(draft);
+                setOpen(false);
+              }}
+            >
+              Save address
+            </Button>
+          </DialogFooter>
+          <AlertDialog open={confirming} onOpenChange={setConfirming} tone="warning">
+            <DialogContent>
+              <DialogHeader>
+                <AlertDialogIcon />
+                <DialogTitle>Discard the new address?</DialogTitle>
+                <DialogDescription>
+                  The address you typed is not saved. The order keeps the previous one.
+                </DialogDescription>
+              </DialogHeader>
+              <DialogFooter>
+                <AlertDialogCancel
+                  render={(props) => (
+                    <Button {...props} tone="secondary" variant="outline">
+                      Keep editing
+                    </Button>
+                  )}
+                />
+                <AlertDialogAction
+                  onClick={() => setOpen(false)}
+                  render={(props) => (
+                    <Button {...props} tone="warning">
+                      Discard changes
+                    </Button>
+                  )}
+                />
+              </DialogFooter>
+            </DialogContent>
+          </AlertDialog>
+        </DialogContent>
+      </Dialog>
+      <Text size="sm" tone="muted">
+        {address}
+      </Text>
+    </Inline>
+  );
+}
+```