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

package/dist/docs/toggle-group.md

@@ -0,0 +1,260 @@
+<!-- index: ./index.md -->
+# toggle-group
+
+`data-ui="toggle-group"` · Set of toggles, single or multiple.
+
+## Import
+
+```tsx
+import { ToggleGroup, ToggleGroupDefaultsProvider, ToggleGroupItem } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<ToggleGroup aria-label="Período do gráfico" defaultValue={['week']}>
+  <ToggleGroupItem value="day">Dia</ToggleGroupItem>
+  <ToggleGroupItem value="week">Semana</ToggleGroupItem>
+  <ToggleGroupItem value="month">Mês</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `item` | button, or the element ToggleGroupItem’s render returns | yes |
+| `icon` | span | no |
+| `label` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | ToggleGroup | 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[]` | — | ToggleGroup | What an uncontrolled group starts from, read once. A later change to it does not silently become new state |
+| `multiple` | `boolean` | false | ToggleGroup | Whether more than one item may be on at a time. The value stays an array either way, so both bindings hold one shape and a single-select consumer writes an array of one |
+| `deselectable` | `boolean` | true | ToggleGroup | 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 | ToggleGroup | 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 | ToggleGroup | Whether the bar draws its own edge. There is no tone axis: “on” is one colour across the system, and a bar that wants the whole palette is button-group around ToggleButtons |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | ToggleGroup | How the items flow, and which pair of arrows moves focus. A vertical group writes aria-orientation |
+| `attached` | `boolean` | true | ToggleGroup | 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 | ToggleGroup | Whether the items share the whole line. Left alone the bar is as wide as its labels |
+| `loop` | `boolean` | true | ToggleGroup | Whether the arrows wrap past the ends of the set |
+| `rovingFocus` | `boolean` | inferred | ToggleGroup | Whether the group holds a tab stop of its own. Unstated it is inferred: a group inside a toolbar stands down, because a bar is already one stop with arrow navigation across every control it holds |
+| `disabled` | `boolean` | false | ToggleGroup | Unstated rather than false, so an item may state its own. Stated, it reaches every item as the native attribute, which is also what makes the browser skip it with the arrows |
+| `value, on ToggleGroupItem` | `string` | — | ToggleGroupItem | 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 |
+| `icon, on ToggleGroupItem` | `ReactNode` | — | ToggleGroupItem | The mark drawn before the words, sized from the control glyph scale and hidden from the reading order |
+| `disabled, on ToggleGroupItem` | `boolean` | — | ToggleGroupItem | One item out of action while the rest of the bar stays live. An item that is on and unavailable keeps saying both |
+| `render` | `(props: ToggleGroupRootProps \| ToggleGroupItemRootProps) => ReactNode` | — | ToggleGroup, ToggleGroupItem | Substitutes either root and hands it every attribute the family was going to write, including the ref the group needs for its own ring |
+| `ref` | `Ref<HTMLDivElement> \| Ref<HTMLButtonElement>` | — | ToggleGroup, ToggleGroupItem | Reaches the element. focus() and click() are the element’s own, so no imperative handle is invented for what the platform already ships |
+| `useToggleGroup()` | `() => ToggleGroupContextValue` | — | inside a ToggleGroup | What an item reads to know whether it is on and how to ask for a change. It throws outside a group rather than rendering a button that toggles nothing |
+| `ToggleGroupDefaultsProvider` | `{ attached, deselectable, loop, orientation, size, variant }` | — | a subtree | The six decisions an application takes once. A group that states any of them itself still wins |
+| `role` | `string` | group | ToggleGroup | A consumer’s own wins. The family writes group and never toolbar: toolbar is a keyboard model, and it is the toolbar family |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: readonly string[], request: 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. |
+| `onClick, onFocus, onBlur, on each item` | `the element’s own events` | Whenever that item’s button fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, and always runs. Calling preventDefault() in onClick stops the toggle as well. |
+
+## 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.
+- Inside a toolbar the group gives its keyboard up: a bar is already one tab stop with arrow navigation across every control it holds. The bar is found in the DOM by its public identifier rather than through an imported context, so neither family 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: 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
+
+```tsx
+<ToggleGroup aria-label="Estilo do texto" defaultValue={['bold', 'italic']} multiple>
+  <ToggleGroupItem value="bold">Negrito</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Itálico</ToggleGroupItem>
+</ToggleGroup>;
+
+<ToggleGroup aria-label="Período" defaultValue={['week']} deselectable={false}>
+  <ToggleGroupItem value="week">Semana</ToggleGroupItem>
+  <ToggleGroupItem value="month">Mês</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Densidade" defaultValue={['compact']} variant="ghost">
+  <ToggleGroupItem value="comfortable">Confortável</ToggleGroupItem>
+  <ToggleGroupItem value="compact">Compacta</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Ordenação" defaultValue={['newest']} size="sm">
+  <ToggleGroupItem value="newest">Mais recentes</ToggleGroupItem>
+  <ToggleGroupItem value="oldest">Mais antigos</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Alinhamento" defaultValue={['center']} orientation="vertical">
+  <ToggleGroupItem value="start">Início</ToggleGroupItem>
+  <ToggleGroupItem value="center">Centro</ToggleGroupItem>
+  <ToggleGroupItem value="end">Fim</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Camadas" attached={false} defaultValue={['roads']} multiple>
+  <ToggleGroupItem value="roads">Ruas</ToggleGroupItem>
+  <ToggleGroupItem value="terrain">Relevo</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Formato" defaultValue={['pdf']}>
+  <ToggleGroupItem value="csv">CSV</ToggleGroupItem>
+  <ToggleGroupItem disabled value="xlsx">
+    XLSX
+  </ToggleGroupItem>
+  <ToggleGroupItem disabled value="pdf">
+    PDF
+  </ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Estilo do texto" defaultValue={['bold']} multiple>
+  <ToggleGroupItem aria-label="Negrito" icon={<BoldIcon />} value="bold" />
+  <ToggleGroupItem aria-label="Itálico" icon={<ItalicIcon />} value="italic" />
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Cobrança" defaultValue={['monthly']} fullWidth>
+  <ToggleGroupItem value="monthly">Mensal</ToggleGroupItem>
+  <ToggleGroupItem value="yearly">Anual</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### 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
+
+```tsx
+<Toolbar aria-label="Formatação">
+  <ToggleGroup aria-label="Estilo do texto" defaultValue={['bold']} multiple variant="ghost">
+    <ToggleGroupItem aria-label="Negrito" icon={<BoldIcon />} value="bold" />
+    <ToggleGroupItem aria-label="Itálico" icon={<ItalicIcon />} value="italic" />
+  </ToggleGroup>
+  <ToolbarSeparator />
+  <Button size="sm" tone="secondary" variant="ghost">
+    Publicar
+  </Button>
+</Toolbar>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Frequência" defaultValue={['now']} fullWidth>
+  <ToggleGroupItem value="now">Imediatamente</ToggleGroupItem>
+  <ToggleGroupItem value="digest">Uma vez por dia, no resumo da noite</ToggleGroupItem>
+</ToggleGroup>;
+```
+
+### Substituting an element, and setting the defaults once
+
+render hands either root every attribute it was going to write, so a bar can be a real ul with each item an li; the provider states the axes once for a whole application.
+
+Excerpt — not a complete module
+
+```tsx
+<ToggleGroupDefaultsProvider size="sm" variant="ghost">
+  <ToggleGroup aria-label="Camadas" render={(props) => <nav {...props} />}>
+    <ToggleGroupItem value="roads">Ruas</ToggleGroupItem>
+  </ToggleGroup>
+</ToggleGroupDefaultsProvider>;
+```
+
+### 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
+
+```tsx
+<ToggleGroup aria-label="Período" defaultValue={['week']} loop={false}>
+  <ToggleGroupItem value="day">Dia</ToggleGroupItem>
+  <ToggleGroupItem value="week">Semana</ToggleGroupItem>
+</ToggleGroup>;
+```

package/dist/docs/toggle.json

@@ -0,0 +1,331 @@
+{
+  "family": "toggle",
+  "ui": "toggle",
+  "binding": "react",
+  "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 { Toggle, ToggleDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "button, or the element render returns",
+          "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": "span",
+          "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",
+          "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": "Toggle",
+          "description": "Present means the consumer owns the state, for the life of the component. Absent, the toggle owns it and starts from defaultPressed"
+        },
+        {
+          "name": "defaultPressed",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Toggle",
+          "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": "Toggle",
+          "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": "Toggle",
+          "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": "icon",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Toggle",
+          "description": "The mark drawn before the words, sized from the control glyph scale and hidden from the reading order. Alone, it makes the toggle square"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Toggle",
+          "description": "The words, which never change with the state. Absent, the toggle needs an aria-label"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Toggle",
+          "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": "Toggle",
+          "description": "The native type. 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": "render",
+          "type": "(props: ToggleRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Toggle",
+          "description": "Substitutes the root and hands it every attribute the family was going to write. It stays a button"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLButtonElement>",
+          "defaultValue": "—",
+          "appliesTo": "Toggle",
+          "description": "Reaches the element. focus() and click() are the element’s own, so no imperative handle is invented for what the platform already ships"
+        },
+        {
+          "name": "ToggleDefaultsProvider",
+          "type": "{ size, variant }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The two decisions an application takes once. A toggle that states either itself still wins"
+        },
+        {
+          "name": "name, value, form, aria-*",
+          "type": "the button’s own attributes",
+          "defaultValue": "—",
+          "appliesTo": "Toggle",
+          "description": "Every native attribute reaches the button unchanged and means what a button’s does"
+        }
+      ],
+      "events": [
+        {
+          "name": "onPressedChange",
+          "payload": "(pressed: boolean, request: 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": "onClick, onFocus, onBlur",
+          "payload": "the element’s own events",
+          "when": "Whenever the button fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, and always runs. Calling preventDefault() in onClick 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 a toolbar 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: 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": "tsx",
+      "source": "<Toggle icon={<WrapText size={16} />} defaultPressed>\n  Quebrar linhas\n</Toggle>;\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": "tsx",
+      "source": "const [wrap, setWrap] = useState(false);\n\n<Toggle icon={<WrapText size={16} />} onPressedChange={setWrap} pressed={wrap}>\n  Quebrar linhas\n</Toggle>;\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": "tsx",
+      "source": "<Toggle icon={<Pin size={16} />} variant=\"ghost\">\n  Fixar cabeçalho\n</Toggle>;\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": "tsx",
+      "source": "<Toggle icon={<WrapText size={14} />} size=\"sm\">\n  Quebrar\n</Toggle>;\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": "tsx",
+      "source": "<Toggle aria-label=\"Negrito\" icon={<Bold size={16} />} defaultPressed />;\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": "tsx",
+      "source": "<Toggle icon={<Pin size={16} />} defaultPressed disabled>\n  Fixar cabeçalho\n</Toggle>;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Editor\">\n  <Toggle aria-label=\"Negrito\" icon={<Bold size={16} />} variant=\"ghost\" />\n  <Toggle aria-label=\"Itálico\" icon={<Italic size={16} />} variant=\"ghost\" />\n  <ToolbarSeparator />\n  <Toggle icon={<WrapText size={16} />} variant=\"ghost\">\n    Quebrar\n  </Toggle>\n</Toolbar>;\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": "tsx",
+      "source": "<Toggle icon={<WrapText size={16} />}>Zeilenumbruch aktivieren</Toggle>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Defaults once, and the consumer’s own element",
+      "note": "The provider sets size and variant for every toggle under it; a toggle that states either itself still wins. render hands the wiring to the consumer’s own button — it stays a button, because aria-pressed on a link is a link announcing a state a link does not hold.",
+      "language": "tsx",
+      "source": "<ToggleDefaultsProvider size=\"sm\" variant=\"ghost\">\n  <Toggle icon={<Pin size={14} />} render={(props) => <button {...props} data-track=\"pin\" />}>\n    Fixar\n  </Toggle>\n</ToggleDefaultsProvider>;\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 page below shows which one it saw.",
+      "language": "tsx",
+      "source": "<Toggle icon={<WrapText size={16} />} onPressedChange={(pressed, request) => log(request.reason)}>\n  Quebrar linhas\n</Toggle>;\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": "tsx",
+      "source": "<>\n  <Toggle icon={<WrapText size={16} />}>Quebrar linhas</Toggle>\n  <ToggleButton loading={following} onPressedChange={follow} pressed={followed}>\n    Seguir\n  </ToggleButton>\n</>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}