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

package/docs/toggle-group.md

@@ -0,0 +1,255 @@
+<!-- index: ./index.md -->
+# toggle-group
+
+`data-ui="toggle-group"` · Set of toggles, single or multiple.
+
+## Import
+
+```ts
+import {
+  provideToggleGroupDefaults,
+  SlToggleGroup,
+  SlToggleGroupIcon,
+  SlToggleGroupItem,
+} from '@slotted/angular/toggle-group';
+```
+
+Selector: `[slToggleGroup]` · exportAs: `slToggleGroup`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Período do gráfico" [defaultValue]="['week']">
+  <button slToggleGroupItem value="day">Dia</button>
+  <button slToggleGroupItem value="week">Semana</button>
+  <button slToggleGroupItem value="month">Mês</button>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element, with slToggleGroup on it | yes |
+| `item` | button, with slToggleGroupItem on it | yes |
+| `icon` | the consumer’s own element, with slToggleGroupIcon on it | no |
+| `label` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | slToggleGroup | Present means the consumer owns the set, for the life of the component. Absent, the group owns it and starts from defaultValue |
+| `defaultValue` | `readonly string[]` | — | slToggleGroup | What an uncontrolled group starts from, read once in ngOnInit. A later change to it does not silently become new state |
+| `multiple` | `boolean` | false | slToggleGroup | Whether more than one item may be on at a time. The value stays an array either way, so one signal holds it in every mode |
+| `deselectable` | `boolean` | true | slToggleGroup | Whether the last item on may be turned off. Ignored while multiple is true, where a set may always empty |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slToggleGroup | The control step the bar and every item sit at. It reads the control scale, so the bar is as tall as the field beside it |
+| `variant` | `'outline' \| 'ghost'` | outline | slToggleGroup | Whether the bar draws its own edge. There is no tone axis: “on” is one colour across the system |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slToggleGroup | How the items flow, and which pair of arrows moves focus. A vertical group writes aria-orientation |
+| `attached` | `boolean` | true | slToggleGroup | Whether the items are joined into one bar or spaced apart. A joined bar overlaps its items by one border so a shared column holds one line |
+| `fullWidth` | `boolean` | false | slToggleGroup | Whether the items share the whole line. Left alone the bar is as wide as its labels |
+| `loop` | `boolean` | true | slToggleGroup | Whether the arrows wrap past the ends of the set |
+| `rovingFocus` | `boolean` | inferred | slToggleGroup | Whether the group holds a tab stop of its own. Unstated it is inferred after the first render: a group inside a toolbar stands down |
+| `disabled` | `boolean` | false | slToggleGroup | Unstated rather than false, so an item may state its own. Stated, it reaches every item as the native attribute |
+| `value, on slToggleGroupItem` | `string` | — | slToggleGroupItem | What this item turns on, and what the group’s value holds. It is required: an item with no value is a control that changes nothing |
+| `disabled, on slToggleGroupItem` | `boolean` | — | slToggleGroupItem | One item out of action while the rest of the bar stays live. An item that is on and unavailable keeps saying both |
+| `slToggleGroupItem` | `directive on a button` | — | the consumer’s element | The item is a directive, so the button is the consumer’s own: every attribute, every listener and every structural directive around it stay exactly as they were written |
+| `slToggleGroupIcon` | `directive on any element` | — | inside an item | The mark, projected into the item and hidden from the reading order. An ng-icon, an inline svg or a span all work and none of them loses its own semantics |
+| `exportAs` | `'slToggleGroup' \| 'slToggleGroupItem'` | — | a template reference | Reaches the instance, so a template can read selection(), resolvedSize() or an item’s pressed() without the component owning a second copy of the state |
+| `provideToggleGroupDefaults()` | `(defaults: Partial<ToggleGroupDefaults>) => Provider` | — | an injector | The six decisions an application takes once, at the root or on one route. A group that states any of them itself still wins |
+| `role` | `string` | group | slToggleGroup | Read from the host with HostAttributeToken before the host bindings write, so a consumer’s own survives. The family writes group and never toolbar: toolbar is a keyboard model, and it is the toolbar family |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<readonly string[]>` | Before the value moves. The request carries the new array, the array 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 group already holds. |
+| `click, focus, blur, on each item` | `the element’s own events` | Whenever that item’s button fires them. The item is a directive on the consumer’s own element, so every listener the consumer bound is on the element itself and runs exactly as it was written. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `ghost` | `outline` |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+
+## Rules
+
+- There is no APG pattern called “toggle group”. The container is a group, each item is the Button pattern’s toggle button (w3.org/WAI/ARIA/apg/patterns/button/), and the movement between them is the Toolbar pattern’s roving tabindex (w3.org/WAI/ARIA/apg/patterns/toolbar/). Citing one and implying the other is how a family ends up with half a keyboard.
+- So the arrows move focus and never toggle, which is the one place this family and segmented-control genuinely differ and the one a reader feels. Space and Enter turn the focused item on or off; Home and End reach the ends; a horizontal group ignores the cross axis so the page keeps scrolling with focus inside it.
+- aria-pressed is written in both states, so an item 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 Button pattern calls critical. An item with only a mark takes its name from an aria-label the consumer writes on the button.
+- Inside a toolbar the group gives its keyboard up: the bar is found in the DOM by its public identifier rather than by injecting the other family, so neither depends on the other. rovingFocus states it outright for a bar this library did not write.
+- disabled is the native attribute, because that is also what makes the browser refuse focus and what makes the ring skip the item. The group is not a form control and implements no ControlValueAccessor: a set of choices a form submits is checkbox-group for many and segmented-control for one.
+- The target is the item 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-group-active-background`, `--slotted-toggle-group-border-color`, `--slotted-toggle-group-color`, `--slotted-toggle-group-disabled-border-color`, `--slotted-toggle-group-disabled-color`, `--slotted-toggle-group-disabled-pressed-background`, `--slotted-toggle-group-hover-background`, `--slotted-toggle-group-pressed-background`, `--slotted-toggle-group-pressed-border-color`, `--slotted-toggle-group-pressed-color`, `--slotted-toggle-group-pressed-hover-background`, `--slotted-toggle-group-radius`, `--slotted-toggle-group-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
+
+### One at a time, several at once, or none
+
+The value is an array in both modes: multiple caps it at every item rather than at one. Press the item that is already on — the set empties, unless deselectable says it may not.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Estilo do texto" multiple [defaultValue]="['bold']">
+  <button slToggleGroupItem value="bold">Negrito</button>
+  <button slToggleGroupItem value="italic">Itálico</button>
+</div>
+```
+
+### Framed, or bare
+
+outline draws the bar’s own edge; ghost draws none, for a bar that sits inside something already framed — a toolbar, a card header. The colour of an item that is on is the same in both.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Densidade" variant="ghost" [defaultValue]="['compact']">
+  <button slToggleGroupItem value="comfortable">Confortável</button>
+  <button slToggleGroupItem value="compact">Compacta</button>
+</div>
+```
+
+### The three control steps
+
+Each step reads the control scale, so a bar is exactly as tall as the text field and the button beside it at every size and at every density.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Ordenação" size="sm" [defaultValue]="['newest']">
+  <button slToggleGroupItem value="newest">Mais recentes</button>
+  <button slToggleGroupItem value="oldest">Mais antigos</button>
+</div>
+```
+
+### Along the line, or down the page
+
+A vertical bar moves with ArrowUp and ArrowDown and writes aria-orientation; a horizontal one leaves the cross axis to the page, so scrolling still works with focus inside the group.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Alinhamento" orientation="vertical" [defaultValue]="['center']">
+  <button slToggleGroupItem value="start">Início</button>
+  <button slToggleGroupItem value="center">Centro</button>
+</div>
+```
+
+### Joined, or spaced apart
+
+A joined bar overlaps its items by one border so the shared column holds one line rather than two — which is what keeps the edge even at 110%, 150% and 175% zoom.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Camadas" multiple [attached]="false" [defaultValue]="['roads']">
+  <button slToggleGroupItem value="roads">Ruas</button>
+  <button slToggleGroupItem value="terrain">Relevo</button>
+</div>
+```
+
+### Every state the contract declares
+
+Hover, focus, press, on, unavailable, and unavailable while on — that last one keeps both facts, because the state a reader cannot change is still one they have to be able to read.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Formato" [defaultValue]="['csv']">
+  <button slToggleGroupItem value="csv">CSV</button>
+  <button slToggleGroupItem value="xlsx" disabled>XLSX</button>
+</div>
+```
+
+### Marks without words
+
+An item with only a mark draws square and takes its accessible name from aria-label, which is the one thing the family cannot supply for a consumer’s own artwork.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Estilo do texto" multiple [defaultValue]="['bold']">
+  <button slToggleGroupItem value="bold" aria-label="Negrito">
+    <ng-icon slToggleGroupIcon name="lucideBold" />
+  </button>
+</div>
+```
+
+### Content width, or the whole line
+
+Left alone the bar is as wide as its labels; fullWidth makes the items share the line. Either way an item gives way rather than pushing the layout, and its label clips at the ellipsis.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Cobrança" fullWidth [defaultValue]="['monthly']">
+  <button slToggleGroupItem value="monthly">Mensal</button>
+  <button slToggleGroupItem value="yearly">Anual</button>
+</div>
+```
+
+### Inside a toolbar, the bar owns the keyboard
+
+A toolbar is already one tab stop with arrow navigation across every control it holds, so the group stands down rather than putting a second stop inside the first. Nothing has to be passed.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Formatação">
+  <div
+    slToggleGroup
+    aria-label="Estilo do texto"
+    multiple
+    variant="ghost"
+    [defaultValue]="['bold']"
+  >
+    <button slToggleGroupItem value="bold" aria-label="Negrito">
+      <ng-icon slToggleGroupIcon name="lucideBold" />
+    </button>
+  </div>
+</div>
+```
+
+### Content the family did not choose
+
+A label nine words long, one unbroken token, and a right-to-left string inside a left-to-right page. Each clips at the ellipsis and keeps its whole text in the DOM.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Frequência" fullWidth [defaultValue]="['now']">
+  <button slToggleGroupItem value="now">Imediatamente</button>
+  <button slToggleGroupItem value="digest">Uma vez por dia, no resumo da noite</button>
+</div>
+```
+
+### The directive on the consumer’s own element, and the defaults once
+
+Every part is a directive, so the element is always the consumer’s; provideToggleGroupDefaults states the axes once for a whole application or one route.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideToggleGroupDefaults({ size: 'sm', variant: 'ghost' })];
+```
+
+### The keyboard, key by key
+
+Tab reaches the group once; the arrows move focus and never toggle; Home and End reach the ends; Space and Enter turn the focused item on and off. An item is a button, and that is why.
+
+Excerpt — not a complete module
+
+```html
+<div slToggleGroup aria-label="Período" [loop]="false" [defaultValue]="['week']">
+  <button slToggleGroupItem value="day">Dia</button>
+  <button slToggleGroupItem value="week">Semana</button>
+</div>
+```

package/docs/toggle.json

@@ -0,0 +1,326 @@
+{
+  "family": "toggle",
+  "ui": "toggle",
+  "binding": "angular",
+  "catalog": {
+    "group": "Actions",
+    "summary": "Button that stays pressed or unpressed."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "ghost"
+    ]
+  },
+  "members": {
+    "toggle": {
+      "nativeElement": "button",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "type": "button",
+        "disabled": false,
+        "defaultPressed": false
+      },
+      "capabilities": [
+        "pressed",
+        "size",
+        "appearance",
+        "content",
+        "disabled",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "pressed",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "icon",
+        "label"
+      ]
+    }
+  },
+  "docs": {
+    "toggle": {
+      "imports": {
+        "source": "import { provideToggleDefaults, SlToggle, SlToggleIcon } from '@slotted/angular/toggle';",
+        "selector": "button[slToggle]",
+        "exportAs": "slToggle"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the consumer’s own button, with slToggle on it",
+          "required": true,
+          "purpose": "The control. It carries data-ui=\"toggle\", aria-pressed in both states, data-pressed while it is on, and the two axes. Its border is always present, so turning it on changes a colour and never the geometry."
+        },
+        {
+          "part": "icon",
+          "element": "the consumer’s own element, with slToggleIcon on it",
+          "required": false,
+          "purpose": "The mark, sized from the control glyph scale and hidden from the reading order. A toggle with a mark and no words draws square and takes its accessible name from the aria-label the consumer writes."
+        },
+        {
+          "part": "label",
+          "element": "span, always rendered; empty when the button projects no words",
+          "required": false,
+          "purpose": "The words. A box of their own, so a label a narrow container made too long clips at the ellipsis instead of wrapping — and the string stays whole in the DOM."
+        }
+      ],
+      "api": [
+        {
+          "name": "pressed",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slToggle",
+          "description": "Bound, the consumer owns the state for the life of the component. Unbound, the toggle owns it and starts from defaultPressed"
+        },
+        {
+          "name": "defaultPressed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slToggle",
+          "description": "What an uncontrolled toggle starts from, read once. A later change to it does not silently become new state"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slToggle",
+          "description": "The control step. It reads the control scale, so the toggle is as tall as the field beside it"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'ghost'",
+          "defaultValue": "outline",
+          "appliesTo": "slToggle",
+          "description": "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"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slToggle",
+          "description": "The native attribute, which is also what makes the browser refuse focus. A toggle that is on and unavailable keeps saying both"
+        },
+        {
+          "name": "type",
+          "type": "'button' | 'submit' | 'reset'",
+          "defaultValue": "button",
+          "appliesTo": "slToggle",
+          "description": "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"
+        }
+      ],
+      "composition": [
+        {
+          "name": "slToggle",
+          "type": "directive on a button",
+          "defaultValue": "—",
+          "appliesTo": "the consumer’s element",
+          "description": "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"
+        },
+        {
+          "name": "slToggleIcon",
+          "type": "directive on any element",
+          "defaultValue": "—",
+          "appliesTo": "inside the button",
+          "description": "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"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slToggle'",
+          "defaultValue": "—",
+          "appliesTo": "a template reference",
+          "description": "Reaches the instance, so a template can read isPressed(), resolvedSize() or resolvedVariant() without the component owning a second copy of the state"
+        },
+        {
+          "name": "provideToggleDefaults()",
+          "type": "(defaults: Partial<ToggleDefaults>) => Provider",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The two decisions an application takes once, at the root or on one route. A toggle that states either itself still wins"
+        },
+        {
+          "name": "type",
+          "type": "string",
+          "defaultValue": "button",
+          "appliesTo": "slToggle",
+          "description": "Read from the host with HostAttributeToken before the host binding writes, so a consumer’s own submit survives"
+        }
+      ],
+      "events": [
+        {
+          "name": "pressedChange",
+          "payload": "ChangeRequest<boolean>",
+          "when": "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."
+        },
+        {
+          "name": "(click), (focus), (blur)",
+          "payload": "the element’s own events",
+          "when": "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."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One toggle with every axis on it, driven by the controls below the canvas. Press it: the label stays “Quebrar linhas” and the state is what changes, which is what a screen reader announces beside it.",
+      "language": "html",
+      "source": "<button slToggle defaultPressed>\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Quebrar linhas\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "pressed",
+      "title": "Owned by the consumer, or by the toggle",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle [pressed]=\"wrap()\" (pressedChange)=\"wrap.set($event.value)\">\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Quebrar linhas\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variant",
+      "title": "Framed, or bare until it is on",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle variant=\"ghost\">\n  <ng-icon slToggleIcon name=\"lucidePin\" />\n  Fixar cabeçalho\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three steps, one control tall",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle size=\"sm\">\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Quebrar\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "iconOnly",
+      "title": "A mark and no words",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle aria-label=\"Negrito\" defaultPressed>\n  <ng-icon slToggleIcon name=\"lucideBold\" />\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the contract declares",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle defaultPressed disabled>\n  <ng-icon slToggleIcon name=\"lucidePin\" />\n  Fixar cabeçalho\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "toolbar",
+      "title": "Inside a toolbar",
+      "note": "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.",
+      "language": "html",
+      "source": "<div slToolbar aria-label=\"Editor\">\n  <button slToggle variant=\"ghost\" aria-label=\"Negrito\">\n    <ng-icon slToggleIcon name=\"lucideBold\" />\n  </button>\n  <button slToggle variant=\"ghost\" aria-label=\"Itálico\">\n    <ng-icon slToggleIcon name=\"lucideItalic\" />\n  </button>\n  <hr slToolbarSeparator />\n  <button slToggle variant=\"ghost\">\n    <ng-icon slToggleIcon name=\"lucideWrapText\" />\n    Quebrar\n  </button>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle>\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Zeilenumbruch aktivieren\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Defaults once, and the consumer’s own element",
+      "note": "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.",
+      "language": "html",
+      "source": "<!-- providers: [provideToggleDefaults({ size: 'sm', variant: 'ghost' })] -->\n<button slToggle #pin=\"slToggle\" data-track=\"pin\" (click)=\"track(pin.isPressed())\">\n  <ng-icon slToggleIcon name=\"lucidePin\" />\n  Fixar\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard, key by key",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle (pressedChange)=\"log($event.reason)\">\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Quebrar linhas\n</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "versus",
+      "title": "Toggle, or ToggleButton",
+      "note": "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.",
+      "language": "html",
+      "source": "<button slToggle>\n  <ng-icon slToggleIcon name=\"lucideWrapText\" />\n  Quebrar linhas\n</button>\n<button\n  slToggleButton\n  [loading]=\"following()\"\n  [pressed]=\"followed()\"\n  (pressedChange)=\"follow($event)\"\n>\n  Seguir\n</button>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}