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

package/dist/docs/calendar.md

@@ -0,0 +1,246 @@
+<!-- index: ./index.md -->
+# calendar
+
+`data-ui="calendar"` · Month grid for choosing a date or a range.
+
+## Import
+
+```tsx
+import { Calendar, CalendarDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar aria-label="Data" locale="pt-BR" onValueChange={setValue} value={value} />;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `header` | div | yes |
+| `previous` | button | yes |
+| `next` | button | yes |
+| `heading` | button | yes |
+| `grids` | div | yes |
+| `grid` | table | yes |
+| `grid-caption` | caption | yes |
+| `week-headers` | tr | yes |
+| `week-header` | th | yes |
+| `week` | tr | yes |
+| `week-number` | th | no |
+| `cell` | td | yes |
+| `day` | span | yes |
+| `months` | div | no |
+| `years` | div | no |
+| `period` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | Calendar | What the calendar holds, which depends on selectionMode. Present means the consumer owns it. |
+| `defaultValue` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | Calendar | What it starts from when nobody else writes one. Read once; a later change to it is not new state. |
+| `focusedDate` | `PlainDate` | — | Calendar | The date the reader is on, which is not the date they have chosen. Present means the consumer owns it, which is what a product that pages a calendar from outside needs. |
+| `defaultFocusedDate` | `PlainDate` | today | Calendar | Where the reader starts. Unset, it is the value if there is one and today if there is not. |
+| `selectionMode` | `'single' \| 'range' \| 'multiple'` | single | Calendar | How many dates the reader may choose, and what the value then is. |
+| `months` | `number` | 1 | Calendar | How many months are drawn side by side. They wrap when they do not fit; nothing is withdrawn. |
+| `view` | `'day' \| 'month' \| 'year'` | day | Calendar | Which grid is showing. Present means the consumer owns it; defaultView sets the starting one. |
+| `defaultView` | `'day' \| 'month' \| 'year'` | day | Calendar | The view it opens on. |
+| `min` | `PlainDate` | — | Calendar | The earliest date the reader may reach. An arrow that would leave the range stops at the edge. |
+| `max` | `PlainDate` | — | Calendar | The latest date the reader may reach. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | Calendar | Refuses particular dates. A refused date stays focusable and cannot be chosen. |
+| `weekNumbers` | `boolean` | false | Calendar | Draws the ISO 8601 week number as a row header. |
+| `fixedWeeks` | `boolean` | false | Calendar | Always six rows, so paging does not change the surface’s height. Worth setting inside a popover. |
+| `outsideDays` | `'shown' \| 'selectable' \| 'hidden'` | shown | Calendar | What a day of the month either side does: drawn and not pressable, drawn and pressable, or not drawn. |
+| `locale` | `string` | the language in force | Calendar | BCP 47. Decides the month names, the weekday names and the day a week starts on. |
+| `timeZone` | `string` | the runtime’s | Calendar | Which zone answers "what is today". |
+| `firstDayOfWeek` | `number` | the locale’s | Calendar | 0 is Sunday. Overrides what the locale says, for a product that fixes one. |
+| `calendar` | `'gregory'` | gregory | Calendar | The calendar system. One value today, and an axis rather than a silence. |
+| `disabled` | `boolean` | — | Calendar | Answers no key and no press, and takes every cell out of the tab sequence. |
+| `readOnly` | `boolean` | — | Calendar | Readable and not changeable, and never faded. |
+| `invalid` | `boolean` | — | Calendar | Retargets the focus ring to the danger colour. |
+| `messages` | `Partial<CalendarMessages>` | — | Calendar | Words laid over the language in force, key by key: the back (previous) and forward (next) triggers’ accessible names. |
+| `CalendarDefaultsProvider` | `component` | — | application | Sets timeZone, firstDayOfWeek, months, weekNumbers, fixedWeeks, outsideDays and calendar once for everything under it; a prop on the calendar still wins. |
+| `render` | `(props: CalendarRootProps) => ReactNode` | — | Calendar | Substitutes the element the root renders. The props carry the ref, which the family reaches its own cells through. |
+| `ref` | `Ref<CalendarHandle>` | — | Calendar | focus() puts the reader on the cell holding the tab stop; focusDate() moves them to a date, paging the grid to reach it. |
+| `onKeyDown` | `KeyboardEventHandler` | — | Calendar | Runs before the family acts, and calling preventDefault stops it acting at all — which is how a surface above the calendar takes a key first. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: CalendarValue, request: ChangeRequest<CalendarValue>)` | Before the value moves, and cancellable. The request carries the new value, the value it replaces, the reason — pointer or keyboard — and the originating event. |
+| `onFocusedDateChange` | `(date: PlainDate, request: ChangeRequest<PlainDate>)` | Before the date the reader is on moves, and cancellable. It fires for every arrow and every page, which is what lets a consumer load a month before it is shown. |
+| `onViewChange` | `(view: CalendarView)` | When the heading walks up a view or Escape walks down one. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `months` | `1`, `2`, `3` | `1` |
+| `selectionMode` | `single`, `range`, `multiple` | `single` |
+| `view` | `day`, `month`, `year` | `day` |
+| `calendar` | `gregory` | `gregory` |
+| `weekNumbers` | `off`, `on` | `false` |
+| `fixedWeeks` | `off`, `on` | `false` |
+| `outsideDays` | `shown`, `selectable`, `hidden` | `shown` |
+
+## Rules
+
+- The grid role is on a real table, so the row, column-header and cell roles are implied by tr, th and td and are deliberately not written — the APG’s own note, and the duplication a pattern check exists to refuse.
+- Exactly one cell is in the tab sequence, and the arrows move it. Focus is only put back into the DOM after a key moved it, never on a render, so a calendar on a page does not steal the reader’s place.
+- The heading is a polite live region, because paging with a key changes nothing that focus lands on and nothing else would announce the new month.
+- A column header shows the locale’s narrow weekday and carries the full name in abbr, which is the difference between a screen reader saying "Mo" and saying "Monday".
+- A date the predicate refuses carries aria-disabled rather than being removed, so a reader can arrow onto it and be told why it is out; and it is struck through as well as dimmed, because colour alone says nothing under forced colours.
+- Today is a dot under the number and focus is a ring around it. They were the same ring once, and a reader arrowing onto today saw one box and could not tell which of the two facts it was.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-calendar-active-background`, `--slotted-calendar-background`, `--slotted-calendar-cell-size`, `--slotted-calendar-color`, `--slotted-calendar-day-radius`, `--slotted-calendar-disabled-color`, `--slotted-calendar-hover-background`, `--slotted-calendar-in-range-color`, `--slotted-calendar-invalid-edge-width`, `--slotted-calendar-invalid-focus-ring-color`, `--slotted-calendar-outside-color`, `--slotted-calendar-preview-background`, `--slotted-calendar-preview-border-color`, `--slotted-calendar-radius`, `--slotted-calendar-range-active-background`, `--slotted-calendar-range-background`, `--slotted-calendar-range-border-color`, `--slotted-calendar-range-hover-background`, `--slotted-calendar-selected-background`, `--slotted-calendar-selected-color`, `--slotted-calendar-today-color`, `--slotted-calendar-trigger-color`, `--slotted-calendar-unavailable-color`, `--slotted-calendar-week-number-border-color`, `--slotted-calendar-week-number-color`, `--slotted-calendar-weekday-color`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-invalid-edge-width`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-highlight-tint-opacity`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### One date
+
+The default mode. Pressing the chosen date again takes it back, which is the only way to empty the value without a control of its own.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar selectionMode="single" value={value} onValueChange={setValue} />;
+```
+
+### A run of days
+
+Two presses make a range, and either end may come first: choosing the 11th and then the 7th means the 7th to the 11th. A third press starts again, because a range that only grew could never be narrowed.
+
+Excerpt — not a complete module
+
+```tsx
+<>
+  <Calendar selectionMode="range" value={run} onValueChange={setRun} />
+  <Calendar selectionMode="multiple" value={dates} onValueChange={setDates} />
+</>;
+```
+
+### Day, month and year
+
+Press the heading to walk up and Escape to walk down. A reader entering a birth date must not press "previous month" four hundred times, which is what these two views exist to prevent.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar defaultView="year" onViewChange={setView} />;
+```
+
+### More than one month
+
+Two or three months side by side, each with its own caption because the heading then names the span. Narrow the stage: a month that no longer fits wraps under the first rather than being withdrawn.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar months={2} selectionMode="range" />;
+```
+
+### The locale writes the month
+
+The month name, the weekday names and the day a week starts on all come from Intl. A German week starts on Monday and a Brazilian one on Sunday, from the same component and no table.
+
+Excerpt — not a complete module
+
+```tsx
+<>
+  <Calendar locale="pt-BR" />
+  <Calendar locale="de-DE" />
+  <Calendar locale="ja-JP" />
+  <Calendar locale="pt-BR" firstDayOfWeek={1} />
+</>;
+```
+
+### Bounds
+
+min and max fence what the reader may reach: an arrow that would leave the range stops at the edge, and a date outside it cannot be pressed at all.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar max={{ year: 2026, month: 9, day: 30 }} min={{ year: 2026, month: 9, day: 1 }} />;
+```
+
+### Days that are refused
+
+A refused date stays focusable — aria-disabled, never disabled — so a reader can arrow onto it, be told why it is out, and arrow past. Struck through rather than only faded, because colour alone says nothing under forced colours.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar isDateUnavailable={(date) => isWeekend(date) || isHoliday(date)} />;
+```
+
+### Week numbers
+
+ISO 8601 numbering, as a row header separated by a rule. The rule is what keeps the column from reading as an eighth day of the week.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar fixedWeeks firstDayOfWeek={1} weekNumbers />;
+```
+
+### States
+
+Read-only keeps the value legible and answers nothing; disabled takes every cell out of the tab sequence and paints today in the disabled ink; invalid retargets the focus ring rather than removing it.
+
+Excerpt — not a complete module
+
+```tsx
+<>
+  <Calendar readOnly />
+  <Calendar invalid />
+  <Calendar disabled />
+</>;
+```
+
+### Density and width
+
+Seven columns of two-digit numbers make this the densest grid the library draws. Switch the toolbar to dense and narrow the stage: the cell is the room there is divided by the columns there are, bounded by the WCAG minimum below.
+
+Excerpt — not a complete module
+
+```tsx
+<Calendar fixedWeeks />;
+```
+
+### Composition and escape hatches
+
+A provider sets the shape once, SlottedProvider the language; focusedDate is a value of its own a consumer may own; and the ref hands back focus() and focusDate(), which page the grid to reach a date.
+
+Excerpt — not a complete module
+
+```tsx
+<CalendarDefaultsProvider fixedWeeks>
+  <Calendar focusedDate={focused} onFocusedDateChange={setFocused} ref={handle} />
+</CalendarDefaultsProvider>;
+```
+
+### The keyboard
+
+Every key the APG grid pattern lists, including the two a month grid needs that a list does not: PageUp and PageDown move a month, and Shift with either moves a year.
+
+Excerpt — not a complete module
+
+```tsx
+// ArrowLeft / ArrowRight  a day, mirrored under dir="rtl"
+// ArrowUp / ArrowDown     the same weekday, a week either way
+// Home / End              the first and last day of the displayed week
+// PageUp / PageDown       a month, clamped to the last day it has
+// Shift + PageUp / Down   a year, on the same terms
+// Enter / Space           chooses the date focus is on
+// Escape                  walks down a view, and out of nothing
+```

package/dist/docs/card.json

@@ -0,0 +1,263 @@
+{
+  "family": "card",
+  "ui": "card",
+  "binding": "react",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Bordered surface that groups related content."
+  },
+  "axes": {
+    "orientation": [
+      "vertical",
+      "horizontal"
+    ],
+    "fill": [
+      "outline",
+      "elevated",
+      "subtle"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ]
+  },
+  "members": {
+    "card": {
+      "nativeElement": "div",
+      "defaults": {
+        "orientation": "vertical",
+        "fill": "outline",
+        "size": "md",
+        "selected": false,
+        "disabled": false
+      },
+      "capabilities": [
+        "orientation",
+        "size"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "selected",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "media",
+        "header",
+        "actions",
+        "body",
+        "footer",
+        "link",
+        "selection"
+      ]
+    }
+  },
+  "docs": {
+    "card": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "orientation",
+          "type": "'vertical' | 'horizontal'",
+          "defaultValue": "vertical",
+          "appliesTo": "Card",
+          "description": "Puts the media beside the regions, and returns it to the top in a narrow container"
+        },
+        {
+          "name": "fill",
+          "type": "'outline' | 'elevated' | 'subtle'",
+          "defaultValue": "outline",
+          "appliesTo": "Card",
+          "description": "How the surface is bounded: a hairline edge, the edge plus a lift, or a filled ground"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "Card",
+          "description": "The card's own inset. Density is the application's choice; this is this card's"
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Card",
+          "description": "Mirrors a selection the page owns; the control inside is what announces it"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Card",
+          "description": "Mirrors a control the page has disabled; the card disables nothing itself"
+        },
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Card, CardMedia, CardHeader, CardActions, CardSelection, CardBody, CardFooter, CardLink",
+          "description": "Renders the wiring into another element"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the native element; each part extends its own element’s props"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "CardLink",
+          "description": "Destination of the card, on the anchor whose hit area covers the surface"
+        },
+        {
+          "name": "CardDefaultsProvider",
+          "type": "{ fill, orientation, size }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets the defaults once for every card under it; an explicit prop still wins"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "There is no card pattern in the WAI-ARIA Authoring Practices, and a card is structure rather than a widget. The applicable guidance is Structural Roles: use the HTML element that already carries the meaning.",
+        "The root is a div with no role. Use render to make it an article with its own heading, a section, the li of a list of results, or the label of a chooser — whichever the page actually means.",
+        "The card contributes no keyboard behaviour. CardLink is an anchor, so Enter, the context menu and middle-click are the platform’s.",
+        "CardLink is named by its own text. A card whose root were the link would take every string inside it into that name, which is the reason the hit area is stretched from the link instead.",
+        "A card carries at most one CardLink, and it navigates. A whole surface that fires a command on any click, with no visible control boundary, is a misclick nobody can undo; put a button in CardActions or the footer instead.",
+        "CardActions and CardFooter both sit above the stretched hit area, so a control in either stays operable. An interactive element anywhere else needs position: relative of its own.",
+        "Text over the stretched area cannot be selected with the pointer. That is the cost of the whole-card target, and the reason a card with no CardLink stretches nothing.",
+        "selected and disabled are painted, never announced. The radio, checkbox or button inside the card is what carries the state for assistive technology.",
+        "selected is the accent surface under a hairline accent edge, the pair a selected row paints. In high contrast and forced colours both flatten, and the checked control inside is what carries the state. elevated keeps its hairline because a shadow is removed there outright.",
+        "The focus ring is drawn on the card while the link has focus. In a browser without :has() the link keeps its own native outline instead.",
+        "A rule between two regions is a Divider written between them. It is announced as a separator unless it is marked decorative, which is usually what a rule inside one card is."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-card-actions-gap",
+    "--slotted-card-background",
+    "--slotted-card-background-disabled",
+    "--slotted-card-background-selected",
+    "--slotted-card-background-selected-active",
+    "--slotted-card-background-selected-hover",
+    "--slotted-card-background-subtle",
+    "--slotted-card-border-color",
+    "--slotted-card-border-color-disabled",
+    "--slotted-card-border-color-hover",
+    "--slotted-card-border-width",
+    "--slotted-card-color",
+    "--slotted-card-color-disabled",
+    "--slotted-card-edge-color-selected",
+    "--slotted-card-edge-width-selected",
+    "--slotted-card-footer-gap",
+    "--slotted-card-header-column-gap",
+    "--slotted-card-header-gap",
+    "--slotted-card-media-size",
+    "--slotted-card-padding-block",
+    "--slotted-card-padding-block-lg",
+    "--slotted-card-padding-block-sm",
+    "--slotted-card-padding-inline",
+    "--slotted-card-padding-inline-lg",
+    "--slotted-card-padding-inline-sm",
+    "--slotted-card-radius",
+    "--slotted-card-region-gap",
+    "--slotted-card-region-gap-lg",
+    "--slotted-card-region-gap-sm",
+    "--slotted-card-selection-line",
+    "--slotted-card-selection-size",
+    "--slotted-card-shadow",
+    "--slotted-card-shadow-hover",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-short",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-lg",
+    "--slotted-line-height-lg",
+    "--slotted-radius-lg",
+    "--slotted-selection-size-md",
+    "--slotted-shadow-lg",
+    "--slotted-shadow-md",
+    "--slotted-shadow-sm",
+    "--slotted-shadow-xs",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-8",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-accent-subtle-active",
+    "--slotted-tone-accent-subtle-hover",
+    "--slotted-tone-accent-surface",
+    "--slotted-tone-secondary-subtle-active"
+  ],
+  "examples": [
+    {
+      "id": "card-react-regions",
+      "title": "The regions, and the corner of the header",
+      "note": null,
+      "language": "tsx",
+      "source": "<Card>\n  <CardHeader>\n    <Heading level={3}>Northwind billing</Heading>\n    <Text size=\"sm\" tone=\"muted\">\n      Invoices and payment methods\n    </Text>\n    <CardActions>\n      <Badge tone=\"warning\">Overdue</Badge>\n    </CardActions>\n  </CardHeader>\n  <CardBody>The next invoice settles on 1 October.</CardBody>\n  <CardFooter>\n    <button type=\"button\">Pay now</button>\n  </CardFooter>\n</Card>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-react-sections",
+      "title": "A rule between two regions",
+      "note": null,
+      "language": "tsx",
+      "source": "<Card>\n  <CardHeader>\n    <Heading level={3}>Review pictures</Heading>\n  </CardHeader>\n  <Divider decorative />\n  <CardBody>Two hundred images since the last visit.</CardBody>\n  <Divider decorative inset />\n  <CardFooter>\n    <Text size=\"xs\" tone=\"muted\">\n      The inset rule lines up with the text\n    </Text>\n  </CardFooter>\n</Card>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-react-link",
+      "title": "One destination, named by the title",
+      "note": null,
+      "language": "tsx",
+      "source": "<Card>\n  <CardHeader>\n    <CardLink href=\"/accounts/northwind\">\n      <Heading level={3}>Northwind Traders</Heading>\n    </CardLink>\n  </CardHeader>\n  <CardBody>Twelve open invoices</CardBody>\n  <CardFooter>\n    <a href=\"/accounts/northwind/settings\">Billing settings</a>\n  </CardFooter>\n</Card>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-react-chooser",
+      "title": "A chooser, where the radio owns the state",
+      "note": null,
+      "language": "tsx",
+      "source": "<Card render={(props) => <label {...props} />} selected={plan === 'team'}>\n  <CardHeader>\n    <CardSelection>\n      <input\n        checked={plan === 'team'}\n        name=\"plan\"\n        onChange={() => setPlan('team')}\n        type=\"radio\"\n        value=\"team\"\n      />\n    </CardSelection>\n    <Heading level={3}>Team</Heading>\n    <Text size=\"sm\" tone=\"muted\">\n      Twenty seats and shared billing\n    </Text>\n  </CardHeader>\n</Card>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-react-horizontal",
+      "title": "Media beside the content, until the card is narrow",
+      "note": null,
+      "language": "tsx",
+      "source": "<Card orientation=\"horizontal\">\n  <CardMedia>\n    <img alt=\"\" src={report.cover} />\n  </CardMedia>\n  <CardHeader>\n    <Heading level={3}>Quarterly report</Heading>\n  </CardHeader>\n  <CardBody>Revenue, retention and the accounts that moved them.</CardBody>\n</Card>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-react-defaults",
+      "title": "One decision for every card in the application",
+      "note": null,
+      "language": "tsx",
+      "source": "<CardDefaultsProvider fill=\"elevated\" size=\"lg\">\n  <Dashboard />\n</CardDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/card.md

@@ -0,0 +1,156 @@
+<!-- index: ./index.md -->
+# card
+
+`data-ui="card"` · Bordered surface that groups related content.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Card>
+  <CardHeader>
+    <Heading level={3}>Northwind billing</Heading>
+    <Text size="sm" tone="muted">
+      Invoices and payment methods
+    </Text>
+    <CardActions>
+      <Badge tone="warning">Overdue</Badge>
+    </CardActions>
+  </CardHeader>
+  <CardBody>The next invoice settles on 1 October.</CardBody>
+  <CardFooter>
+    <button type="button">Pay now</button>
+  </CardFooter>
+</Card>;
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | Card | Puts the media beside the regions, and returns it to the top in a narrow container |
+| `fill` | `'outline' \| 'elevated' \| 'subtle'` | outline | Card | How the surface is bounded: a hairline edge, the edge plus a lift, or a filled ground |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Card | The card's own inset. Density is the application's choice; this is this card's |
+| `selected` | `boolean` | false | Card | Mirrors a selection the page owns; the control inside is what announces it |
+| `disabled` | `boolean` | false | Card | Mirrors a control the page has disabled; the card disables nothing itself |
+| `render` | `(props) => ReactNode` | — | Card, CardMedia, CardHeader, CardActions, CardSelection, CardBody, CardFooter, CardLink | Renders the wiring into another element |
+| `ref` | `Ref<HTMLElement>` | — | every part | Reaches the native element; each part extends its own element’s props |
+| `href` | `string` | — | CardLink | Destination of the card, on the anchor whose hit area covers the surface |
+| `CardDefaultsProvider` | `{ fill, orientation, size }` | — | a subtree | Sets the defaults once for every card under it; an explicit prop still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `fill` | `outline`, `elevated`, `subtle` | `outline` |
+| `size` | `sm`, `md`, `lg` | `md` |
+
+## Rules
+
+- There is no card pattern in the WAI-ARIA Authoring Practices, and a card is structure rather than a widget. The applicable guidance is Structural Roles: use the HTML element that already carries the meaning.
+- The root is a div with no role. Use render to make it an article with its own heading, a section, the li of a list of results, or the label of a chooser — whichever the page actually means.
+- The card contributes no keyboard behaviour. CardLink is an anchor, so Enter, the context menu and middle-click are the platform’s.
+- CardLink is named by its own text. A card whose root were the link would take every string inside it into that name, which is the reason the hit area is stretched from the link instead.
+- A card carries at most one CardLink, and it navigates. A whole surface that fires a command on any click, with no visible control boundary, is a misclick nobody can undo; put a button in CardActions or the footer instead.
+- CardActions and CardFooter both sit above the stretched hit area, so a control in either stays operable. An interactive element anywhere else needs position: relative of its own.
+- Text over the stretched area cannot be selected with the pointer. That is the cost of the whole-card target, and the reason a card with no CardLink stretches nothing.
+- selected and disabled are painted, never announced. The radio, checkbox or button inside the card is what carries the state for assistive technology.
+- selected is the accent surface under a hairline accent edge, the pair a selected row paints. In high contrast and forced colours both flatten, and the checked control inside is what carries the state. elevated keeps its hairline because a shadow is removed there outright.
+- The focus ring is drawn on the card while the link has focus. In a browser without :has() the link keeps its own native outline instead.
+- A rule between two regions is a Divider written between them. It is announced as a separator unless it is marked decorative, which is usually what a rule inside one card is.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-card-actions-gap`, `--slotted-card-background`, `--slotted-card-background-disabled`, `--slotted-card-background-selected`, `--slotted-card-background-selected-active`, `--slotted-card-background-selected-hover`, `--slotted-card-background-subtle`, `--slotted-card-border-color`, `--slotted-card-border-color-disabled`, `--slotted-card-border-color-hover`, `--slotted-card-border-width`, `--slotted-card-color`, `--slotted-card-color-disabled`, `--slotted-card-edge-color-selected`, `--slotted-card-edge-width-selected`, `--slotted-card-footer-gap`, `--slotted-card-header-column-gap`, `--slotted-card-header-gap`, `--slotted-card-media-size`, `--slotted-card-padding-block`, `--slotted-card-padding-block-lg`, `--slotted-card-padding-block-sm`, `--slotted-card-padding-inline`, `--slotted-card-padding-inline-lg`, `--slotted-card-padding-inline-sm`, `--slotted-card-radius`, `--slotted-card-region-gap`, `--slotted-card-region-gap-lg`, `--slotted-card-region-gap-sm`, `--slotted-card-selection-line`, `--slotted-card-selection-size`, `--slotted-card-shadow`, `--slotted-card-shadow-hover`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-lg`, `--slotted-line-height-lg`, `--slotted-radius-lg`, `--slotted-selection-size-md`, `--slotted-shadow-lg`, `--slotted-shadow-md`, `--slotted-shadow-sm`, `--slotted-shadow-xs`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-text`, `--slotted-tone-accent-border`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-secondary-subtle-active`
+
+## Examples
+
+### A rule between two regions
+
+Excerpt — not a complete module
+
+```tsx
+<Card>
+  <CardHeader>
+    <Heading level={3}>Review pictures</Heading>
+  </CardHeader>
+  <Divider decorative />
+  <CardBody>Two hundred images since the last visit.</CardBody>
+  <Divider decorative inset />
+  <CardFooter>
+    <Text size="xs" tone="muted">
+      The inset rule lines up with the text
+    </Text>
+  </CardFooter>
+</Card>;
+```
+
+### One destination, named by the title
+
+Excerpt — not a complete module
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardLink href="/accounts/northwind">
+      <Heading level={3}>Northwind Traders</Heading>
+    </CardLink>
+  </CardHeader>
+  <CardBody>Twelve open invoices</CardBody>
+  <CardFooter>
+    <a href="/accounts/northwind/settings">Billing settings</a>
+  </CardFooter>
+</Card>;
+```
+
+### A chooser, where the radio owns the state
+
+Excerpt — not a complete module
+
+```tsx
+<Card render={(props) => <label {...props} />} selected={plan === 'team'}>
+  <CardHeader>
+    <CardSelection>
+      <input
+        checked={plan === 'team'}
+        name="plan"
+        onChange={() => setPlan('team')}
+        type="radio"
+        value="team"
+      />
+    </CardSelection>
+    <Heading level={3}>Team</Heading>
+    <Text size="sm" tone="muted">
+      Twenty seats and shared billing
+    </Text>
+  </CardHeader>
+</Card>;
+```
+
+### Media beside the content, until the card is narrow
+
+Excerpt — not a complete module
+
+```tsx
+<Card orientation="horizontal">
+  <CardMedia>
+    <img alt="" src={report.cover} />
+  </CardMedia>
+  <CardHeader>
+    <Heading level={3}>Quarterly report</Heading>
+  </CardHeader>
+  <CardBody>Revenue, retention and the accounts that moved them.</CardBody>
+</Card>;
+```
+
+### One decision for every card in the application
+
+Excerpt — not a complete module
+
+```tsx
+<CardDefaultsProvider fill="elevated" size="lg">
+  <Dashboard />
+</CardDefaultsProvider>;
+```