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

package/dist/docs/toggle.md

@@ -0,0 +1,201 @@
+<!-- index: ./index.md -->
+# toggle
+
+`data-ui="toggle"` · Button that stays pressed or unpressed.
+
+## Import
+
+```tsx
+import { Toggle, ToggleDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Toggle icon={<WrapText size={16} />} defaultPressed>
+  Quebrar linhas
+</Toggle>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | button, or the element render returns | yes |
+| `icon` | span | no |
+| `label` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `pressed` | `boolean` | — | Toggle | Present means the consumer owns the state, for the life of the component. Absent, the toggle owns it and starts from defaultPressed |
+| `defaultPressed` | `boolean` | false | Toggle | What an uncontrolled toggle starts from, read once. A later change to it does not silently become new state |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Toggle | The control step. It reads the control scale, so the toggle is as tall as the field beside it |
+| `variant` | `'outline' \| 'ghost'` | outline | Toggle | 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 |
+| `icon` | `ReactNode` | — | Toggle | The mark drawn before the words, sized from the control glyph scale and hidden from the reading order. Alone, it makes the toggle square |
+| `children` | `ReactNode` | — | Toggle | The words, which never change with the state. Absent, the toggle needs an aria-label |
+| `disabled` | `boolean` | false | Toggle | 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 | Toggle | 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 |
+| `render` | `(props: ToggleRootProps) => ReactNode` | — | Toggle | Substitutes the root and hands it every attribute the family was going to write. It stays a button |
+| `ref` | `Ref<HTMLButtonElement>` | — | Toggle | Reaches the element. focus() and click() are the element’s own, so no imperative handle is invented for what the platform already ships |
+| `ToggleDefaultsProvider` | `{ size, variant }` | — | a subtree | The two decisions an application takes once. A toggle that states either itself still wins |
+| `name, value, form, aria-*` | `the button’s own attributes` | — | Toggle | Every native attribute reaches the button unchanged and means what a button’s does |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onPressedChange` | `(pressed: boolean, request: 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. |
+| `onClick, onFocus, onBlur` | `the element’s own events` | 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. |
+
+## 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 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
+
+### 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
+
+```tsx
+const [wrap, setWrap] = useState(false);
+
+<Toggle icon={<WrapText size={16} />} onPressedChange={setWrap} pressed={wrap}>
+  Quebrar linhas
+</Toggle>;
+```
+
+### 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
+
+```tsx
+<Toggle icon={<Pin size={16} />} variant="ghost">
+  Fixar cabeçalho
+</Toggle>;
+```
+
+### 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
+
+```tsx
+<Toggle icon={<WrapText size={14} />} size="sm">
+  Quebrar
+</Toggle>;
+```
+
+### 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
+
+```tsx
+<Toggle aria-label="Negrito" icon={<Bold size={16} />} defaultPressed />;
+```
+
+### 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
+
+```tsx
+<Toggle icon={<Pin size={16} />} defaultPressed disabled>
+  Fixar cabeçalho
+</Toggle>;
+```
+
+### 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
+
+```tsx
+<Toolbar aria-label="Editor">
+  <Toggle aria-label="Negrito" icon={<Bold size={16} />} variant="ghost" />
+  <Toggle aria-label="Itálico" icon={<Italic size={16} />} variant="ghost" />
+  <ToolbarSeparator />
+  <Toggle icon={<WrapText size={16} />} variant="ghost">
+    Quebrar
+  </Toggle>
+</Toolbar>;
+```
+
+### 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
+
+```tsx
+<Toggle icon={<WrapText size={16} />}>Zeilenumbruch aktivieren</Toggle>;
+```
+
+### Defaults once, and the consumer’s own element
+
+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.
+
+Excerpt — not a complete module
+
+```tsx
+<ToggleDefaultsProvider size="sm" variant="ghost">
+  <Toggle icon={<Pin size={14} />} render={(props) => <button {...props} data-track="pin" />}>
+    Fixar
+  </Toggle>
+</ToggleDefaultsProvider>;
+```
+
+### 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 page below shows which one it saw.
+
+Excerpt — not a complete module
+
+```tsx
+<Toggle icon={<WrapText size={16} />} onPressedChange={(pressed, request) => log(request.reason)}>
+  Quebrar linhas
+</Toggle>;
+```
+
+### 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
+
+```tsx
+<>
+  <Toggle icon={<WrapText size={16} />}>Quebrar linhas</Toggle>
+  <ToggleButton loading={following} onPressedChange={follow} pressed={followed}>
+    Seguir
+  </ToggleButton>
+</>;
+```

package/dist/docs/toolbar.json

@@ -0,0 +1,385 @@
+{
+  "family": "toolbar",
+  "ui": "toolbar",
+  "binding": "react",
+  "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 { Toolbar, ToolbarDefaultsProvider, ToolbarGroup, ToolbarItem, ToolbarOverflow, ToolbarSeparator, ToolbarSpacer } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div[role=\"toolbar\"], or the element render returns",
+          "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",
+          "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. A ButtonGroup inside one of these is one unit and four items."
+        },
+        {
+          "part": "overflow",
+          "element": "button, from 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. On a coarse pointer it is the comfortable target wide as well as tall."
+        }
+      ],
+      "api": [
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "Toolbar, ToolbarDefaultsProvider",
+          "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": "Toolbar, ToolbarDefaultsProvider",
+          "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": "Toolbar, ToolbarDefaultsProvider",
+          "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": "Toolbar, ToolbarDefaultsProvider",
+          "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 ToolbarOverflow in it has nothing to give way to, so it scrolls"
+        },
+        {
+          "name": "onOverflowChange",
+          "type": "(hidden: number) => void",
+          "defaultValue": "—",
+          "appliesTo": "Toolbar",
+          "description": "How many units gave way, once per change. There is no controlled pair 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": "counterpart",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "ToolbarItem, ToolbarGroup",
+          "description": "What the unit becomes in the surface when the bar has no room for it. A unit that declares none is pinned — pinning is the absence of a counterpart rather than a second prop, 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": "ToolbarOverflow",
+          "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"
+        },
+        {
+          "name": "align, side, size",
+          "type": "MenuAlign | MenuSide | MenuSize",
+          "defaultValue": "from the Menu defaults",
+          "appliesTo": "ToolbarOverflow",
+          "description": "Where the surface sits against the trigger, and its own measure. Everything else about the layer an application sets once with MenuDefaultsProvider: a second configuration surface over the same layer would be two answers to one question"
+        },
+        {
+          "name": "loop",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Toolbar, ToolbarDefaultsProvider",
+          "description": "Whether the arrows wrap past the ends of the bar"
+        },
+        {
+          "name": "aria-label",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Toolbar, ToolbarGroup",
+          "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": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Toolbar, ToolbarGroup, ToolbarItem, ToolbarOverflow, ToolbarSeparator, ToolbarSpacer",
+          "description": "Substitutes any of the six roots and hands it every attribute — a bar can be a nav, a rule an hr, and the overflow trigger the consumer’s own IconButton with the Menu wiring on it"
+        },
+        {
+          "name": "menuRef",
+          "type": "Ref<MenuHandle>",
+          "defaultValue": "—",
+          "appliesTo": "ToolbarOverflow",
+          "description": "Reaches the surface’s imperative actions — open, close and focus — which belong to the Menu family rather than to this one"
+        },
+        {
+          "name": "useToolbarOverflow",
+          "type": "() => { collapsed, counterpart }",
+          "defaultValue": "—",
+          "appliesTo": "inside Toolbar",
+          "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 value"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "Toolbar and every part",
+          "description": "Reaches the element itself. No imperative handle is invented: focus() on the control a page wants to start from is the platform’s own"
+        },
+        {
+          "name": "items",
+          "type": "any focusable descendant",
+          "defaultValue": "—",
+          "appliesTo": "inside Toolbar",
+          "description": "Anything focusable is an item, found in the DOM: this library’s button, link, checkbox, switch and text-field, a menu trigger, or a consumer’s own control. An element that cannot hold focus is not reachable by the arrows"
+        },
+        {
+          "name": "ToolbarDefaultsProvider",
+          "type": "{ orientation, size, variant, overflow, loop }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The five decisions an application takes once. A bar that states any of them itself still wins"
+        },
+        {
+          "name": "fieldset",
+          "type": "the platform’s own element",
+          "defaultValue": "—",
+          "appliesTo": "around a Toolbar",
+          "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": "tsx",
+      "source": "<Toolbar aria-label=\"Formatação\">\n  <Button variant=\"ghost\">Negrito</Button>\n  <Button variant=\"ghost\">Itálico</Button>\n  <ToolbarSeparator />\n  <Button variant=\"ghost\">Link</Button>\n</Toolbar>;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Ferramentas\" orientation=\"vertical\">\n  <Button variant=\"ghost\">Lápis</Button>\n  <Button variant=\"ghost\">Pincel</Button>\n  <ToolbarSeparator />\n  <Button variant=\"ghost\">Borracha</Button>\n</Toolbar>;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Sem moldura\" variant=\"plain\" />;\n<Toolbar aria-label=\"Com moldura\" variant=\"outline\" />;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Compacta\" size=\"sm\">\n  <Button size=\"sm\" variant=\"ghost\">\n    Recortar\n  </Button>\n</Toolbar>;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Seleção\" variant=\"outline\">\n  <ToolbarGroup aria-label=\"Alinhamento\">\n    <Button variant=\"outline\">Início</Button>\n    <Button pressed variant=\"outline\">\n      Centro\n    </Button>\n  </ToolbarGroup>\n  <ToolbarSeparator />\n  <ToolbarSpacer />\n  <Button tone=\"danger\">Excluir</Button>\n</Toolbar>;\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": "tsx",
+      "source": "// Every focusable control inside the bar is an item, found in the DOM\n// rather than wrapped in a component of its own — so this library's own\n// families, and a consumer's own control, drop in unwrapped.\n<Toolbar aria-label=\"Formatação\">\n  <Button variant=\"ghost\">Negrito</Button>\n  <Checkbox>Grade</Checkbox>\n  <Link href=\"/ajuda\">Ajuda</Link>\n</Toolbar>;\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": "tsx",
+      "source": "<Toolbar aria-label=\"Filtro\">\n  <Button variant=\"outline\">Todos</Button>\n  <ToolbarSpacer />\n  {/* Inferred from the kind of control; data-toolbar-keys states it where\n      the kind cannot say — \"none\", \"inline\", \"block\" or \"all\". */}\n  <TextField aria-label=\"Buscar\" type=\"search\" />\n</Toolbar>;\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": "tsx",
+      "source": "<fieldset disabled={readOnly}>\n  <Toolbar aria-label=\"Somente leitura\">\n    <Button variant=\"outline\">Editar</Button>\n    <ToolbarSeparator />\n    <Button tone=\"danger\">Excluir</Button>\n  </Toolbar>\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": "tsx",
+      "source": "<Toolbar aria-label=\"Muitas ações\" overflow=\"wrap\" />;\n<Toolbar aria-label=\"Muitas ações, rolando\" overflow=\"scroll\" />;\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.",
+      "language": "tsx",
+      "source": "<Toolbar aria-label=\"Documento\" overflow=\"menu\">\n  {/* No counterpart, so it is pinned: the primary action stays visible. */}\n  <ToolbarItem>\n    <Button tone=\"accent\">Publicar</Button>\n  </ToolbarItem>\n  <ToolbarSeparator />\n  <ToolbarItem counterpart={<MenuItem>Duplicar</MenuItem>}>\n    <Button variant=\"ghost\">Duplicar</Button>\n  </ToolbarItem>\n  <ToolbarItem counterpart={<MenuItem>Arquivar</MenuItem>}>\n    <Button variant=\"ghost\">Arquivar</Button>\n  </ToolbarItem>\n  <ToolbarOverflow />\n</Toolbar>;\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": "tsx",
+      "source": "<ToolbarDefaultsProvider size=\"sm\" variant=\"outline\">\n  <Tabs defaultValue=\"resumo\">\n    <TabList aria-label=\"Pedido\">\n      <Tab value=\"resumo\">Resumo</Tab>\n    </TabList>\n    <TabActions>\n      <Toolbar aria-label=\"Ações do pedido\">\n        <Button variant=\"ghost\">Exportar</Button>\n      </Toolbar>\n    </TabActions>\n  </Tabs>\n</ToolbarDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}