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

package/docs/calendar.md

@@ -0,0 +1,242 @@
+<!-- index: ./index.md -->
+# calendar
+
+`data-ui="calendar"` · Month grid for choosing a date or a range.
+
+## Import
+
+```ts
+import { SlCalendar } from '@slotted/angular/calendar';
+```
+
+Selector: `[slCalendar]` · exportAs: `slCalendar`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slCalendar locale="pt-BR" (valueChange)="onValue($event)"></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element | 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` | — | SlCalendar | What the calendar holds, which depends on selectionMode. Present means the consumer owns it. |
+| `defaultValue` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | SlCalendar | What it starts from when nobody else writes one. Read once; a later change to it is not new state. |
+| `focusedDate` | `PlainDate` | — | SlCalendar | 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 | SlCalendar | Where the reader starts. Unset, it is the value if there is one and today if there is not. |
+| `selectionMode` | `'single' \| 'range' \| 'multiple'` | single | SlCalendar | How many dates the reader may choose, and what the value then is. |
+| `months` | `number` | 1 | SlCalendar | How many months are drawn side by side. They wrap when they do not fit; nothing is withdrawn. |
+| `view` | `'day' \| 'month' \| 'year'` | day | SlCalendar | Which grid is showing. Present means the consumer owns it; defaultView sets the starting one. |
+| `defaultView` | `'day' \| 'month' \| 'year'` | day | SlCalendar | The view it opens on. |
+| `min` | `PlainDate` | — | SlCalendar | The earliest date the reader may reach. An arrow that would leave the range stops at the edge. |
+| `max` | `PlainDate` | — | SlCalendar | The latest date the reader may reach. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlCalendar | Refuses particular dates. A refused date stays focusable and cannot be chosen. |
+| `weekNumbers` | `boolean` | false | SlCalendar | Draws the ISO 8601 week number as a row header. |
+| `fixedWeeks` | `boolean` | false | SlCalendar | Always six rows, so paging does not change the surface’s height. Worth setting inside a popover. |
+| `outsideDays` | `'shown' \| 'selectable' \| 'hidden'` | shown | SlCalendar | 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 | SlCalendar | BCP 47. Decides the month names, the weekday names and the day a week starts on. |
+| `timeZone` | `string` | the runtime’s | SlCalendar | Which zone answers "what is today". |
+| `firstDayOfWeek` | `number` | the locale’s | SlCalendar | 0 is Sunday. Overrides what the locale says, for a product that fixes one. |
+| `calendar` | `'gregory'` | gregory | SlCalendar | The calendar system. One value today, and an axis rather than a silence. |
+| `disabled` | `boolean` | — | SlCalendar | Answers no key and no press, and takes every cell out of the tab sequence. |
+| `readOnly` | `boolean` | — | SlCalendar | Readable and not changeable, and never faded. |
+| `invalid` | `boolean` | — | SlCalendar | Retargets the focus ring to the danger colour. |
+| `messages` | `Partial<CalendarMessages>` | — | SlCalendar | Words laid over the language in force, key by key: the back (previous) and forward (next) triggers’ accessible names. |
+| `provideCalendarDefaults` | `Provider` | — | application | Sets timeZone, firstDayOfWeek, months, weekNumbers, fixedWeeks, outsideDays and calendar once for everything under the injector; an input on the calendar still wins. |
+| `exportAs` | `slCalendar` | — | SlCalendar | Hands a template the instance, so focus(), focusDate(), currentView() and the derived selection() signal are reachable without a component of its own. |
+| `focusDate` | `(date: PlainDate) => void` | — | SlCalendar | Moves the reader to a date, paging the grid to reach it — the one action no input can express. |
+| `currentView` | `Signal<CalendarView>` | — | SlCalendar | Which grid is showing, as a signal, so a template reads it without an event handler and without a second copy of it. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `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. There is no two-way [(value)]: one slot could carry none of that. |
+| `focusedDateChange` | `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. |
+| `viewChange` | `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
+
+```html
+<div slCalendar selectionMode="single" [value]="value" (valueChange)="onValue($event)"></div>
+```
+
+### 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
+
+```html
+<div slCalendar selectionMode="range" [value]="run"></div>
+<div slCalendar selectionMode="multiple" [value]="dates"></div>
+```
+
+### 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
+
+```html
+<div slCalendar defaultView="year" (viewChange)="onView($event)"></div>
+```
+
+### 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
+
+```html
+<div slCalendar selectionMode="range" [months]="2"></div>
+```
+
+### 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
+
+```html
+<div slCalendar locale="pt-BR"></div>
+<div slCalendar locale="de-DE"></div>
+<div slCalendar locale="ja-JP"></div>
+<div slCalendar locale="pt-BR" [firstDayOfWeek]="1"></div>
+```
+
+### 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
+
+```html
+<div slCalendar [min]="first" [max]="last"></div>
+```
+
+### 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
+
+```html
+<div slCalendar [isDateUnavailable]="isWeekend"></div>
+```
+
+### 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
+
+```html
+<div slCalendar weekNumbers fixedWeeks [firstDayOfWeek]="1"></div>
+```
+
+### 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
+
+```html
+<div slCalendar readOnly></div>
+<div slCalendar invalid></div>
+<div slCalendar disabled></div>
+```
+
+### 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
+
+```html
+<div slCalendar fixedWeeks></div>
+```
+
+### Composition and escape hatches
+
+A provider sets the shape once, provideSlotted 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
+
+```html
+<div slCalendar #cal="slCalendar" locale="pt-BR" (focusedDateChange)="onFocused($event)"></div>
+<button type="button" (click)="cal.focusDate(christmas)">Ir para o Natal</button>
+```
+
+### 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
+
+```html
+<!-- 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 -->
+<div slCalendar></div>
+```

package/docs/card.json

@@ -0,0 +1,283 @@
+{
+  "family": "card",
+  "ui": "card",
+  "binding": "angular",
+  "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": "slCard",
+          "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": "slCard",
+          "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": "slCard",
+          "description": "The card's own inset. Density is the application's choice; this is this card's"
+        },
+        {
+          "name": "selected",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCard",
+          "description": "Mirrors a selection the page owns; the control inside is what announces it"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slCard",
+          "description": "Mirrors a control the page has disabled; the card disables nothing itself"
+        },
+        {
+          "name": "slCardMedia",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "Media that bleeds to the edge and rounds the corners it touches"
+        },
+        {
+          "name": "slCardHeader",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "A title and the line that supports it"
+        },
+        {
+          "name": "slCardActions",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "inside slCardHeader",
+          "description": "The corner of the header: a badge, a status, a menu button"
+        },
+        {
+          "name": "slCardSelection",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "inside slCardHeader",
+          "description": "The column a choice card keeps for its checkbox or radio"
+        },
+        {
+          "name": "slCardBody",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "The content of the card"
+        },
+        {
+          "name": "slCardFooter",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "any element",
+          "description": "Actions and metadata, above the hit area a link stretches"
+        },
+        {
+          "name": "slCardLink",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "a[href]",
+          "description": "The one destination the card resolves to; its hit area covers the surface"
+        },
+        {
+          "name": "provideCardDefaults",
+          "type": "{ fill, orientation, size }",
+          "defaultValue": "—",
+          "appliesTo": "any injector",
+          "description": "Sets the defaults once for every card under it, as a provider on the application or a route; an explicit input 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.",
+        "Every part is a directive written on the element the page chose, so an article with its own heading, the li of a list of results and the label of a chooser are all the same card. The family writes no role.",
+        "The card contributes no keyboard behaviour. slCardLink only matches an anchor, so Enter, the context menu and middle-click are the platform’s.",
+        "The link 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 slCardLink, 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 slCardActions or the footer instead.",
+        "slCardActions and slCardFooter 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 link 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 an slDivider 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-angular-regions",
+      "title": "The regions, and the corner of the header",
+      "note": null,
+      "language": "html",
+      "source": "<div slCard>\n  <div slCardHeader>\n    <h3 slHeading [level]=\"3\">Northwind billing</h3>\n    <span slText size=\"sm\" tone=\"muted\">Invoices and payment methods</span>\n    <span slCardActions><span slBadge tone=\"warning\">Overdue</span></span>\n  </div>\n  <div slCardBody>The next invoice settles on 1 October.</div>\n  <div slCardFooter>\n    <button type=\"button\">Pay now</button>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-angular-sections",
+      "title": "A rule between two regions",
+      "note": null,
+      "language": "html",
+      "source": "<div slCard>\n  <div slCardHeader><h3 slHeading [level]=\"3\">Review pictures</h3></div>\n  <hr slDivider decorative />\n  <div slCardBody>Two hundred images since the last visit.</div>\n  <hr slDivider decorative inset />\n  <div slCardFooter>\n    <span slText size=\"xs\" tone=\"muted\">The inset rule lines up with the text</span>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-angular-link",
+      "title": "One destination, named by the title",
+      "note": null,
+      "language": "html",
+      "source": "<div slCard>\n  <div slCardHeader>\n    <a slCardLink href=\"/accounts/northwind\">Northwind Traders</a>\n  </div>\n  <div slCardBody>Twelve open invoices</div>\n  <div slCardFooter>\n    <a href=\"/accounts/northwind/settings\">Billing settings</a>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-angular-chooser",
+      "title": "A chooser, where the radio owns the state",
+      "note": null,
+      "language": "html",
+      "source": "<label slCard [selected]=\"plan() === 'team'\">\n  <div slCardHeader>\n    <span slCardSelection>\n      <input type=\"radio\" name=\"plan\" value=\"team\" [(ngModel)]=\"plan\" />\n    </span>\n    <h3 slHeading [level]=\"3\">Team</h3>\n    <span slText size=\"sm\" tone=\"muted\">Twenty seats and shared billing</span>\n  </div>\n</label>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "card-angular-horizontal",
+      "title": "Media beside the content, until the card is narrow",
+      "note": null,
+      "language": "html",
+      "source": "<div slCard orientation=\"horizontal\">\n  <figure slCardMedia><img alt=\"\" [src]=\"report.cover\" /></figure>\n  <div slCardHeader>\n    <h3 slHeading [level]=\"3\">Quarterly report</h3>\n  </div>\n  <div slCardBody>Revenue, retention and the accounts that moved them.</div>\n</div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/card.md

@@ -0,0 +1,130 @@
+<!-- index: ./index.md -->
+# card
+
+`data-ui="card"` · Bordered surface that groups related content.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slCard>
+  <div slCardHeader>
+    <h3 slHeading [level]="3">Northwind billing</h3>
+    <span slText size="sm" tone="muted">Invoices and payment methods</span>
+    <span slCardActions><span slBadge tone="warning">Overdue</span></span>
+  </div>
+  <div slCardBody>The next invoice settles on 1 October.</div>
+  <div slCardFooter>
+    <button type="button">Pay now</button>
+  </div>
+</div>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | slCard | Puts the media beside the regions, and returns it to the top in a narrow container |
+| `fill` | `'outline' \| 'elevated' \| 'subtle'` | outline | slCard | How the surface is bounded: a hairline edge, the edge plus a lift, or a filled ground |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slCard | The card's own inset. Density is the application's choice; this is this card's |
+| `selected` | `boolean` | false | slCard | Mirrors a selection the page owns; the control inside is what announces it |
+| `disabled` | `boolean` | false | slCard | Mirrors a control the page has disabled; the card disables nothing itself |
+| `slCardMedia` | `directive` | — | any element | Media that bleeds to the edge and rounds the corners it touches |
+| `slCardHeader` | `directive` | — | any element | A title and the line that supports it |
+| `slCardActions` | `directive` | — | inside slCardHeader | The corner of the header: a badge, a status, a menu button |
+| `slCardSelection` | `directive` | — | inside slCardHeader | The column a choice card keeps for its checkbox or radio |
+| `slCardBody` | `directive` | — | any element | The content of the card |
+| `slCardFooter` | `directive` | — | any element | Actions and metadata, above the hit area a link stretches |
+| `slCardLink` | `directive` | — | a[href] | The one destination the card resolves to; its hit area covers the surface |
+| `provideCardDefaults` | `{ fill, orientation, size }` | — | any injector | Sets the defaults once for every card under it, as a provider on the application or a route; an explicit input 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.
+- Every part is a directive written on the element the page chose, so an article with its own heading, the li of a list of results and the label of a chooser are all the same card. The family writes no role.
+- The card contributes no keyboard behaviour. slCardLink only matches an anchor, so Enter, the context menu and middle-click are the platform’s.
+- The link 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 slCardLink, 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 slCardActions or the footer instead.
+- slCardActions and slCardFooter 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 link 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 an slDivider 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
+
+```html
+<div slCard>
+  <div slCardHeader><h3 slHeading [level]="3">Review pictures</h3></div>
+  <hr slDivider decorative />
+  <div slCardBody>Two hundred images since the last visit.</div>
+  <hr slDivider decorative inset />
+  <div slCardFooter>
+    <span slText size="xs" tone="muted">The inset rule lines up with the text</span>
+  </div>
+</div>
+```
+
+### One destination, named by the title
+
+Excerpt — not a complete module
+
+```html
+<div slCard>
+  <div slCardHeader>
+    <a slCardLink href="/accounts/northwind">Northwind Traders</a>
+  </div>
+  <div slCardBody>Twelve open invoices</div>
+  <div slCardFooter>
+    <a href="/accounts/northwind/settings">Billing settings</a>
+  </div>
+</div>
+```
+
+### A chooser, where the radio owns the state
+
+Excerpt — not a complete module
+
+```html
+<label slCard [selected]="plan() === 'team'">
+  <div slCardHeader>
+    <span slCardSelection>
+      <input type="radio" name="plan" value="team" [(ngModel)]="plan" />
+    </span>
+    <h3 slHeading [level]="3">Team</h3>
+    <span slText size="sm" tone="muted">Twenty seats and shared billing</span>
+  </div>
+</label>
+```
+
+### Media beside the content, until the card is narrow
+
+Excerpt — not a complete module
+
+```html
+<div slCard orientation="horizontal">
+  <figure slCardMedia><img alt="" [src]="report.cover" /></figure>
+  <div slCardHeader>
+    <h3 slHeading [level]="3">Quarterly report</h3>
+  </div>
+  <div slCardBody>Revenue, retention and the accounts that moved them.</div>
+</div>
+```