@uniflowed/ui 0.0.0-alpha.18 → 0.0.0-alpha.37

package/index.js

@@ -32,6 +32,105 @@
 // A library written in TypeScript can document those constraints; it cannot
 // state them.
 //
+// # The copy step copies the look, never the behaviour
+//
+// shadcn's product is not a component. It is `npx shadcn add dialog`, which
+// writes the source into your repository so that you own it and change it —
+// and around that sit `init`, `view`, `search`, `build`, `migrate`, `eject`, an
+// MCP server, a `components.json` and a registry format anybody can publish to.
+// The roadmap first answered that with "typed imports, preset styles, and
+// **no copy step**", and ubugeeei-prod/uf#303 is where the answer was argued.
+// ubugeeei-prod/uf#947 kept half of it and reversed the other half, and the
+// half it kept is this package.
+//
+// **Why this package is still never copied.** A copy is a fork with no
+// upstream, and four things follow. A focus trap fixed here reaches everyone
+// who upgrades and reaches nobody who copied. The composition constraints above
+// are checked *across the boundary*: `Tabs.List` declaring `renders* Tabs.Tab`
+// means something while the library is imported and means nothing once the
+// source has been pasted into an application, because then it is the
+// application's own component and Flow has nothing left to hold it to.
+// `sideEffects: false` and one module per primitive already give a bundler
+// everything a copy would. And the accessibility work stays in one place with
+// one suite over it, rather than in every consumer's repository at the version
+// they took it at.
+//
+// **What `uf ui add` copies instead.** The styled layer. `uf ui add dialog`
+// writes `app/components/ui/dialog.js`, which imports its parts from
+// `@uniflowed/ui` and owns the scrim, the spacing and the tone of the
+// trigger — what a person means when they say "our dialog". None of the four
+// arguments above is reopened by it, because none of them is about the look:
+// the focus trap still arrives by upgrade, and the copied `TabsList` still takes
+// `renders* TabsTab` over a `TabsTab` that renders this package's tab, so the
+// constraint holds in the application's own file. `crates/uf_ui`'s header is
+// the decision in full.
+//
+// **What a caller gets without copying anything.** The reason people copy
+// is to change the markup, so that has to be answered or this is a worse
+// library for the same use. The answer is `render`, which every part that
+// renders an element of its own is growing:
+//
+//     <Menu.Item render={(props) => <a href="/settings" {...props} />}>
+//       Settings
+//     </Menu.Item>
+//
+// The part computes every attribute, every id, every composed handler and every
+// ref exactly as it would have, and hands them to the caller to put on their
+// own element; `children` is among them, so a caller who spreads and
+// self-closes still gets what was written between the tags. What it does *not*
+// hand over is anything true of the element rather than of the part —
+// `type="button"` stays on the `<button>` branch.
+//
+// It is deliberately not Radix's `asChild`. Cloning a child hides which props
+// arrived and in what order; a function is handed the object, so a caller can
+// read it, order it themselves, and drop one on purpose. And the part is still
+// the part: `Menu.Body`'s `renders*` still rejects a `<div>` where a
+// `Menu.Item` belongs, because a `Menu.Item` rendered as an `<a>` is a
+// `Menu.Item`. That is the half a copied source cannot keep, and it is what
+// makes leaving this package uncopied a trade rather than a loss.
+//
+// **Where it is, today.** Every fixed-element part has it in `Accordion`,
+// `Alert`, `AlertDialog`, `Avatar`, `Breadcrumb`, `Collapsible`, `Dialog`,
+// `Drawer`, `Menu`, `ContextMenu`, `Menubar`, `Pagination`, `Popover`, `Sheet`,
+// `Skeleton`, `Slider`, `Table`, `Tabs` and `ToggleGroup`; so do the
+// single-part `Checkbox`, `Progress`, `Separator`, `Switch` and `Toggle`.
+// `Field.Root`, `Field.Label`, `Field.Control`, `Field.Description`,
+// `Field.Status` and `Field.Error` take it too, as do `RadioGroup`,
+// `InputOtp.Separator`, `Tooltip.Trigger`, `Tooltip.Body`,
+// `HoverCard.Trigger`, `HoverCard.Body` and `Sidebar.Item`. A documented
+// escape hatch that is not there is worse than an undocumented one that is, so
+// the state of every part is a table in `packages/ui/ui.test.js` rather than a
+// claim in this paragraph: it names each part as implemented, no-element, or
+// fixed remainder, and the suite holds the lists to the exported files. A part
+// added to this barrel is in none of them and the suite says so.
+//
+// **Are the `internal/` modules ever public?** No, and the consequence is
+// worth stating rather than leaving as an omission. `merge-props.js`,
+// `roving-focus.js`, `controlled-state.js` and the rest each explain in their
+// own header why exporting them would publish a weaker promise than the
+// components make — a consumer who could reach `merge-props.js` could build a
+// part that spreads `rest` last, which is the failure it exists to prevent. So
+// there is no third-party primitive that participates the way these do, and no
+// registry of them: the uf-shaped equivalent of publishing a component is a
+// pull request against this package, where its keyboard map gets the same suite
+// as everything else. That is a real cost of the decision and the right side of
+// it for a library whose value is that the hard parts are correct. What a third
+// party *can* build on is the escape hatch itself, which is the whole public
+// surface it needs: a component of theirs given to `render` receives the props
+// this package would have used, and their own composition sits inside a part
+// that is still checked.
+//
+// **What the CLI adds.** `uf ui add`, `uf ui list` and `uf ui diff`, over a
+// registry of styled components in `registry/ui/` that is embedded into the
+// binary — each one built on parts exported here, and none of them a copy of
+// one. There is still no registry of *primitives*, for the reason the previous
+// paragraph gives, and there is no `components.json`: `uf.config.js` is the one
+// configuration surface by design, so a UI option belongs there rather than in
+// a second file. The affordance `shadcn view` has — "tell me what this
+// component is made of" — is still `uf inspect --json` for the parts, out of
+// `crates/uf_lib/src/ui.rs`, which `cargo test -p uf_lib` holds to this barrel
+// in both directions.
+//
 // # Styling is a default, not a dependency
 //
 // Nothing here imports StyleX, and nothing here has a StyleX-shaped type. A
@@ -76,14 +175,33 @@
 // are `Declined` with the preset functions that replace them named on each,
 // and `cargo test -p uf_lib` fails if a name there stops existing.
 //
-// Five of that twenty are not presentational and are missing rather than
-// declined — Alert, Avatar, Breadcrumb, Separator and Skeleton — each for one
-// specific reason, and the registry entry for each says which. The shortest is
-// Alert: `role="alert"` is a live region, an element already in the document
-// when the page loads announces on insertion or not at all, and a permanently
-// rendered "your trial ends soon" box carrying that role is either an
-// interruption on every page load or silence. `field.js` already makes that
-// call correctly for `Field.Error`.
+// Five of that twenty are on the other side of the line and now ship — Alert,
+// Avatar, Breadcrumb, Separator and Skeleton — each for one specific reason,
+// and each of them one or two elements:
+//
+// - **Alert** is the one whose usual shape is arguably wrong to copy.
+//   `role="alert"` is a live region, an element already in the document when
+//   the page loads announces on insertion or not at all, and a permanently
+//   rendered "your trial ends soon" box carrying that role is either an
+//   interruption on every page load or silence. So the role is behind `live`,
+//   and a static callout does not get one. `field.js` already makes that call
+//   correctly for `Field.Error`.
+// - **Avatar** is a three-state machine — loading, loaded, failed — with the
+//   fallback held back so a cached image does not flash somebody's initials,
+//   and with `alt=""` by default, because an avatar beside a name that puts
+//   the name in `alt` makes every screen reader say it twice.
+// - **Breadcrumb** is `Pagination`'s shape one door along: a named `<nav>`, one
+//   `aria-current="page"`, and separators hidden so the trail is not read as
+//   "Home slash Settings slash Billing".
+// - **Separator** is two lines with one decision in them, and it is the
+//   decision `Progress` is: `role="separator"` with an `aria-orientation` for a
+//   boundary a reader should be told about, `aria-hidden` for a rule that is
+//   only a rule.
+// - **Skeleton** is the one that silently makes a page worse. A screen of
+//   skeletons is a screen of empty boxes, so the boxes are `aria-hidden`, the
+//   region they stand in is `aria-busy`, and a live region that was empty for
+//   one commit says "Loading" — which is #289's rule met at the moment it bites
+//   hardest, because a skeleton screen is busy on its very first render.
 //
 // # What these components promise React
 //
@@ -103,20 +221,9 @@
 //
 // One component does use it, and it is the case the API is actually for.
 // `toast("Saved")` is called from an event handler or a `catch`, so the queue
-// of notifications lives outside React — a store at module scope in
-// `toast.js`, read through `useSyncExternalStore` with the cached immutable
-// snapshots and the consistent server snapshot that requires. A queue is a
-// store; the DOM is not.
-//
-// That store should be an atom in `@uniflowed/state`, and was one. It is
-// written out by hand in `toast.js` because `@uniflowed/ui` is published to
-// npm and `@uniflowed/state` is not: its name has never been bound, and
-// binding it takes a person with an `npm login` session and a 2FA prompt —
-// ubugeeei-prod/uf#210. A published package whose dependency is missing
-// installs as nothing, `ETARGET` on the first thing a user types, so this
-// package cannot declare that dependency until the name exists. The queue
-// moves back to `@uniflowed/state` when #210 binds it. The local store is the
-// shippable design, not the better one.
+// of notifications lives outside React — an atom in `@uniflowed/state`, read
+// through `useSyncExternalStore` with the cached immutable snapshots and the
+// consistent server snapshot that requires. A queue is a store; the DOM is not.
 //
 // # Server and client
 //
@@ -184,11 +291,23 @@
 //   a dialog that is not modal, a tooltip describes its trigger and may never
 //   take focus, a hover card is neither and holds links — and because a flag
 //   selecting between them would be one flag every behaviour had to read.
+// - `alert.js`, `avatar.js`, `breadcrumb.js`, `separator.js` and `skeleton.js`
+//   — the five above that look like a class list and are not. One or two
+//   elements each, and one conditional each: whether a callout announces
+//   itself, which of three states an image is in, whether the last crumb is a
+//   link, whether a rule is in the accessibility tree, and whether anybody is
+//   told the page is loading.
+// - `interactions.js` — the press, the hover, the focus ring, the long press,
+//   the drag and the key, and the one module here that exports hooks rather
+//   than parts. A press that is released outside does not press, a hover is
+//   never a finger's, a ring is drawn for the keyboard and not for the pointer,
+//   and a screen reader's click is a press; its header says what each rule
+//   prevents and where it differs from React Aria's.
 //
-// Every name below is exported from one of those, so a consumer may import
-// `@uniflowed/ui` or `@uniflowed/ui/dialog` and get the same thing. The split
-// is by primitive because that is the unit a reader looks for, the unit a
-// bundler drops, and the unit the WAI-ARIA practices are written in.
+// Every name below is exported from one of those, and this file is the only way
+// to import any of them: `package.json` exports it alone. The split is by
+// primitive because that is the unit a reader looks for, the unit a bundler
+// drops, and the unit the WAI-ARIA practices are written in.
 //
 // `internal/` holds ten modules and nothing else, each a rule the primitives
 // must apply identically and a consumer must not be able to apply differently:
@@ -217,6 +336,7 @@ import {
   AccordionRoot,
   AccordionTrigger,
 } from "./accordion.js";
+import { AlertDescription, AlertRoot, AlertTitle } from "./alert.js";
 import {
   AlertDialogAction,
   AlertDialogBody,
@@ -229,6 +349,15 @@ import {
   AlertDialogTitle,
   AlertDialogTrigger,
 } from "./alert-dialog.js";
+import { AvatarFallback, AvatarImage, AvatarRoot } from "./avatar.js";
+import {
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbRoot,
+  BreadcrumbSeparator,
+} from "./breadcrumb.js";
 import {
   CarouselContent,
   CarouselItem,
@@ -287,7 +416,14 @@ import {
   DrawerTitle,
   DrawerTrigger,
 } from "./drawer.js";
-import { FieldControl, FieldDescription, FieldError, FieldLabel, FieldRoot } from "./field.js";
+import {
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  FieldRoot,
+  FieldStatus,
+} from "./field.js";
 import { HoverCardBody, HoverCardRoot, HoverCardTrigger } from "./hover-card.js";
 import { InputOtpGroup, InputOtpRoot, InputOtpSeparator, InputOtpSlot } from "./input-otp.js";
 import {
@@ -336,6 +472,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "./select.js";
+import { Separator } from "./separator.js";
 import {
   SheetBody,
   SheetClose,
@@ -355,6 +492,7 @@ import {
   SidebarRoot,
   SidebarTrigger,
 } from "./sidebar.js";
+import { SkeletonBox, SkeletonRoot } from "./skeleton.js";
 import { SliderRange, SliderRoot, SliderThumb, SliderTrack } from "./slider.js";
 import { Switch } from "./switch.js";
 import {
@@ -387,6 +525,7 @@ import { ToggleGroupItem, ToggleGroupRoot } from "./toggle-group.js";
 import { TooltipBody, TooltipProvider, TooltipRoot, TooltipTrigger } from "./tooltip.js";
 
 export type { AccordionType } from "./accordion.js";
+export type { AvatarStatus } from "./avatar.js";
 // A date, however a caller had one to hand: a `PlainDate` from
 // `@uniflowed/temporal`, or the ISO 8601 string a form field or a URL carries.
 export type { DateValue } from "./calendar.js";
@@ -397,7 +536,11 @@ export type { DialogRole } from "./dialog.js";
 // Which edge of the viewport a sheet or a drawer is attached to. `Sidebar` has
 // its own two-member union, because a sidebar is never on the top or bottom.
 export type { Edge } from "./sheet.js";
+export type { FieldSource } from "./field.js";
 export type { InputOtpKind } from "./input-otp.js";
+export type { MenuSelect } from "./menu.js";
+// Which way a carousel, a scroll area or a separator runs.
+export type { Orientation } from "./separator.js";
 export type { SidebarSide } from "./sidebar.js";
 // Where an anchored overlay opens, for a caller who holds one in a variable or
 // a prop of their own. Unions rather than strings, so `side="botom"` is a type
@@ -410,7 +553,212 @@ export type { Sort } from "./table.js";
 export type { Notification, ToastChanges, ToastOptions, Urgency } from "./toast.js";
 export type { ToggleGroupType } from "./toggle-group.js";
 
-export { Checkbox, Progress, Switch, Toggle };
+/**
+ * Every part, under the name its module gives it.
+ *
+ * This file is the only entry point the package has — `package.json` exports
+ * `.` and nothing else — so a name a module exports and this list leaves out is
+ * a name nobody can import. The namespaces below are the same parts spelled for
+ * composing a page (`Dialog.Root`); these are for the wrapper, the preset and
+ * the test that want one part (`import { DialogRoot } from "@uniflowed/ui"`).
+ * `sideEffects: false` lets a bundler keep the module a name comes from and drop
+ * the rest, and `uf_rsc` names that module, not the package, as the client
+ * boundary of a Server Component that imports the name.
+ */
+export {
+  AccordionContent,
+  AccordionHeader,
+  AccordionItem,
+  AccordionRoot,
+  AccordionTrigger,
+  AlertDescription,
+  AlertDialogAction,
+  AlertDialogBody,
+  AlertDialogCancel,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogOverlay,
+  AlertDialogRoot,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  AlertRoot,
+  AlertTitle,
+  AvatarFallback,
+  AvatarImage,
+  AvatarRoot,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbRoot,
+  BreadcrumbSeparator,
+  CalendarDay,
+  CalendarMonth,
+  CalendarNext,
+  CalendarPrevious,
+  CalendarRoot,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPause,
+  CarouselPrevious,
+  CarouselRoot,
+  CollapsibleContent,
+  CollapsibleRoot,
+  CollapsibleTrigger,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxGroupLabel,
+  ComboboxInput,
+  ComboboxLabel,
+  ComboboxList,
+  ComboboxOption,
+  ComboboxRoot,
+  ComboboxStatus,
+  ContextMenuRoot,
+  ContextMenuTrigger,
+  DatePickerCalendar,
+  DatePickerInput,
+  DatePickerRoot,
+  DatePickerTrigger,
+  DialogBody,
+  DialogClose,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogRoot,
+  DialogTitle,
+  DialogTrigger,
+  DrawerBody,
+  DrawerClose,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHandle,
+  DrawerHeader,
+  DrawerOverlay,
+  DrawerRoot,
+  DrawerTitle,
+  DrawerTrigger,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  FieldRoot,
+  FieldStatus,
+  HoverCardBody,
+  HoverCardRoot,
+  HoverCardTrigger,
+  InputOtpGroup,
+  InputOtpRoot,
+  InputOtpSeparator,
+  InputOtpSlot,
+  MenuBody,
+  MenuCheckboxItem,
+  MenuGroup,
+  MenuItem,
+  MenuLabel,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuRoot,
+  MenuSeparator,
+  MenuSub,
+  MenuSubTrigger,
+  MenuTrigger,
+  MenubarMenu,
+  MenubarRoot,
+  MenubarTrigger,
+  NavigationMenuBody,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuRoot,
+  NavigationMenuTrigger,
+  PaginationContent,
+  PaginationItem,
+  PaginationNext,
+  PaginationPrevious,
+  PaginationRoot,
+  PopoverBody,
+  PopoverRoot,
+  PopoverTrigger,
+  RadioGroupIndicator,
+  RadioGroupItem,
+  RadioGroupRoot,
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+  ScrollAreaRoot,
+  ScrollAreaScrollbar,
+  ScrollAreaViewport,
+  SelectGroup,
+  SelectGroupLabel,
+  SelectLabel,
+  SelectList,
+  SelectOption,
+  SelectRoot,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+  SheetBody,
+  SheetClose,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetOverlay,
+  SheetRoot,
+  SheetTitle,
+  SheetTrigger,
+  SidebarBody,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarItem,
+  SidebarRoot,
+  SidebarTrigger,
+  SkeletonBox,
+  SkeletonRoot,
+  SliderRange,
+  SliderRoot,
+  SliderThumb,
+  SliderTrack,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRoot,
+  TableRow,
+  TableRowHeader,
+  TableRowSelect,
+  TableSelectAll,
+  TabsList,
+  TabsPanel,
+  TabsRoot,
+  TabsTab,
+  ToastAction,
+  ToastClose,
+  ToastDescription,
+  ToastRegion,
+  ToastRoot,
+  ToastTitle,
+  ToggleGroupItem,
+  ToggleGroupRoot,
+  TooltipBody,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+};
+
+/**
+ * The five that are one component rather than a namespace of parts.
+ *
+ * Each takes `render`, so the control or line a design system already has — a
+ * `<div>` with a knob drawn in it, somebody's `<Pressable>`, a presentational
+ * meter shell — keeps the role, state, keys and attributes while being their
+ * element. See the module headers and the table in `packages/ui/ui.test.js`.
+ */
+export { Checkbox, Progress, Separator, Switch, Toggle };
 
 /**
  * Queueing a notification, from anywhere.
@@ -425,6 +773,72 @@ export { Checkbox, Progress, Switch, Toggle };
  */
 export { dismissAllToasts, dismissToast, toast, updateToast };
 
+/**
+ * The interactions every part here is made of, for a control of the caller's own.
+ *
+ * `usePress` is a press from a pointer, a key or assistive technology, with one
+ * set of events; `useHover` is a mouse's and a pen's and never a finger's;
+ * `useFocusRing` draws a ring for keyboard focus and not for pointer focus;
+ * `useLongPress`, `useMove` and `useKeyboard` are the rest; `mergeProps` puts
+ * several of them on one element. `interactions.js` says what each one gets
+ * right, and where it differs from React Aria's, at length.
+ *
+ *     const { isPressed, pressProps } = usePress({ onPress: save });
+ *     const { focusProps, isFocusVisible } = useFocusRing();
+ *     <div {...mergeProps(pressProps, focusProps)} role="button" tabIndex={0} />
+ *
+ * Hooks rather than parts, and the one module here that exports them: its rules
+ * are about input devices rather than about markup this package builds, so a
+ * control written with them is the same control a part is rather than a weaker
+ * copy of one.
+ */
+export {
+  getInteractionModality,
+  mergeProps,
+  useFocusRing,
+  useFocusVisible,
+  useHover,
+  useInteractionModality,
+  useKeyboard,
+  useLongPress,
+  useMove,
+  usePress,
+} from "./interactions.js";
+export type {
+  FocusRingOptions,
+  FocusRingProps,
+  FocusRingResult,
+  FocusVisibleResult,
+  HoverEvent,
+  HoverOptions,
+  HoverProps,
+  HoverResult,
+  InteractionEvent,
+  InteractionProps,
+  KeyboardInteraction,
+  KeyboardOptions,
+  KeyboardProps,
+  KeyboardResult,
+  LongPressEvent,
+  LongPressOptions,
+  LongPressProps,
+  LongPressResult,
+  Modality,
+  MoveEndEvent,
+  MoveMoveEvent,
+  MoveOptions,
+  MovePointerType,
+  MoveProps,
+  MoveResult,
+  MoveStartEvent,
+  PhysicalPointer,
+  PointerType,
+  PressEvent,
+  PressOptions,
+  PressProps,
+  PressResult,
+} from "./interactions.js";
+
 /**
  * An accessible form field.
  *
@@ -432,14 +846,16 @@ export { dismissAllToasts, dismissToast, toast, updateToast };
  *     <Field.Label>Email</Field.Label>
  *     <Field.Control render={(props) => <input type="email" {...props} />} />
  *     <Field.Description>We will not share it.</Field.Description>
+ *     <Field.Status>{saving ? "Saving…" : ""}</Field.Status>
  *     <Field.Error>{error}</Field.Error>
  *   </Field.Root>
  *
  * Inside a form, `field` replaces the hand-written `invalid`: the form says
  * whether the field is wrong and what the message is, and the field composes
- * every `aria-*` from that in one place. `@uniflowed/form`'s `useFieldSource`
- * is what produces one, and `field.js`'s header says why the hook lives there
- * rather than here.
+ * every `aria-*` from that in one place. It also marks the control busy during
+ * submit, validation, or async default loading. `@uniflowed/form`'s
+ * `useFieldSource` is what produces one, and `field.js`'s header says why the
+ * hook lives there rather than here.
  *
  *   const email = useFieldSource(form, "email", { required: "We need one" });
  *   <Field.Root field={email}>…<Field.Error /></Field.Root>
@@ -454,6 +870,7 @@ export const Field = {
   Label: FieldLabel,
   Control: FieldControl,
   Description: FieldDescription,
+  Status: FieldStatus,
   Error: FieldError,
 };
 
@@ -471,6 +888,11 @@ export const Field = {
  *     <Tabs.Panel value="one">…</Tabs.Panel>
  *     <Tabs.Panel value="two">…</Tabs.Panel>
  *   </Tabs.Root>
+ *
+ * Every part takes `render`, so a tab that is also a route — `<Tabs.Tab
+ * render={(props) => <a href="#billing" {...props} />}>` — is still a tab, with
+ * the roving tab stop and the `aria-controls` a tab has. `Tabs.List`'s
+ * `renders* Tabs.Tab` is unaffected, because it is the *part* it constrains.
  */
 export const Tabs = {
   Root: TabsRoot,
@@ -603,6 +1025,12 @@ export const ToggleGroup = {
  *       </Dialog.Footer>
  *     </Dialog.Body>
  *   </Dialog.Root>
+ *
+ * Every part takes `render`. `Dialog.Title` is an `<h2>` by default and the
+ * level is a fact about the page around it rather than about the dialog, so
+ * `render={(props) => <h3 {...props} />}` is how a caller says which — without
+ * losing the id `aria-labelledby` points at. `AlertDialog`, `Sheet` and
+ * `Drawer` are made of these parts and pass `render` straight through.
  */
 export const Dialog = {
   Root: DialogRoot,
@@ -828,6 +1256,17 @@ export const InputOtp = {
  *       </Menu.Sub>
  *     </Menu.Body>
  *   </Menu.Root>
+ *
+ * Every part takes `render`, which is what makes a menu of links possible — and
+ * a menu of links is the most ordinary menu there is:
+ *
+ *   <Menu.Item render={(props) => <a href="/settings" {...props} />}>
+ *     Settings
+ *   </Menu.Item>
+ *
+ * The `<a>` keeps the middle click, the context menu and the status bar; the
+ * item keeps the role, the id, the roving tab stop and the press that closes
+ * the tree. See the module header for why that is the answer to "no copy step".
  */
 export const Menu = {
   Root: MenuRoot,
@@ -1242,3 +1681,100 @@ export const Pagination = {
   Previous: PaginationPrevious,
   Next: PaginationNext,
 };
+
+/**
+ * The trail above the page, read as places rather than as punctuation.
+ *
+ *   <Breadcrumb.Root>
+ *     <Breadcrumb.List>
+ *       <Breadcrumb.Item>
+ *         <Breadcrumb.Link href="/">Home</Breadcrumb.Link>
+ *       </Breadcrumb.Item>
+ *       <Breadcrumb.Separator>/</Breadcrumb.Separator>
+ *       <Breadcrumb.Item>
+ *         <Breadcrumb.Page>Billing</Breadcrumb.Page>
+ *       </Breadcrumb.Item>
+ *     </Breadcrumb.List>
+ *   </Breadcrumb.Root>
+ *
+ * `Pagination`'s shape one door along: a `<nav>` with a name, one
+ * `aria-current="page"`, and the separators out of the accessibility tree so
+ * the trail is not announced as "Home slash Settings slash Billing". The last
+ * crumb is a `Breadcrumb.Page` and not a link, because it is where the reader
+ * already is.
+ */
+export const Breadcrumb = {
+  Root: BreadcrumbRoot,
+  List: BreadcrumbList,
+  Item: BreadcrumbItem,
+  Link: BreadcrumbLink,
+  Page: BreadcrumbPage,
+  Separator: BreadcrumbSeparator,
+};
+
+/**
+ * A callout, and the `live` that decides whether anybody is interrupted by it.
+ *
+ *   <Alert.Root>
+ *     <Alert.Title>Your trial ends on Friday</Alert.Title>
+ *     <Alert.Description>Add a card to keep your projects.</Alert.Description>
+ *   </Alert.Root>
+ *
+ *   {error != null && (
+ *     <Alert.Root live>
+ *       <Alert.Title>Could not save</Alert.Title>
+ *       <Alert.Description>{error}</Alert.Description>
+ *     </Alert.Root>
+ *   )}
+ *
+ * The first has no role at all: it was there when the page loaded, so a live
+ * region would announce it on every load or never, and neither is what anybody
+ * wanted. The second appeared because something happened, which is what
+ * `role="alert"` is for. `alert.js`'s header says why there is no polite
+ * version of this and why `Toast` is that instead.
+ */
+export const Alert = {
+  Root: AlertRoot,
+  Title: AlertTitle,
+  Description: AlertDescription,
+};
+
+/**
+ * A picture of a person, and the two states it is not in yet.
+ *
+ *   <Avatar.Root>
+ *     <Avatar.Image src={person.photo} />
+ *     <Avatar.Fallback>{initials(person.name)}</Avatar.Fallback>
+ *   </Avatar.Root>
+ *
+ * The fallback is absent while the image is loading and present once it has
+ * failed, held back long enough that a cached image never flashes initials.
+ * `alt` defaults to `""`, because an avatar beside the name it belongs to is
+ * decorative and a component that helpfully puts the name there makes every
+ * screen reader say it twice; pass `alt` where the picture is the only thing
+ * identifying the person.
+ */
+export const Avatar = {
+  Root: AvatarRoot,
+  Image: AvatarImage,
+  Fallback: AvatarFallback,
+};
+
+/**
+ * The grey boxes, and the sentence that stops them being an empty page.
+ *
+ *   <Skeleton.Root busy={pending}>
+ *     {pending ? <Skeleton.Box /> : <Invoices rows={invoices} />}
+ *   </Skeleton.Root>
+ *
+ * The boxes are `aria-hidden`, the region is `aria-busy`, and a live region
+ * that was mounted empty for a commit says "Loading" — a skeleton screen is
+ * busy on its first render, so a region rendered with its message already in it
+ * announces nothing at all. Keep the root mounted across the load and toggle
+ * `busy`; unmounting it takes the region away before it can say the wait is
+ * over.
+ */
+export const Skeleton = {
+  Root: SkeletonRoot,
+  Box: SkeletonBox,
+};