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

package/docs/command-palette.md

@@ -0,0 +1,419 @@
+<!-- index: ./index.md -->
+# command-palette
+
+`data-ui="command-palette"` · Searchable dialog of commands and destinations.
+
+## Import
+
+```ts
+import { SlCommandPalette, SlCommandPaletteTrigger, SlCommandPaletteItem, provideCommandPaletteDefaults } from '@slotted/angular/command-palette';
+```
+
+Selector: `sl-command-palette, [slCommandPaletteTrigger], ng-template[slCommandPaletteItem]` · exportAs: `slCommandPalette`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button slButton [slCommandPaletteTrigger]="palette">Search</button>
+<sl-command-palette
+  #palette="slCommandPalette"
+  [items]="items"
+  [groups]="groups"
+  (select)="run($event.item.id)"
+/>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `trigger` | button | no |
+| `header` | div | yes |
+| `search` | span | no |
+| `busy` | span | no |
+| `pages` | ol | no |
+| `page` | button | no |
+| `input` | input | yes |
+| `clear` | button | yes |
+| `close` | button | no |
+| `list` | div | yes |
+| `group` | div | no |
+| `group-label` | div | no |
+| `item` | div \| a | no |
+| `icon` | span | no |
+| `label` | span | no |
+| `match` | mark | no |
+| `description` | span | no |
+| `meta` | span | no |
+| `shortcut` | span | no |
+| `arrow` | span | no |
+| `separator` | div | no |
+| `empty` | div | no |
+| `status` | div | yes |
+| `placeholder` | div | no |
+| `footer` | div | no |
+| `hint` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `CommandPaletteItem[]` | — | sl-command-palette | The commands: id, label, keywords, description, group, meta, shortcut, href, target, disabled, onSelect, children |
+| `groups` | `CommandGroup[]` | — | sl-command-palette | The headings and their order; a group not listed is drawn after them under its own id |
+| `rank` | `CommandRanker \| null` | the core ranker | sl-command-palette | (item, query) => number \| null. Absent takes the locale-sensitive core ranker; null shows the items as they came |
+| `locale` | `string` | — | sl-command-palette | BCP 47, for the comparison the default ranker and the match mark make |
+| `limit` | `number` | — | sl-command-palette | How many rows to draw at most, across groups in reading order |
+| `open` | `model<boolean>` | false | sl-command-palette | model(): the layer’s state, two-way with [(open)] |
+| `query` | `model<string>` | '' | sl-command-palette | model(): the text, two-way with [(query)] |
+| `highlightedId` | `model<string \| null>` | null | sl-command-palette | model(): the current row; autoHighlight moves it to the first row |
+| `pages` | `model<string[]>` | [] | sl-command-palette | model(): the ids of the open pages, oldest first |
+| `recent` | `model<string[]>` | [] | sl-command-palette | model(): the ids the reader ran recently, newest first |
+| `presentation` | `'dialog' \| 'inline'` | dialog | sl-command-palette | dialog composes the dialog family; inline draws the panel where it was written |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-command-palette | The dialog’s measure and the row’s control step |
+| `outsidePress` | `'close' \| 'none'` | close | sl-command-palette | Whether a press on the scrim closes the palette |
+| `loop` | `boolean` | true | sl-command-palette | Whether ArrowDown on the last row wraps to the first |
+| `autoHighlight` | `boolean` | true | sl-command-palette | Whether the first enabled row is current on open and after every change of the rows |
+| `closeOnSelect` | `boolean` | true | sl-command-palette | Whether running a row closes the palette; keepOpen() on the request holds it open once |
+| `clearOnClose` | `boolean` | true | sl-command-palette | Whether closing empties the query and the pages, each through its own request |
+| `highlightMatch` | `boolean` | true | sl-command-palette | Whether the run the query matched is marked in the label |
+| `hotkey` | `string \| null` | mod+k | sl-command-palette | The chord that opens the palette from anywhere; null for none. A bare key stays quiet in an editable field |
+| `recentLimit` | `number` | 5 | sl-command-palette | How many recents are kept |
+| `loading` | `boolean` | false | sl-command-palette | The ring in the header, three skeleton rows when there is nothing to show, aria-busy on the list, the loading message in the status row |
+| `disabled` | `boolean` | false | sl-command-palette | Disables the field, the trigger and the hotkey |
+| `hideFooter` | `boolean` | false | sl-command-palette | Removes the footer; an ng-template[slCommandPaletteFooter] replaces it instead |
+| `container` | `Element \| null` | — | sl-command-palette | A parent for the layer alone, instead of the portal root the dialog makes beside this host |
+| `messages` | `Partial<CommandPaletteMessages>` | — | sl-command-palette | Words laid over the language in force, key by key: the dialog’s name (label), the field’s name and placeholder (input, placeholder), the empty, loading, count and error sentences, the recents heading, the clear, close and back controls, and the footer’s hints |
+| `slCommandPaletteTrigger` | `SlCommandPalette` | — | [slCommandPaletteTrigger] | The instance the control opens, reached with a template reference variable |
+| `ng-template[slCommandPaletteItem]` | `let-item, let-current, let-disabled, let-pending, let-query, let-runs` | — | sl-command-palette | Replaces the row’s content; the option element and its wiring stay the family’s. runs is the marked label |
+| `ng-template[slCommandPaletteEmpty]` | `—` | — | sl-command-palette | Replaces the empty message |
+| `ng-template[slCommandPaletteFooter]` | `—` | — | sl-command-palette | Replaces the footer |
+| `exportAs` | `slCommandPalette` | — | sl-command-palette | openPalette(), close(), toggle(), focus(), setQuery(), setHighlighted(), setPages(), scrollToId() |
+| `[slCommandPaletteTrigger]` | `directive` | — | the consumer’s button | Writes data-part="trigger", aria-haspopup, aria-expanded and data-open on the consumer’s own element and registers it as the layer’s focus origin |
+| `provideCommandPaletteDefaults` | `Partial<CommandPaletteDefaults>` | — | the injector | Every axis, set once; an explicit input still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `openChange / openChangeRequest` | `boolean / ChangeRequest<boolean>` | Before the palette opens or closes; reason is pointer, keyboard, escape, outsidePress, select, dismiss or programmatic. request.cancel() refuses it; the model updates after. |
+| `queryChange / queryChangeRequest` | `string / ChangeRequest<string>` | Before the query moves: keyboard as the reader types, clear from the clear control or Escape, select when a page opens, programmatic on close and from setQuery(). |
+| `highlightedIdChange / highlightedIdChangeRequest` | `string \| null / ChangeRequest<string \| null>` | Before the current row moves: pointer, keyboard, or programmatic when the rows changed under it. |
+| `pagesChange / pagesChangeRequest` | `string[] / ChangeRequest<readonly string[]>` | Before a page opens or closes: select from Enter on a row with children, pointer from a click on one or on the trail, keyboard from Backspace or Escape, programmatic on close. |
+| `recentChange / recentChangeRequest` | `string[] / ChangeRequest<readonly string[]>` | After a row ran, with its id moved to the front and the array cut at recentLimit; reason select. |
+| `select` | `{ item, reason, source, keepOpen() }` | When a row runs, after the row’s own onSelect and after a returned promise fulfilled; reason pointer or keyboard. Never for a disabled row or a row that opens a page. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `presentation` | `dialog`, `inline` | `dialog` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `outsidePress` | `close`, `none` | `close` |
+| `loop` | `true`, `false` | `true` |
+| `autoHighlight` | `true`, `false` | `true` |
+| `closeOnSelect` | `true`, `false` | `true` |
+| `clearOnClose` | `true`, `false` | `true` |
+| `highlightMatch` | `true`, `false` | `true` |
+| `loading` | `true`, `false` | `false` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- The field carries role="combobox" with aria-expanded="true", aria-controls naming the list and aria-autocomplete="list"; the list carries role="listbox" and each row role="option". DOM focus stays on the field for the whole interaction and the current row is named by aria-activedescendant and marked aria-selected — the WAI-ARIA combobox pattern with a listbox popup, whose note says exactly this.
+- The layer is the dialog family’s: role="dialog", aria-modal, the page inert behind the scrim, focus contained and returned to the trigger. Its name is the label message, pointed at through a hidden title the dialog labels itself by; the field’s name is the input message, and the list borrows it.
+- A row with a shortcut carries aria-keyshortcuts in the platform’s own words — Meta+Shift+D on a Mac, Control+Shift+D elsewhere — while the drawn keys are aria-hidden; a sequence has no syntax in the attribute and is drawn only. A disabled row is announced with aria-disabled, stays in the list, and is skipped by every movement key.
+- The result count, the loading sentence and the failure of a rejected handler are one visually hidden role="status" row, spoken through the shared live announcer so the same sentence is never said twice in a row.
+- Escape is three steps in a fixed order — clear the query, return one page, close — so a reader who typed does not lose the palette on the first press; the footer draws the same keys the family answers.
+- The panel answers its own width: below 360 pixels the description and the meta go and the binding stays; inside a dialog on a narrow screen the panel takes the whole layer.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-command-palette-active`, `--slotted-command-palette-border-color`, `--slotted-command-palette-footer-surface`, `--slotted-command-palette-highlight`, `--slotted-command-palette-highlight-ring`, `--slotted-command-palette-hover`, `--slotted-command-palette-item-radius`, `--slotted-command-palette-list-max-block-size`, `--slotted-command-palette-list-padding`, `--slotted-command-palette-measure`, `--slotted-command-palette-page-surface`, `--slotted-command-palette-placeholder-fade`, `--slotted-command-palette-radius`, `--slotted-command-palette-separator-color`, `--slotted-command-palette-shadow`, `--slotted-command-palette-surface`, `--slotted-command-palette-text`, `--slotted-command-palette-text-muted`, `--slotted-control-font-size-lg`, `--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-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-lg`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-line-height-xs`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-shadow-lg`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### Every part, inline
+
+The same panel with no layer around it, so every part can be pointed at: the header with its mark and clear, the grouped list, the current row, a row with a description and a binding, and the footer of hints.
+
+Excerpt — not a complete module
+
+```ts
+const items: CommandPaletteItem[] = [
+  {
+    id: 'deploy',
+    label: 'Deploy to production',
+    description: 'Ship the current release of api-gateway',
+    keywords: ['ship', 'release'],
+    group: 'actions',
+    shortcut: 'mod+shift+d',
+    onSelect: () => this.deploy(),
+  },
+];
+```
+
+### Groups, in the order the product declares
+
+groups gives each heading its label and its place; an item whose group is not listed lands under its own id, after them, and an item with no group closes the list.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette
+  presentation="inline"
+  [items]="items"
+  [groups]="[
+    { id: 'nav', label: 'Go to' },
+    { id: 'actions', label: 'Actions' },
+  ]"
+/>
+```
+
+### Ranking, and the adapter
+
+Type “dep”: a label that starts with it outranks a word that starts with it, which outranks a run inside a word, which outranks a keyword; groups reorder by their best row. The third panel hands the order to a ranker of the product’s own.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette presentation="inline" query="dep" [items]="items" />
+
+<!-- A server has already ranked the list: show it as it came. -->
+<sl-command-palette presentation="inline" [items]="results" [rank]="null" />
+
+<!-- Or score it yourself. -->
+<sl-command-palette presentation="inline" [items]="items" [rank]="byWeight" />
+```
+
+### Pages, stacked
+
+A row with children opens a page: the trail appears before the field, the children take the list, and Backspace on an empty query or Escape returns one page. pages is state the product may own through the model.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette presentation="inline" [items]="items" [(pages)]="pages" />
+```
+
+### What the reader ran last
+
+With nothing typed, the recents open the list under their own heading; running a row moves it to the front and cuts the array at recentLimit. Persisting it is the product’s — it receives the array through the model.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette
+  presentation="inline"
+  [items]="items"
+  [(recent)]="recent"
+  [recentLimit]="3"
+  (recentChangeRequest)="persist($event.value)"
+/>
+```
+
+### Shortcuts, drawn for the platform
+
+One notation, mod+shift+d, becomes ⌘⇧D on a Mac and Ctrl+Shift+D elsewhere, and is announced as Meta+Shift+D or Control+Shift+D. A sequence such as g i is drawn and not announced. The palette binds none of them: the lines below do.
+
+Excerpt — not a complete module
+
+```ts
+class Shell {
+  private readonly platformOf = injectKbdPlatform();
+
+  @HostListener('document:keydown', ['$event'])
+  onKey(event: KeyboardEvent) {
+    const platform = this.platformOf();
+    const hit = this.items.find(
+      (item) => item.shortcut && matchesShortcut(event, item.shortcut, platform),
+    );
+    if (hit) hit.onSelect?.();
+  }
+}
+```
+
+### Rows that are places
+
+A row with href renders as a link with role option: Enter follows it, ⌘Enter opens it in a new tab because the browser, not the palette, answers the modifier. meta says what kind of place it is.
+
+Excerpt — not a complete module
+
+```ts
+const items: CommandPaletteItem[] = [
+  { id: 'billing', label: 'Billing', href: '/settings/billing', meta: 'Page' },
+  { id: 'invoice', label: 'Download last invoice', onSelect: () => this.download() },
+];
+```
+
+### A command that takes a while
+
+A handler that returns a promise keeps the palette open and the row busy, refuses a second run of the same row until it settles, then closes; a rejection keeps it open and the status row says why. Press the first row and wait two seconds.
+
+Excerpt — not a complete module
+
+```ts
+const items: CommandPaletteItem[] = [
+  { id: 'restart', label: 'Restart api-gateway', onSelect: () => this.api.restart('api-gateway') },
+  {
+    id: 'purge',
+    label: 'Purge CDN cache',
+    onSelect: () => Promise.reject(new Error('Not allowed')),
+  },
+];
+```
+
+### While the results travel
+
+loading swaps the magnifier for the ring, draws three skeleton rows when there is nothing to show yet, and says the loading message in the status row. The palette debounces nothing: the product does, in a few lines.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette [items]="results()" [loading]="loading()" [rank]="null" [(query)]="query" />
+```
+
+### Nothing matched
+
+The empty part takes the list, the count row says “0 results”, and the root carries data-empty. The second panel replaces the sentence with the product’s own template.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette presentation="inline" query="xylophone" [items]="items">
+  <ng-template slCommandPaletteEmpty>No command matches. Try a service name.</ng-template>
+</sl-command-palette>
+```
+
+### Without a layer
+
+presentation="inline" draws the panel where it was written — here inside a popover on an “Assign to” button — with no scrim, no hotkey and no Escape to close. It is the filtered menu that menu refused.
+
+Excerpt — not a complete module
+
+```html
+<ng-container slPopover>
+  <button slButton slPopoverTrigger>Assign to…</button>
+  <ng-template slPopoverLayer>
+    <div slPopoverContent aria-label="Assign to">
+      <sl-command-palette presentation="inline" hideFooter [items]="people" />
+    </div>
+  </ng-template>
+</ng-container>
+```
+
+### Three measures
+
+size is the dialog’s measure — 24, 32 and 42 rems — and the row’s step: sm rows read the small control geometry, lg rows the large, and the header stands one step above the rows in each.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette presentation="inline" size="sm" [items]="items" />
+<sl-command-palette presentation="inline" size="lg" [items]="items" />
+```
+
+### Every state a row can be in
+
+At rest, current from the keyboard, busy while its handler runs, disabled but announced and kept in place, opening a page, and a link. Hover a row that is not current for the quieter wash.
+
+Excerpt — not a complete module
+
+```ts
+const items: CommandPaletteItem[] = [
+  {
+    id: 'delete',
+    label: 'Delete workspace',
+    description: 'Requires the owner role',
+    disabled: true,
+  },
+];
+```
+
+### Content the family did not choose
+
+A German label of sixty characters, a description longer than the row, a binding of four keys and a row with a short label beside it: the label gives way, the binding never does, and the rows stay one line each.
+
+Excerpt — not a complete module
+
+```ts
+const items: CommandPaletteItem[] = [
+  {
+    id: 'sync',
+    label: 'Benachrichtigungseinstellungen für alle Arbeitsbereiche synchronisieren',
+    shortcut: 'mod+shift+alt+p',
+  },
+];
+```
+
+### The chord that opens it
+
+mod+k by default, matched on the document in the capture phase with preventDefault, so Firefox’s search bar does not answer first. A bare key such as / stays quiet inside a text field; [hotkey]="null" turns it off. Focus the page and press ⌘K or Ctrl+K.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette hotkey="mod+p" [items]="items" />
+<sl-command-palette hotkey="/" [items]="items" />
+<sl-command-palette [hotkey]="null" [items]="items" />
+```
+
+### Set once for the application
+
+The provider holds every axis, and provideSlotted the language the family speaks: the panel below reads Portuguese words, a size and a hotkey it did not state itself.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideSlotted({ locale: 'pt-BR' }),
+    provideCommandPaletteDefaults({ hotkey: 'mod+p', size: 'sm' }),
+  ],
+});
+```
+
+### In an application’s top bar
+
+The trigger is a search-shaped slButton with a kbd in it, carrying slCommandPaletteTrigger; the row content is the product’s own through an item template, with an avatar where the icon column is.
+
+Excerpt — not a complete module
+
+```html
+<button slButton tone="secondary" variant="outline" [slCommandPaletteTrigger]="palette">
+  Search people <kbd slKbd size="sm">⌘K</kbd>
+</button>
+<sl-command-palette #palette="slCommandPalette" [items]="people">
+  <ng-template slCommandPaletteItem let-item let-query="query">
+    <span data-part="icon"><sl-avatar [name]="item.label" size="xs" /></span>
+    <span data-part="label">
+      <span slHighlight [text]="item.label" [query]="query"></span>
+    </span>
+  </ng-template>
+</sl-command-palette>
+```
+
+### The keys
+
+Arrows move and wrap, PageUp and PageDown move ten and stop, Ctrl+Home and Ctrl+End reach the ends, Home and End keep moving the caret, Enter runs, Escape clears then returns a page then closes, Backspace on an empty query returns a page.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette presentation="inline" [items]="items" />
+```
+
+### What a screen reader meets
+
+The dialog is named by the label message, the field by the input message, the list by the same; the current row is aria-selected and named by aria-activedescendant; the count, the wait and a failure are one live region. Open the tree to read it.
+
+Excerpt — not a complete module
+
+```html
+<sl-command-palette
+  [messages]="{ label: 'Deployment commands', input: 'Search deployments' }"
+  [items]="items"
+/>
+```

package/docs/container.json

@@ -0,0 +1,156 @@
+{
+  "family": "container",
+  "ui": "container",
+  "binding": "angular",
+  "catalog": {
+    "group": "Layout",
+    "summary": "Centers content at a maximum width."
+  },
+  "axes": {
+    "size": [
+      "measure",
+      "content",
+      "wide",
+      "full",
+      "bleed"
+    ],
+    "inset": [
+      "0",
+      "1",
+      "2",
+      "3",
+      "4",
+      "5",
+      "6",
+      "7",
+      "8",
+      "9",
+      "10",
+      "11",
+      "12"
+    ],
+    "align": [
+      "center",
+      "start",
+      "end"
+    ]
+  },
+  "members": {
+    "container": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "content",
+        "inset": "6",
+        "align": "center"
+      },
+      "capabilities": [
+        "size"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "breakout"
+      ]
+    }
+  },
+  "docs": {
+    "container": {
+      "imports": null,
+      "anatomy": [],
+      "api": [
+        {
+          "name": "size",
+          "type": "'measure' | 'content' | 'wide' | 'full' | 'bleed'",
+          "defaultValue": "content",
+          "appliesTo": "slContainer",
+          "description": "What the column bounds. measure is the comfortable reading line, counted in characters; full is the space the frame gives up to --slotted-container-full, 120rem; bleed removes the maximum. Both keep the inset"
+        },
+        {
+          "name": "inset",
+          "type": "0 | 1 | … | 12",
+          "defaultValue": "6",
+          "appliesTo": "slContainer",
+          "description": "The gap between the column and the edge of the space the container was given, as a step on the space scale"
+        },
+        {
+          "name": "align",
+          "type": "'center' | 'start' | 'end'",
+          "defaultValue": "center",
+          "appliesTo": "slContainer",
+          "description": "Where the column sits when there is space left over. Logical, so a right-to-left document mirrors"
+        },
+        {
+          "name": "render",
+          "type": "—",
+          "defaultValue": "—",
+          "appliesTo": "slContainer, slContainerBreakout",
+          "description": "Not needed: both are written on the element the template already chose, so the element is never substituted"
+        }
+      ],
+      "composition": [],
+      "events": [],
+      "accessibility": [
+        "Container has no role and no ARIA. It bounds what the template wrote, and the children keep whatever semantics they already had. The directive goes on a main, a section or an article so the document says what it means.",
+        "size=\"measure\" bounds the line at 65ch. WCAG 2.2 SC 1.4.8 asks for no more than 80 characters per line, and technique C20 asks that the width be set in a relative measurement; ch is relative to the inherited type, so the bound follows a reader who enlarges the text rather than fighting them.",
+        "Every other step is stated in rem, so the whole page grows with the browser zoom WCAG SC 1.4.4 requires.",
+        "The column collapses continuously through min(), and every child is allowed to shrink below its content, so a long unbroken token overflows its own box rather than widening the page — the two-axis scroll SC 1.4.10 refuses.",
+        "Nothing reorders children. Visual order stays DOM order, which is what SC 1.3.2 asks for, and a breakout is read where it is written.",
+        "The root is a grid, so a run of text written directly inside it becomes an item nothing can place in the column. Wrap text in an element."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-container-content",
+    "--slotted-container-full",
+    "--slotted-container-measure",
+    "--slotted-container-wide",
+    "--slotted-space-1",
+    "--slotted-space-10",
+    "--slotted-space-11",
+    "--slotted-space-12",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-space-8",
+    "--slotted-space-9"
+  ],
+  "examples": [
+    {
+      "id": "container-angular-page",
+      "title": "A reading page holding a table that reaches both edges",
+      "note": null,
+      "language": "html",
+      "source": "<main slContainer size=\"measure\">\n  <div slStack [gap]=\"6\">\n    <h1 slHeading level=\"1\">Usage this month</h1>\n    <p slText>Billed per seat, settled with the invoice.</p>\n  </div>\n  <div slContainerBreakout>\n    <app-usage-table />\n  </div>\n  <p slText>Bounded content resumes at the same column.</p>\n</main>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "container-angular-nested",
+      "title": "Bounded content returns inside a breakout",
+      "note": null,
+      "language": "html",
+      "source": "<article slContainer size=\"measure\">\n  <app-article />\n  <aside slContainerBreakout class=\"sunken\">\n    <div slContainer size=\"wide\" [inset]=\"9\">\n      <app-related-accounts />\n    </div>\n  </aside>\n</article>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "container-angular-defaults",
+      "title": "An application decides once what its pages are bounded to",
+      "note": null,
+      "language": "ts",
+      "source": "import { provideContainerDefaults } from '@slotted/angular/container';\n\nbootstrapApplication(App, {\n  providers: [provideContainerDefaults({ inset: 8, size: 'wide' })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "container-maxima",
+      "title": "Retuning the maxima, which is the whole theming story",
+      "note": null,
+      "language": "css",
+      "source": "[data-slotted-theme='acme'] {\n  --slotted-container-measure: 60ch;\n  --slotted-container-content: 48rem;\n  --slotted-container-wide: 90rem;\n}\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/container.md

@@ -0,0 +1,92 @@
+<!-- index: ./index.md -->
+# container
+
+`data-ui="container"` · Centers content at a maximum width.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<main slContainer size="measure">
+  <div slStack [gap]="6">
+    <h1 slHeading level="1">Usage this month</h1>
+    <p slText>Billed per seat, settled with the invoice.</p>
+  </div>
+  <div slContainerBreakout>
+    <app-usage-table />
+  </div>
+  <p slText>Bounded content resumes at the same column.</p>
+</main>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'measure' \| 'content' \| 'wide' \| 'full' \| 'bleed'` | content | slContainer | What the column bounds. measure is the comfortable reading line, counted in characters; full is the space the frame gives up to --slotted-container-full, 120rem; bleed removes the maximum. Both keep the inset |
+| `inset` | `0 \| 1 \| … \| 12` | 6 | slContainer | The gap between the column and the edge of the space the container was given, as a step on the space scale |
+| `align` | `'center' \| 'start' \| 'end'` | center | slContainer | Where the column sits when there is space left over. Logical, so a right-to-left document mirrors |
+| `render` | `—` | — | slContainer, slContainerBreakout | Not needed: both are written on the element the template already chose, so the element is never substituted |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `measure`, `content`, `wide`, `full`, `bleed` | `content` |
+| `inset` | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12` | `6` |
+| `align` | `center`, `start`, `end` | `center` |
+
+## Rules
+
+- Container has no role and no ARIA. It bounds what the template wrote, and the children keep whatever semantics they already had. The directive goes on a main, a section or an article so the document says what it means.
+- size="measure" bounds the line at 65ch. WCAG 2.2 SC 1.4.8 asks for no more than 80 characters per line, and technique C20 asks that the width be set in a relative measurement; ch is relative to the inherited type, so the bound follows a reader who enlarges the text rather than fighting them.
+- Every other step is stated in rem, so the whole page grows with the browser zoom WCAG SC 1.4.4 requires.
+- The column collapses continuously through min(), and every child is allowed to shrink below its content, so a long unbroken token overflows its own box rather than widening the page — the two-axis scroll SC 1.4.10 refuses.
+- Nothing reorders children. Visual order stays DOM order, which is what SC 1.3.2 asks for, and a breakout is read where it is written.
+- The root is a grid, so a run of text written directly inside it becomes an item nothing can place in the column. Wrap text in an element.
+
+## Tokens
+
+`--slotted-container-content`, `--slotted-container-full`, `--slotted-container-measure`, `--slotted-container-wide`, `--slotted-space-1`, `--slotted-space-10`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`
+
+## Examples
+
+### Bounded content returns inside a breakout
+
+Excerpt — not a complete module
+
+```html
+<article slContainer size="measure">
+  <app-article />
+  <aside slContainerBreakout class="sunken">
+    <div slContainer size="wide" [inset]="9">
+      <app-related-accounts />
+    </div>
+  </aside>
+</article>
+```
+
+### An application decides once what its pages are bounded to
+
+Excerpt — not a complete module
+
+```ts
+import { provideContainerDefaults } from '@slotted/angular/container';
+
+bootstrapApplication(App, {
+  providers: [provideContainerDefaults({ inset: 8, size: 'wide' })],
+});
+```
+
+### Retuning the maxima, which is the whole theming story
+
+Excerpt — not a complete module
+
+```css
+[data-slotted-theme='acme'] {
+  --slotted-container-measure: 60ch;
+  --slotted-container-content: 48rem;
+  --slotted-container-wide: 90rem;
+}
+```