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

package/docs/toggle.md

@@ -0,0 +1,222 @@
+<!-- index: ./index.md -->
+# toggle
+
+`data-ui="toggle"` · Button that stays pressed or unpressed.
+
+## Import
+
+```ts
+import { provideToggleDefaults, SlToggle, SlToggleIcon } from '@slotted/angular/toggle';
+```
+
+Selector: `button[slToggle]` · exportAs: `slToggle`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<button slToggle defaultPressed>
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Quebrar linhas
+</button>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own button, with slToggle on it | yes |
+| `icon` | the consumer’s own element, with slToggleIcon on it | no |
+| `label` | span, always rendered; empty when the button projects no words | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `pressed` | `boolean` | — | slToggle | Bound, the consumer owns the state for the life of the component. Unbound, the toggle owns it and starts from defaultPressed |
+| `defaultPressed` | `boolean` | false | slToggle | What an uncontrolled toggle starts from, read once. A later change to it does not silently become new state |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slToggle | The control step. It reads the control scale, so the toggle is as tall as the field beside it |
+| `variant` | `'outline' \| 'ghost'` | outline | slToggle | Whether the control draws its own edge before it is on. There is no tone axis: a mode is one colour when it is on, and an action that persists in one of five tones is button’s ToggleButton |
+| `disabled` | `boolean` | false | slToggle | The native attribute, which is also what makes the browser refuse focus. A toggle that is on and unavailable keeps saying both |
+| `type` | `'button' \| 'submit' \| 'reset'` | button | slToggle | The native attribute, kept when the consumer wrote it. A toggle in a form is not a form control — checkbox and switch are — so it is a button unless the consumer says otherwise |
+| `slToggle` | `directive on a button` | — | the consumer’s element | The component is a directive on the consumer’s own button: every attribute, every listener and every structural directive around it stay as written. It stays a button, because aria-pressed on a link is a link announcing a state a link does not hold |
+| `slToggleIcon` | `directive on any element` | — | inside the button | The mark, projected before the words and hidden from the reading order. An ng-icon, an inline svg or a masked span all work and none loses its own semantics |
+| `exportAs` | `'slToggle'` | — | a template reference | Reaches the instance, so a template can read isPressed(), resolvedSize() or resolvedVariant() without the component owning a second copy of the state |
+| `provideToggleDefaults()` | `(defaults: Partial<ToggleDefaults>) => Provider` | — | an injector | The two decisions an application takes once, at the root or on one route. A toggle that states either itself still wins |
+| `type` | `string` | button | slToggle | Read from the host with HostAttributeToken before the host binding writes, so a consumer’s own submit survives |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `pressedChange` | `ChangeRequest<boolean>` | Before the state moves. The request carries the new value, the value it replaces, the reason — pointer or keyboard — the originating event, and cancel(), which refuses the move before anything commits. Nothing is emitted for a value equal to the one the toggle already holds. |
+| `(click), (focus), (blur)` | `the element’s own events` | Whenever the button fires them. The family listens after the view is created, so a (click) written on the same element runs first; calling preventDefault() in it stops the toggle as well. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `ghost` | `outline` |
+
+## Rules
+
+- The APG Button pattern’s toggle button (w3.org/WAI/ARIA/apg/patterns/button/): a native button with aria-pressed, and no navigation pattern around it — a single control has no arrows of its own.
+- aria-pressed is written in both states, so the control is announced as a toggle rather than as a button that happens to be pressed — and the label never changes with the state, which the pattern calls critical. A toggle with only a mark takes its name from an aria-label the consumer writes.
+- Inside slToolbar the bar owns the tab stop and the arrows and reaches this control as it reaches every focusable control it holds; the family writes no listener. Space and Enter press it, from the platform.
+- disabled is the native attribute, because that is also what makes the browser refuse focus and skip the control. The toggle is not a form control and implements no ControlValueAccessor: a value a form submits is checkbox or switch.
+- The target is the control itself, never narrower than it is tall, so the WCAG 2.2 minimum of 24 by 24 holds at the smallest step and the tightest density — and the theme grows every control to 44 under a coarse pointer.
+
+## Tokens
+
+`--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-font-weight`, `--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-letter-spacing`, `--slotted-control-line-height`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-text`, `--slotted-toggle-active-background`, `--slotted-toggle-border-color`, `--slotted-toggle-color`, `--slotted-toggle-disabled-border-color`, `--slotted-toggle-disabled-color`, `--slotted-toggle-disabled-pressed-background`, `--slotted-toggle-hover-background`, `--slotted-toggle-pressed-background`, `--slotted-toggle-pressed-border-color`, `--slotted-toggle-pressed-color`, `--slotted-toggle-pressed-hover-background`, `--slotted-toggle-radius`, `--slotted-toggle-shadow`, `--slotted-tone-accent-border`, `--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
+
+### Owned by the consumer, or by the toggle
+
+The left toggle owns its state and starts from defaultPressed. The right one is controlled: the page holds the value, the toggle asks with a request carrying the reason, and the page decides. Both announce “pressed” the same way.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle [pressed]="wrap()" (pressedChange)="wrap.set($event.value)">
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Quebrar linhas
+</button>
+```
+
+### Framed, or bare until it is on
+
+outline draws its own edge and stands beside a field; ghost is the toggle inside something already framed — a toolbar, a card header. Both turn on into the same accent pair, so “on” is one colour wherever the control is.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle variant="ghost">
+  <ng-icon slToggleIcon name="lucidePin" />
+  Fixar cabeçalho
+</button>
+```
+
+### Three steps, one control tall
+
+Every step reads the control scale, so a toggle beside a text field of the same step lines up with it to the pixel — and the density switch in the toolbar moves both together.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle size="sm">
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Quebrar
+</button>
+```
+
+### A mark and no words
+
+Without children the toggle draws square from the control height and the mark is centred in it. The name comes from aria-label, and the type makes nothing of that: the reference page is where the rule is stated, and the harness photographs it.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle aria-label="Negrito" defaultPressed>
+  <ng-icon slToggleIcon name="lucideBold" />
+</button>
+```
+
+### Every state the contract declares
+
+Hover takes the neutral ground when off and the accent ground’s own hover step when on. Disabled keeps both facts of a toggle that is on: the ground says unavailable and the edge still says on, so the reader learns the mode from a control they cannot change.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle defaultPressed disabled>
+  <ng-icon slToggleIcon name="lucidePin" />
+  Fixar cabeçalho
+</button>
+```
+
+### Inside a toolbar
+
+The bar is one tab stop with arrow navigation across every control it holds, and a toggle is one of those controls: Tab reaches the bar once, the arrows reach the toggle, Space presses it. The family writes no listener of its own.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Editor">
+  <button slToggle variant="ghost" aria-label="Negrito">
+    <ng-icon slToggleIcon name="lucideBold" />
+  </button>
+  <button slToggle variant="ghost" aria-label="Itálico">
+    <ng-icon slToggleIcon name="lucideItalic" />
+  </button>
+  <hr slToolbarSeparator />
+  <button slToggle variant="ghost">
+    <ng-icon slToggleIcon name="lucideWrapText" />
+    Quebrar
+  </button>
+</div>
+```
+
+### Content the family did not choose
+
+A long translated label in a narrow column clamps at the ellipsis and keeps its string whole in the DOM; a right-to-left document mirrors the mark to the other side of the words. Switch the direction in the toolbar to see the second.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle>
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Zeilenumbruch aktivieren
+</button>
+```
+
+### Defaults once, and the consumer’s own element
+
+provideToggleDefaults() sets size and variant for every toggle under an injector; a toggle that states either itself still wins. The directive sits on the consumer’s own button, so an analytics attribute or a template reference is written where it always was.
+
+Excerpt — not a complete module
+
+```html
+<!-- providers: [provideToggleDefaults({ size: 'sm', variant: 'ghost' })] -->
+<button slToggle #pin="slToggle" data-track="pin" (click)="track(pin.isPressed())">
+  <ng-icon slToggleIcon name="lucidePin" />
+  Fixar
+</button>
+```
+
+### The keyboard, key by key
+
+Tab reaches the control; Space and Enter turn it on and off; nothing else is bound. The request that reaches the consumer says keyboard rather than pointer, and the line below shows which one it saw.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle (pressedChange)="log($event.reason)">
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Quebrar linhas
+</button>
+```
+
+### Toggle, or ToggleButton
+
+A mode is one colour and true the moment it is pressed: Toggle. An action that persists — Follow, Subscribe — reaches a server, waits, and stands in one of five tones beside the other actions of a page: button’s ToggleButton. Same state model, different meaning.
+
+Excerpt — not a complete module
+
+```html
+<button slToggle>
+  <ng-icon slToggleIcon name="lucideWrapText" />
+  Quebrar linhas
+</button>
+<button
+  slToggleButton
+  [loading]="following()"
+  [pressed]="followed()"
+  (pressedChange)="follow($event)"
+>
+  Seguir
+</button>
+```

package/docs/toolbar.json

@@ -0,0 +1,380 @@
+{
+  "family": "toolbar",
+  "ui": "toolbar",
+  "binding": "angular",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Group of controls with arrow-key navigation."
+  },
+  "axes": {
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "outline"
+    ],
+    "overflow": [
+      "wrap",
+      "scroll",
+      "menu"
+    ]
+  },
+  "members": {
+    "toolbar": {
+      "nativeElement": "div",
+      "defaults": {
+        "orientation": "horizontal",
+        "size": "md",
+        "variant": "plain",
+        "overflow": "wrap",
+        "loop": true
+      },
+      "capabilities": [
+        "orientation",
+        "size",
+        "appearance",
+        "overflow"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "group",
+        "separator",
+        "spacer",
+        "item",
+        "overflow"
+      ]
+    }
+  },
+  "docs": {
+    "toolbar": {
+      "imports": {
+        "source": "import { SlToolbar, SlToolbarGroup, SlToolbarItem, SlToolbarOverflow, SlToolbarSeparator, SlToolbarSpacer } from '@slotted/angular/toolbar';",
+        "selector": "[slToolbar], [slToolbarGroup], [slToolbarItem], sl-toolbar-overflow, [slToolbarSeparator], [slToolbarSpacer]",
+        "exportAs": "slToolbar, slToolbarGroup, slToolbarItem, slToolbarOverflow, slToolbarSeparator, slToolbarSpacer"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div[role=\"toolbar\"] carrying slToolbar",
+          "required": true,
+          "purpose": "The bar. Carries data-ui=\"toolbar\", the four axes, aria-orientation when vertical, and the label the consumer wrote. It writes the roving tabindex on every focusable control inside it, which is what makes the whole bar one tab stop."
+        },
+        {
+          "part": "group",
+          "element": "div[role=\"group\"]",
+          "required": false,
+          "purpose": "A run of related controls with a name of its own. The distance inside it is half the bar’s gap and the distance around it is a gap and a half, so the boundary between two groups reads wider than the one between two controls. The arrows do not stop at its edge."
+        },
+        {
+          "part": "separator",
+          "element": "div[role=\"separator\"]",
+          "required": false,
+          "purpose": "A hairline between two runs, with aria-orientation perpendicular to the bar. It is a part of this family rather than a Divider, because its geometry is measured against the controls beside it."
+        },
+        {
+          "part": "spacer",
+          "element": "div",
+          "required": false,
+          "purpose": "The free space between two runs, so what follows sits at the end of the bar. It replaces a justify axis: an axis decides where every control sits, and a bar needs one boundary."
+        },
+        {
+          "part": "item",
+          "element": "div carrying slToolbarItem",
+          "required": false,
+          "purpose": "One unit the bar may give up under overflow=\"menu\", carrying what its control becomes in the surface. A unit is a direct child of the root, which is deliberately not the same thing as an item: the keyboard finds items by being focusable at any depth, and the collapse acts on the boxes the bar lays out. An slButtonGroup inside one of these is one unit and four items."
+        },
+        {
+          "part": "overflow",
+          "element": "button inside sl-toolbar-overflow, carrying the Menu family’s own trigger",
+          "required": false,
+          "purpose": "The control that opens what did not fit. It prints U+2026, its accessible name carries the count, and the bar writes hidden on it while nothing has given way — the same measurement that decides whether it is needed is the one that reveals it to read its width. The host is display: contents, so the button is a child of the bar itself. On a coarse pointer it is the comfortable target wide as well as tall."
+        }
+      ],
+      "api": [
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "slToolbar, provideToolbarDefaults",
+          "description": "Which way the bar runs, and therefore which arrow pair moves between the controls. A vertical bar also writes aria-orientation, which the role’s own default makes unnecessary for a horizontal one"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slToolbar, provideToolbarDefaults",
+          "description": "The bar’s own inset, gap and separator inset, from the control scales. It never touches the controls inside it: a bar that resized another family’s control would own state it cannot see"
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'outline'",
+          "defaultValue": "plain",
+          "appliesTo": "slToolbar, provideToolbarDefaults",
+          "description": "Whether the bar paints a ground and a frame. An outline bar pads itself by at least the reach of a focus ring, so a focused control never sits on the bar’s own edge"
+        },
+        {
+          "name": "overflow",
+          "type": "'wrap' | 'scroll' | 'menu'",
+          "defaultValue": "wrap",
+          "appliesTo": "slToolbar, provideToolbarDefaults",
+          "description": "What a bar does with more controls than it has room for. wrap keeps every control on a second row, scroll is one line the arrows reveal, and menu is one line whose units give way from the end into a surface. A menu bar with no sl-toolbar-overflow in it has nothing to give way to, so it scrolls"
+        },
+        {
+          "name": "overflowChange",
+          "type": "output<number>",
+          "defaultValue": "—",
+          "appliesTo": "slToolbar",
+          "description": "How many units gave way, once per change. There is no two-way binding over the collapsed set: it is a measurement, and a consumer who owned it could assert that a bar fits when the layout says it does not"
+        },
+        {
+          "name": "slToolbarItemCounterpart, slToolbarGroupCounterpart",
+          "type": "TemplateRef",
+          "defaultValue": "—",
+          "appliesTo": "slToolbarItem, slToolbarGroup",
+          "description": "What the unit becomes in the surface when the bar has no room for it, rendered through NgTemplateOutlet only while it is collapsed. A unit that declares none is pinned — pinning is the absence of a counterpart rather than a second input, so the two can never disagree. It is not called overflow, because that word is the bar’s own axis"
+        },
+        {
+          "name": "label",
+          "type": "string | ((hidden: number) => string)",
+          "defaultValue": "counted",
+          "appliesTo": "sl-toolbar-overflow",
+          "description": "The accessible name of the control that holds what did not fit. The default counts — \"3 more actions\" — because three dots say nothing about how much is behind them; a bar in another language replaces the sentence rather than translating the mark, and an aria-label written on the host wins over both"
+        },
+        {
+          "name": "align, side, size",
+          "type": "MenuAlign | MenuSide | MenuSize",
+          "defaultValue": "from provideMenuDefaults",
+          "appliesTo": "sl-toolbar-overflow",
+          "description": "Where the surface sits against the trigger, and its own measure. Everything else about the layer an application sets once with provideMenuDefaults(): a second configuration surface over the same layer would be two answers to one question"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "slToolbar, provideToolbarDefaults",
+          "description": "Whether the arrows wrap past the ends of the bar"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slToolbar, slToolbarGroup",
+          "description": "The name of the bar, and of each group. The family writes neither: only the page knows what the set of controls is for. aria-labelledby works the same way"
+        },
+        {
+          "name": "data-toolbar-keys",
+          "type": "'none' | 'inline' | 'block' | 'all'",
+          "defaultValue": "inferred",
+          "appliesTo": "any item",
+          "description": "Which keys an item keeps for itself. A text entry, a select, a slider, a spin button and a contenteditable keep the flow axis without stating anything; this is how a control the kind cannot describe says so"
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs",
+          "type": "slToolbar | slToolbarGroup | slToolbarItem | slToolbarOverflow | slToolbarSeparator | slToolbarSpacer",
+          "defaultValue": "—",
+          "appliesTo": "every directive",
+          "description": "A template reaches the instance by name: #bar=\"slToolbar\" hands a page the resolved axes, which is what a bar that answers a route needs"
+        },
+        {
+          "name": "the element you write it on",
+          "type": "any element",
+          "defaultValue": "—",
+          "appliesTo": "every directive",
+          "description": "Five of the six parts are directives on the consumer’s own element, so a bar can be a nav and a rule an hr. The overflow is the exception: it is a component, because it renders both the trigger and the surface, and its host is display: contents so the button it draws is still a child of the bar"
+        },
+        {
+          "name": "items",
+          "type": "any focusable descendant",
+          "defaultValue": "—",
+          "appliesTo": "inside slToolbar",
+          "description": "Anything focusable is an item, found in the DOM: this library’s slButton, slLink, slCheckbox, slSwitch and slTextField, a menu trigger, or a consumer’s own control. An element that cannot hold focus is not reachable by the arrows"
+        },
+        {
+          "name": "provideToolbarDefaults()",
+          "type": "{ orientation, size, variant, overflow, loop }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The five decisions an application takes once, in the bootstrap file or on a route. A bar that states any of them itself still wins"
+        },
+        {
+          "name": "collapsedUnits(), counterpart(id)",
+          "type": "signal<ToolbarCollapsedUnit[]>, TemplateRef | null",
+          "defaultValue": "—",
+          "appliesTo": "slToolbar",
+          "description": "What the parts read: the units that gave way, in the order the bar held them, and what each one becomes. A consumer’s own trigger reads the same signals through #bar=\"slToolbar\""
+        },
+        {
+          "name": "fieldset",
+          "type": "the platform’s own element",
+          "defaultValue": "—",
+          "appliesTo": "around a slToolbar",
+          "description": "How a bar is taken out of action. A container cannot disable controls it does not own, and a bar that refused interaction while its controls still looked operable is the defect the state precedence exists to prevent"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The pattern is the WAI-ARIA APG’s Toolbar (w3.org/WAI/ARIA/apg/patterns/toolbar/): the bar is one tab stop, entry lands on the control that last had focus or on the first that is not disabled, the arrows of the flow axis move between the controls and wrap — from row to row when the bar wrapped — and Home and End reach the ends. The cross axis duplicates the pair, which the pattern permits.",
+        "The APG asks an author to avoid controls whose operation needs the navigation arrows and, failing that, to place one such control last. The bar enforces it instead: a text entry, a select, a slider, a spin button and a contenteditable keep the keys of the flow axis, and focus leaves them on the cross axis or with Tab.",
+        "A control that announces aria-disabled keeps its place in the ring, which the pattern allows where discoverability of a function is crucial and which is what Button’s focusableWhenDisabled renders. A control carrying the native attribute is skipped, because the platform will not focus it either — including every control inside a disabled fieldset.",
+        "The bar names itself with the consumer’s aria-label or aria-labelledby, and each group names itself the same way. The pattern uses the role for three or more controls; that is documented rather than enforced, because a role that disappeared when a permission filter removed a button would be a semantic changing behind the author.",
+        "Under overflow=\"menu\" the control that holds what did not fit is a control of the bar like any other: the arrows, Home and End reach it, and it leaves the ring the moment the bar has room for everything, because a hidden control cannot hold focus. Its name carries the count rather than the mark, and focus is moved onto it before the control under focus is hidden — so a reader who was on the fifth button lands on the control that now holds it rather than on the document body.",
+        "Nothing in the bar is painted over: every control keeps its own states, its own focus ring and its own contrast. What the bar adds is the boundary between runs — a group, a rule, a spacer — and under forced colours the rule keeps its own paint, because a background flattens to Canvas and would take the boundary with it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-font-family",
+    "--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-radius",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-radius-md",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-surface-raised",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-toolbar-background",
+    "--slotted-toolbar-border-color",
+    "--slotted-toolbar-gap",
+    "--slotted-toolbar-inset",
+    "--slotted-toolbar-overflow-active-background",
+    "--slotted-toolbar-overflow-color",
+    "--slotted-toolbar-overflow-hover-background",
+    "--slotted-toolbar-overflow-hover-color",
+    "--slotted-toolbar-overflow-open-background",
+    "--slotted-toolbar-separator-color"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One bar with every axis on it, driven by the controls below the canvas. Tab into it once, then use the arrows: the whole bar is a single stop however many controls it holds.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Formatação\">\n  <button slButton variant=\"ghost\">Negrito</button>\n  <button slButton variant=\"ghost\">Itálico</button>\n  <div slToolbarSeparator></div>\n  <button slButton variant=\"ghost\">Link</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "Which way the bar runs",
+      "note": "A horizontal bar centres its controls and a vertical one stretches them, because a column at each control’s natural width is a ragged edge; the separator and the group boundary turn with it.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Ferramentas\" orientation=\"vertical\">\n  <button slButton variant=\"ghost\">Lápis</button>\n  <button slButton variant=\"ghost\">Pincel</button>\n  <div slToolbarSeparator></div>\n  <button slButton variant=\"ghost\">Borracha</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "Whether the bar paints a ground",
+      "note": "plain is the default and paints nothing: a bar inside a card header is already standing on a surface. outline frames it, and pads itself by at least the reach of a focus ring so the two never meet.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Sem moldura\" variant=\"plain\"></div>\n<div slToolbar aria-label=\"Com moldura\" variant=\"outline\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the bar sits at",
+      "note": "The size moves the bar’s own inset, gap and separator inset and never the controls inside it, which is what lets one bar hold a small icon button beside a medium select.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Compacta\" size=\"sm\">\n  <button slButton size=\"sm\" variant=\"ghost\">Recortar</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "groups",
+      "title": "Runs that belong together",
+      "note": "A group carries a name a screen reader announces and a boundary the eye reads, and a rule draws the same boundary the other way — which is what keeps a destructive action off a frequent one.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Seleção\" variant=\"outline\">\n  <div slToolbarGroup aria-label=\"Alinhamento\">\n    <button slButton variant=\"outline\">Início</button>\n    <button slButton variant=\"outline\" pressed>Centro</button>\n  </div>\n  <div slToolbarSeparator></div>\n  <div slToolbarSpacer></div>\n  <button slButton tone=\"danger\">Excluir</button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The APG table, and where focus lands",
+      "note": "Tab enters the bar once and returns to the control that last had focus; the arrows of the flow axis move and wrap, the cross axis duplicates them, and Home and End reach the ends.",
+      "language": "html",
+      "source": "<!-- Every focusable control inside the bar is an item, found in the DOM rather\n     than wrapped in a component of its own — so this library's own families,\n     and a consumer's own control, drop in unwrapped. -->\n<div slToolbar aria-label=\"Formatação\">\n  <button slButton variant=\"ghost\">Negrito</button>\n  <span slCheckbox><input slCheckboxControl type=\"checkbox\" /></span>\n  <a slLink href=\"/ajuda\">Ajuda</a>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyOwners",
+      "title": "An item that keeps the arrows",
+      "note": "A text field needs the inline arrows for its caret, so the bar leaves them to it and focus moves out on the cross axis instead — the APG’s advice for the author, written as behaviour.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Filtro\">\n  <button slButton variant=\"outline\">Todos</button>\n  <div slToolbarSpacer></div>\n  <!-- Inferred from the kind of control; data-toolbar-keys states it where the\n       kind cannot say — \"none\", \"inline\", \"block\" or \"all\". -->\n  <span slTextField><input slTextFieldControl type=\"search\" aria-label=\"Buscar\" /></span>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "disabled",
+      "title": "A bar out of action",
+      "note": "A fieldset around the bar disables every control inside it natively, and because a natively disabled control cannot be focused, the arrows skip exactly those — the platform answers it in two lines.",
+      "language": "html",
+      "source": "<fieldset [disabled]=\"readOnly()\">\n  <div slToolbar aria-label=\"Somente leitura\">\n    <button slButton variant=\"outline\">Editar</button>\n    <div slToolbarSeparator></div>\n    <button slButton tone=\"danger\">Excluir</button>\n  </div>\n</fieldset>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "overflow",
+      "title": "More controls than room",
+      "note": "wrap keeps every control visible on a second row, and the arrows wrap from row to row because the item list is linear; scroll keeps the bar to one line and scrolls past its controls rather than squeezing them.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Muitas ações\" overflow=\"wrap\"></div>\n<div slToolbar aria-label=\"Muitas ações, rolando\" overflow=\"scroll\"></div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "overflowMenu",
+      "title": "What is left over, behind one control",
+      "note": "The bar measures its own width and gives way from the end, so what holds it gives it a width that does not come from the bar’s content: a bar as wide as what it shows is the trigger alone after a fold, and never sees the room come back. What stays visible is what has nowhere to go: an item that declares no counterpart cannot be hidden, which is how the primary action survives without a priority ranking it above the others. The counterpart is an ng-template, so a menu item that is never reached builds nothing.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Documento\" overflow=\"menu\">\n  <!-- No counterpart, so it is pinned: the primary action stays visible. -->\n  <div slToolbarItem>\n    <button slButton tone=\"accent\">Publicar</button>\n  </div>\n  <div slToolbarSeparator></div>\n  <div slToolbarItem [slToolbarItemCounterpart]=\"duplicate\">\n    <button slButton variant=\"ghost\">Duplicar</button>\n  </div>\n  <div slToolbarItem [slToolbarItemCounterpart]=\"archive\">\n    <button slButton variant=\"ghost\">Arquivar</button>\n  </div>\n  <sl-toolbar-overflow />\n</div>\n\n<ng-template #duplicate><button slMenuItem>Duplicar</button></ng-template>\n<ng-template #archive><button slMenuItem>Arquivar</button></ng-template>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and standing beside other families",
+      "note": "The provider carries the five decisions an application takes once, and the bar is what belongs in a tab list’s actions slot — one tab stop for however many actions the page puts there.",
+      "language": "ts",
+      "source": "// One decision for every bar in the application, in the bootstrap file.\nbootstrapApplication(App, {\n  providers: [provideToolbarDefaults({ size: 'sm', variant: 'outline' })],\n});\n\n// And in a template, the actions slot of a tab list is where a bar goes:\n// <div slTabActions><div slToolbar aria-label=\"Ações\">…</div></div>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}