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

package/dist/docs/app-shell.md

@@ -0,0 +1,200 @@
+<!-- index: ./index.md -->
+# app-shell
+
+`data-ui="app-shell"` · Application frame with header, nav, main and aside.
+
+## Import
+
+```tsx
+import {
+  AppShell,
+  AppShellActions,
+  AppShellAside,
+  AppShellAsideBody,
+  AppShellAsideFooter,
+  AppShellAsideHeader,
+  AppShellAsideResizer,
+  AppShellAsideToggle,
+  AppShellBanner,
+  AppShellBrand,
+  AppShellCentre,
+  AppShellDefaultsProvider,
+  AppShellFooter,
+  AppShellMain,
+  AppShellNav,
+  AppShellNavBody,
+  AppShellNavFooter,
+  AppShellNavHeader,
+  AppShellNavRail,
+  AppShellNavToggle,
+  AppShellProgress,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import {
+  AppShell,
+  AppShellBanner,
+  AppShellBrand,
+  AppShellMain,
+  AppShellNav,
+  AppShellNavToggle,
+} from '@slotted/react/app-shell';
+import {
+  SideNavigation,
+  SideNavigationItem,
+  SideNavigationLabel,
+  SideNavigationLink,
+  SideNavigationList,
+} from '@slotted/react/side-navigation';
+
+export default function AppShellBasic() {
+  return (
+    <AppShell>
+      <AppShellBanner>
+        <AppShellNavToggle />
+        <AppShellBrand>Northwind</AppShellBrand>
+      </AppShellBanner>
+      <AppShellNav>
+        <SideNavigation aria-label="Main navigation" defaultValue="orders">
+          <SideNavigationList>
+            <SideNavigationItem value="orders">
+              <SideNavigationLink href="/orders">
+                <SideNavigationLabel>Orders</SideNavigationLabel>
+              </SideNavigationLink>
+            </SideNavigationItem>
+            <SideNavigationItem value="customers">
+              <SideNavigationLink href="/customers">
+                <SideNavigationLabel>Customers</SideNavigationLabel>
+              </SideNavigationLink>
+            </SideNavigationItem>
+          </SideNavigationList>
+        </SideNavigation>
+      </AppShellNav>
+      <AppShellMain>
+        <h1>Orders</h1>
+      </AppShellMain>
+    </AppShell>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `skip` | div holding one a per region | no |
+| `banner` | header, or the element render returns | no |
+| `brand` | div | no |
+| `centre` | div | no |
+| `actions` | div | no |
+| `nav-toggle` | button, or the element render returns | no |
+| `nav` | nav, or the element render returns | no |
+| `nav-rail` | div, or the element render returns | no |
+| `nav-header` | div | no |
+| `nav-body` | div | no |
+| `nav-footer` | div | no |
+| `scrim` | div | no |
+| `main` | main with tabindex="-1", or the element render returns | yes |
+| `progress` | div, holding one ProgressBar at placement="edge-start" | no |
+| `aside` | aside, or the element render returns | no |
+| `aside-resizer` | div with role="separator", or the element render returns | no |
+| `aside-header` | div | no |
+| `aside-body` | div | no |
+| `aside-footer` | div | no |
+| `aside-toggle` | button, or the element render returns | no |
+| `footer` | footer, or the element render returns | no |
+| `layer` | div with display: contents | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `navOpen` | `boolean` | — | AppShell | The controlled value of the navigation region. Passing anything but undefined puts the shell in controlled mode for its lifetime, and it then reports and waits rather than moving itself |
+| `defaultNavOpen` | `boolean` | true | AppShell | The uncontrolled starting value, read once. A later change to it does not silently become new state |
+| `asideOpen` | `boolean` | — | AppShell | The controlled value of the secondary pane, under the same rule. A product that opens the pane on a selection passes the selection down as this |
+| `defaultAsideOpen` | `boolean` | true | AppShell | The uncontrolled starting value of the pane. A product that projects a pane wants to see it, so the default is open |
+| `asideExtent` | `number \| undefined` | — | AppShell | The controlled measure of the pane as a column, as a fraction of the shell’s inline size. Unset, asideSize decides. The pane writes it as --slotted-app-shell-aside-extent in cqi, which the stylesheet reads in the column alone: a layer keeps its step |
+| `defaultAsideExtent` | `number \| undefined` | — | AppShell | The uncontrolled starting measure, read once. Unset, the pane starts on its asideSize step |
+| `minAsideExtent` | `number` | 0.16 | AppShell | The smallest fraction of the shell the reader may give the pane, and Home’s target. aria-valuemin is this times a hundred |
+| `maxAsideExtent` | `number` | 0.6 | AppShell | The largest fraction, and End’s target. aria-valuemax is this times a hundred |
+| `inset` | `'none' \| undefined` | — | AppShellAsideBody | none drops the body’s own padding, for content that brings its own inset. Written as data-inset |
+| `primary` | `'banner' \| 'nav' \| 'main'` | banner | AppShell, AppShellDefaultsProvider | Which region reaches the corner. Under nav the navigation spans every row and its head takes the banner’s height so the two marks sit on one line; under main it does too, and the banner stands inside the card that holds the content |
+| `canvas` | `'inset' \| 'flush' \| 'floating' \| 'panel'` | inset | AppShell, AppShellDefaultsProvider | The plane of every region at once. inset: content and pane as cards over a sunken frame. flush: every region edge to edge, seams drawn. floating: the column a card as well. panel: column, content and pane in one card, the bar and the footer on the frame |
+| `navMode` | `'inline' \| 'overlay' \| 'auto'` | auto | AppShell, AppShellDefaultsProvider | How the region occupies space. auto is inline at or above 600 pixels of the shell’s own inline size and overlay below it, answered in CSS for the layout and in script for the keyboard |
+| `asideMode` | `'inline' \| 'overlay' \| 'auto'` | auto | AppShell, AppShellDefaultsProvider | How the pane occupies space: the navigation’s pair, resolved on the same width. inline is a column beside the content, or a row under it when there is no room; overlay is a layer from the end the navigation is not on |
+| `navSide` | `'start' \| 'end'` | start | AppShell, AppShellDefaultsProvider | Which end of the line the region sits at. Logical, so a right-to-left document mirrors the whole frame; the pane sits at the other end, and both controls turn their marks |
+| `navSize` | `'sm' \| 'md' \| 'lg'` | md | AppShell, AppShellDefaultsProvider | The width of the open region, as a step on the family’s own scale. A theme retunes the step; nothing retunes a pixel string |
+| `asideSize` | `'sm' \| 'md' \| 'lg'` | md | AppShell, AppShellDefaultsProvider | The width of the secondary pane, on the same kind of scale |
+| `collapsedTo` | `'rail' \| 'hidden'` | rail | AppShell, AppShellDefaultsProvider | What a closed inline navigation leaves behind. rail keeps a strip the width of a target and keeps the tab order; hidden takes the region out of both. A closed pane always leaves nothing: it has no marks to keep |
+| `scroll` | `'content' \| 'document'` | content | AppShell, AppShellDefaultsProvider | content makes the shell the height it was given, capped at 100dvh, and only the content column and the pane’s body scroll; document lets the shell grow and the banner travel with it |
+| `separation` | `'rule' \| 'tone'` | rule | AppShell, AppShellDefaultsProvider | What draws a seam where two regions touch without a gutter. rule is a line; tone is a ground of its own on the chrome regions, with the subtle tones inside them recomputed from it. Where a gutter separates, it draws nothing either way |
+| `modal` | `boolean` | true | AppShell, AppShellDefaultsProvider | Whether an overlaid region contains focus and makes every other region inert. Only the overlaid modes read it, and it applies to whichever layer is open |
+| `escape` | `'close' \| 'none'` | close | AppShell, AppShellDefaultsProvider | Whether Escape closes an overlaid region. Registered in the capture phase by @slotted/core/dismissable-layer, so a handler inside the panel runs after the layer has already asked |
+| `outsidePress` | `'close' \| 'none'` | close | AppShell, AppShellDefaultsProvider | Whether a press outside an overlaid panel closes it |
+| `back` | `'close' \| 'none'` | close | AppShell, AppShellDefaultsProvider | The platform's way back — a phone's gesture, a browser's button — closes the layer instead of leaving the page, while it is modal: @slotted/core/dismissable-layer holds one history entry per modal layer and answers the popstate that leaves it with the reason back |
+| `closeOnNavigate` | `boolean` | true | AppShell, AppShellDefaultsProvider | Whether a click on an a[href] inside the overlaid navigation closes it, with the reason select — a router’s preventDefault included, an aria-disabled link excluded. Without it a phone costs two taps per destination |
+| `messages` | `Partial<AppShellMessages>` | — | AppShell | Words laid over the language in force, key by key — aside, close, closeAside, nav, open, openAside, progress, resizeAside, skipToAside, skipToMain, skipToNav: the two regions’ accessible names, the two controls’ labels in each state, the wait’s name, the pane edge’s name, and the three skip links. An aria-label written on the part itself still wins |
+| `loading` | `boolean` | true | AppShellProgress | Whether the next page is on its way. The bar appears once it has lasted delay (200 ms), stays at least minDuration (400 ms), and main carries aria-busy for exactly that long. Every other ProgressBar prop but placement passes through — value for a wait that reports its fraction, tone, label, size (sm by default) — and a value set through ProgressIndicatorDefaultsProvider wins over the shell’s timing |
+| `children` | `anything` | — | every region | The family owns where a region is drawn, its landmark, its width and its state, and nothing about what is in it. The bar’s three clusters, the column’s three ends, the content, the pane’s three parts and the footer each take whatever an application puts there — its own search, its own account, another family, its own markup |
+| `published geometry` | `--slotted-app-shell-row-*` | — | anything inside a region | Six numbers the shell publishes for the rows a product brings: row-inset, row-mark, row-gap, row-height, row-font-size and row-line-height. Every row on this page reads them and states nothing of its own, which is what keeps a destination’s mark under the control in the bar |
+| `custom properties` | `--slotted-app-shell-*` | — | the frame or any region | A ground and an ink per region, plus every measure the frame stands on. Each region reads the public name and falls back to the plane’s default, so a property written on the region resolves in the region’s own scope. The full list is under Theme-owned decisions below |
+| `data-part selectors` | `[data-ui="app-shell"] [data-part="…"]` | — | every part | Anything the properties do not reach is one selector away. [data-ui="app-shell"][data-open] is the navigation; [data-part="aside"][data-open] is the pane |
+| `render` | `(props) => ReactNode` | — | every part | Substitutes the rendered element and hands it every attribute, listener and data-* the part had. The skip links, the veil and the portal root are the shell’s own and are not substitutable |
+| `ref` | `Ref<AppShellHandle> on AppShell, Ref<HTMLElement> on every part` | — | AppShell and its parts | The root exposes a handle — openNav(), closeNav(), openAside(), closeAside(), focusMain() and root — because those are the actions a consumer cannot express declaratively; every part exposes its own element |
+| `useAppShell()` | `() => AppShellContextValue` | — | inside AppShell | What a part reads: open, asideOpen, the resolved modes, every axis, the ids, the translator t, setOpen(next, reason) and setAsideOpen(next, reason). Throws outside a shell rather than rendering a div that navigates nothing |
+| `AppShellDefaultsProvider` | `{ …fourteen axes }` | — | a subtree | What an application decides once for every route. A shell that states any of them itself still wins |
+| `AppShellNavToggle and AppShellAsideToggle anywhere` | `take their wiring from context` | — | inside AppShell | id, aria-expanded, aria-controls, the label and the handler come from the shell, so each control can stand in the banner, in its region’s own head or foot, or anywhere else — and there is still exactly one control carrying each state. Where it goes is written on this page under Rail |
+| `setPortalContainer` | `the layer part, named once` | — | every overlay under the shell | Dialog, Drawer, Menu, Popover, Tooltip and Toast land in the shell’s own layer instead of on the body, which is what keeps an application’s overlays inside the application’s stacking context |
+| `onClick, onKeyDown, …` | `composed, never replaced` | — | every part | A consumer’s own handler runs first; the family acts afterwards and only if the event was not prevented |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onNavOpenChange` | `(open: boolean, request: AppShellOpenRequest)` | Before the navigation region moves, and never for a value equal to the current one. The request carries value, previous, reason, the originating event as source, and cancel() — call it and nothing commits, in either mode. |
+| `onAsideOpenChange` | `(open: boolean, request: AppShellAsideOpenRequest)` | Before the secondary pane moves, with the same shape. The reasons a pane can carry are pointer, keyboard, escape, outsidePress, resize and programmatic — no select, because a pane has no destinations. |
+| `onAsideExtentChange` | `(extent: number \| undefined, request: AppShellAsideExtentRequest)` | Before the pane’s extent moves, already held inside minAsideExtent and maxAsideExtent, with the reason pointer for a drag on the aside-resizer, keyboard for an arrow, Home or End, and programmatic otherwise. undefined is the pane back on its asideSize step. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `primary` | `banner`, `nav`, `main` | `banner` |
+| `canvas` | `inset`, `flush`, `floating`, `panel` | `inset` |
+| `navMode` | `inline`, `overlay`, `auto` | `auto` |
+| `navSide` | `start`, `end` | `start` |
+| `navSize` | `sm`, `md`, `lg` | `md` |
+| `collapsedTo` | `rail`, `hidden` | `rail` |
+| `asideMode` | `inline`, `overlay`, `auto` | `auto` |
+| `asideSize` | `sm`, `md`, `lg` | `md` |
+| `scroll` | `content`, `document` | `content` |
+| `separation` | `rule`, `tone` | `rule` |
+| `modal` | `true`, `false` | `true` |
+| `escape` | `close`, `none` | `close` |
+| `outsidePress` | `close`, `none` | `close` |
+| `back` | `close`, `none` | `close` |
+| `closeOnNavigate` | `true`, `false` | `true` |
+
+## Rules
+
+- The structure is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/), and every one of the five is earned from the element rather than written as a role: header in the context of the body is banner, nav is navigation, main is main, aside is complementary, footer is contentinfo. The root is a div for exactly that reason — a main inside a sectioning element stops being a landmark, and the shell has to be placeable anywhere.
+- Both controls are the APG’s Disclosure pattern (w3.org/WAI/ARIA/apg/patterns/disclosure/): real buttons, so Enter and Space activate them natively, carrying aria-expanded and aria-controls pointing at their region. One departure is written and costed: under collapsedTo="rail" the navigation does not disappear, it narrows — aria-expanded is still true or false about the region’s full form, and the region stays in the tab order because a rail whose destinations cannot be reached is not a rail. The pane has no such departure: closed, it leaves the layout and the tab order.
+- A document with more than one navigation or complementary landmark needs a unique label on each, so both regions carry the family’s strings and a consumer may replace either per instance. Each control’s own name changes with the state — “Open navigation” and “Close navigation”, “Open side panel” and “Close side panel” — because a control whose name never changes leaves the reader to infer the state from aria-expanded alone.
+- The skip links are written from the regions that rendered and are open, so no link ever points at a target nobody built or the reader closed, and main carries tabindex="-1": without it the browser moves the scroll and leaves the focus behind in Safari and Firefox, which is a link that appears to work and moves nothing a screen reader follows.
+- While an overlaid region is modal, @slotted/core/focus contains the keyboard inside it and returns it to the control that opened it on close, and every region beside it — the banner included — takes inert, so Tab cannot reach them and a screen reader does not read them. The ways out are Escape, the veil, a destination, and whatever control the product put in the panel. Two layers can be open together only with both modes forced, and @slotted/core/dismissable-layer keeps one stack, so Escape reaches the topmost.
+- The pane’s edge is the APG’s Window Splitter (w3.org/WAI/ARIA/apg/patterns/windowsplitter/): a focusable separator with aria-orientation="vertical", aria-controls pointing at the pane and aria-valuemin, aria-valuemax and aria-valuenow as whole percentages of the shell, named “Resize panel”. ArrowLeft and ArrowRight move it sixteen pixels, sixty-four with Shift, by the direction on the screen — so ArrowLeft grows an end pane and shrinks a start one, mirrored in right-to-left — and Home and End go to the limits.
+- Nothing important depends on hover, the frame answers its own inline size rather than the window’s — which is what makes a 400% zoom behave like a narrow window — and every transition comes from the motion scale, so prefers-reduced-motion collapses all of them at once.
+
+## Tokens
+
+`--slotted-app-shell-aside-color`, `--slotted-app-shell-aside-extent`, `--slotted-app-shell-aside-size-lg`, `--slotted-app-shell-aside-size-md`, `--slotted-app-shell-aside-size-sm`, `--slotted-app-shell-aside-surface`, `--slotted-app-shell-banner-block-size`, `--slotted-app-shell-banner-color`, `--slotted-app-shell-banner-surface`, `--slotted-app-shell-border-color`, `--slotted-app-shell-brand-overflow`, `--slotted-app-shell-brand-wrap`, `--slotted-app-shell-canvas`, `--slotted-app-shell-color`, `--slotted-app-shell-elevation`, `--slotted-app-shell-footer-color`, `--slotted-app-shell-footer-surface`, `--slotted-app-shell-frame`, `--slotted-app-shell-frame-image`, `--slotted-app-shell-gutter`, `--slotted-app-shell-main-color`, `--slotted-app-shell-main-surface`, `--slotted-app-shell-nav-color`, `--slotted-app-shell-nav-overlay-size`, `--slotted-app-shell-nav-size-lg`, `--slotted-app-shell-nav-size-md`, `--slotted-app-shell-nav-size-sm`, `--slotted-app-shell-nav-surface`, `--slotted-app-shell-radius`, `--slotted-app-shell-rail-size`, `--slotted-app-shell-resizer-color`, `--slotted-app-shell-row-inset-size`, `--slotted-app-shell-row-mark-size`, `--slotted-app-shell-row-text-line-height`, `--slotted-app-shell-row-text-size`, `--slotted-app-shell-scrim`, `--slotted-app-shell-scrollbar-thumb-color`, `--slotted-app-shell-scrollbar-track-color`, `--slotted-app-shell-tone-surface`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-duration-medium`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-sm`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-scrim`, `--slotted-shadow-lg`, `--slotted-shadow-md`, `--slotted-shadow-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface`, `--slotted-surface-sunken`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-overlay`, `--slotted-z-index-popover`
+
+## Examples
+
+See [app-shell.examples.md](./app-shell.examples.md).

package/dist/docs/aspect-ratio.json

@@ -0,0 +1,157 @@
+{
+  "family": "aspect-ratio",
+  "ui": "aspect-ratio",
+  "binding": "react",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Box that keeps its content at a fixed ratio."
+  },
+  "axes": {
+    "ratio": [
+      "square",
+      "landscape",
+      "portrait",
+      "video",
+      "wide",
+      "custom"
+    ]
+  },
+  "members": {
+    "aspect-ratio": {
+      "nativeElement": "div",
+      "defaults": {},
+      "capabilities": [
+        "measurement",
+        "content"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "aspect-ratio": {
+      "imports": {
+        "source": "import { AspectRatio } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "The frame: a grid of one cell that is a stated proportion of its own width. Every child takes the cell and stretches to it; a replaced child is fitted whole, never cropped; content taller than the ratio grows the frame."
+        }
+      ],
+      "api": [
+        {
+          "name": "ratio",
+          "type": "'square' | 'landscape' | 'portrait' | 'video' | 'wide' | number | [number, number]",
+          "defaultValue": "—",
+          "appliesTo": "AspectRatio",
+          "description": "Required. The proportion the box holds before anything is in it: a name a product decided once, or any number"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "AspectRatio",
+          "description": "What the frame holds. Each child takes the one cell; a replaced child is fitted whole"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "AspectRatio",
+          "description": "Substitutes the root element — a figure, an li — and hands it every data attribute and the token"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "AspectRatio",
+          "description": "Reaches the frame; the props type is the div’s own, extended"
+        },
+        {
+          "name": "--slotted-aspect-ratio",
+          "type": "custom property",
+          "defaultValue": "—",
+          "appliesTo": "an instance",
+          "description": "What a custom ratio writes on the element, as w / h. A theme retunes a named ratio in the stylesheet instead"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "There is no aspect-ratio pattern in the WAI-ARIA Authoring Practices, and the frame needs none: it is a div with no role, and what it holds carries its own semantics — an img its alt, an iframe its title, a p its text.",
+        "The frame never clips. Content taller than the ratio grows the box (css-sizing-4 keeps a content-based minimum on a box with aspect-ratio), so a translation that runs longer than the design is read whole rather than cut at the ratio or laid over the frame below.",
+        "A replaced child is fitted with object-fit: contain, so a picture is shown entire; a consumer who wants the picture to cover the frame is asking for a crop, and Image is the family that decides that with its fit axis.",
+        "The frame moves nothing on load: the box is its stated proportion before the first byte of a picture arrives, which is what keeps a grid of thumbnails from shifting as each request returns."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-aspect-ratio"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One frame around a survey photograph, driven by the controls: switch the ratio and the frame changes shape while the picture is shown whole inside it.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio=\"video\">\n  <img alt=\"The fjord lookout at site 12\" src={site.photo} />\n</AspectRatio>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "ratios",
+      "title": "Five ratios a product decides once",
+      "note": "square, landscape (4:3), portrait (3:4), video (16:9) and wide (21:9), each named for what it holds rather than for its numbers, so a template says \"thumbnails are landscape\" and the DOM says which one was taken.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio=\"square\" />;\n<AspectRatio ratio=\"landscape\" />;\n<AspectRatio ratio=\"portrait\" />;\n<AspectRatio ratio=\"video\" />;\n<AspectRatio ratio=\"wide\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "custom",
+      "title": "Any other proportion, as a number or a pair",
+      "note": "A pair is written into the stylesheet exactly as given — 2 / 1 stays 2 / 1 — where a number is its quotient. Both mark the frame data-ratio=\"custom\" and put the value on the instance.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio={[2, 1]} />;\n<AspectRatio ratio={1.85} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "media",
+      "title": "Replaced content is fitted whole",
+      "note": "A 4:3 photograph in a 16:9 frame is shown entire with the frame either side; a wide one in a square frame is letterboxed the same way. The frame reserves and never crops — the crop is Image’s decision, taken with fit.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio=\"video\">\n  <iframe allowFullScreen src={briefing.embedUrl} title=\"Site briefing\" />\n</AspectRatio>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "growth",
+      "title": "Content taller than the ratio grows the frame",
+      "note": "Two lines fit a 16:9 frame at this width and the frame keeps its ratio; a longer paragraph does not fit, and the frame is exactly as tall as the paragraph. Nothing is clipped and nothing lands on the frame below: the ratio is a floor, not a ceiling.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio=\"video\">\n  <p>{site.notes}</p>\n</AspectRatio>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Two children stack; an Image composes the frame",
+      "note": "Every child takes the one cell, so a caption sits over a picture with nothing positioned by hand. An Image given a ratio renders this same frame inside its own root — the second tile is what Image writes.",
+      "language": "tsx",
+      "source": "<AspectRatio ratio=\"landscape\">\n  <img alt=\"\" src={site.photo} />\n  <Text tone=\"inverse\">{site.name}</Text>\n</AspectRatio>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "The frame has no role",
+      "note": "A frame is a div and announces nothing; the content is the consumer’s and carries its own name. A picture with a caption is a figure around the frame, with the figcaption after it, and the caption is not repeated in the alt.",
+      "language": "tsx",
+      "source": "<figure>\n  <AspectRatio ratio=\"landscape\">\n    <img alt=\"The fjord lookout at site 12 from the cliff path\" src={site.photo} />\n  </AspectRatio>\n  <figcaption>Site 12 — fjord lookout, March survey</figcaption>\n</figure>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/aspect-ratio.md

@@ -0,0 +1,132 @@
+<!-- index: ./index.md -->
+# aspect-ratio
+
+`data-ui="aspect-ratio"` · Box that keeps its content at a fixed ratio.
+
+## Import
+
+```tsx
+import { AspectRatio } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio="video">
+  <img alt="The fjord lookout at site 12" src={site.photo} />
+</AspectRatio>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `ratio` | `'square' \| 'landscape' \| 'portrait' \| 'video' \| 'wide' \| number \| [number, number]` | — | AspectRatio | Required. The proportion the box holds before anything is in it: a name a product decided once, or any number |
+| `children` | `ReactNode` | — | AspectRatio | What the frame holds. Each child takes the one cell; a replaced child is fitted whole |
+| `render` | `(props) => ReactNode` | — | AspectRatio | Substitutes the root element — a figure, an li — and hands it every data attribute and the token |
+| `ref` | `Ref<HTMLDivElement>` | — | AspectRatio | Reaches the frame; the props type is the div’s own, extended |
+| `--slotted-aspect-ratio` | `custom property` | — | an instance | What a custom ratio writes on the element, as w / h. A theme retunes a named ratio in the stylesheet instead |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `ratio` | `square`, `landscape`, `portrait`, `video`, `wide`, `custom` | — |
+
+## Rules
+
+- There is no aspect-ratio pattern in the WAI-ARIA Authoring Practices, and the frame needs none: it is a div with no role, and what it holds carries its own semantics — an img its alt, an iframe its title, a p its text.
+- The frame never clips. Content taller than the ratio grows the box (css-sizing-4 keeps a content-based minimum on a box with aspect-ratio), so a translation that runs longer than the design is read whole rather than cut at the ratio or laid over the frame below.
+- A replaced child is fitted with object-fit: contain, so a picture is shown entire; a consumer who wants the picture to cover the frame is asking for a crop, and Image is the family that decides that with its fit axis.
+- The frame moves nothing on load: the box is its stated proportion before the first byte of a picture arrives, which is what keeps a grid of thumbnails from shifting as each request returns.
+
+## Tokens
+
+`--slotted-aspect-ratio`
+
+## Examples
+
+### Five ratios a product decides once
+
+square, landscape (4:3), portrait (3:4), video (16:9) and wide (21:9), each named for what it holds rather than for its numbers, so a template says "thumbnails are landscape" and the DOM says which one was taken.
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio="square" />;
+<AspectRatio ratio="landscape" />;
+<AspectRatio ratio="portrait" />;
+<AspectRatio ratio="video" />;
+<AspectRatio ratio="wide" />;
+```
+
+### Any other proportion, as a number or a pair
+
+A pair is written into the stylesheet exactly as given — 2 / 1 stays 2 / 1 — where a number is its quotient. Both mark the frame data-ratio="custom" and put the value on the instance.
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio={[2, 1]} />;
+<AspectRatio ratio={1.85} />;
+```
+
+### Replaced content is fitted whole
+
+A 4:3 photograph in a 16:9 frame is shown entire with the frame either side; a wide one in a square frame is letterboxed the same way. The frame reserves and never crops — the crop is Image’s decision, taken with fit.
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio="video">
+  <iframe allowFullScreen src={briefing.embedUrl} title="Site briefing" />
+</AspectRatio>;
+```
+
+### Content taller than the ratio grows the frame
+
+Two lines fit a 16:9 frame at this width and the frame keeps its ratio; a longer paragraph does not fit, and the frame is exactly as tall as the paragraph. Nothing is clipped and nothing lands on the frame below: the ratio is a floor, not a ceiling.
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio="video">
+  <p>{site.notes}</p>
+</AspectRatio>;
+```
+
+### Two children stack; an Image composes the frame
+
+Every child takes the one cell, so a caption sits over a picture with nothing positioned by hand. An Image given a ratio renders this same frame inside its own root — the second tile is what Image writes.
+
+Excerpt — not a complete module
+
+```tsx
+<AspectRatio ratio="landscape">
+  <img alt="" src={site.photo} />
+  <Text tone="inverse">{site.name}</Text>
+</AspectRatio>;
+```
+
+### The frame has no role
+
+A frame is a div and announces nothing; the content is the consumer’s and carries its own name. A picture with a caption is a figure around the frame, with the figcaption after it, and the caption is not repeated in the alt.
+
+Excerpt — not a complete module
+
+```tsx
+<figure>
+  <AspectRatio ratio="landscape">
+    <img alt="The fjord lookout at site 12 from the cliff path" src={site.photo} />
+  </AspectRatio>
+  <figcaption>Site 12 — fjord lookout, March survey</figcaption>
+</figure>;
+```