ionbase-ui 0.84.0 → 0.88.0

package/dist/meta/SearchField.json

@@ -0,0 +1,487 @@
+{
+  "name": "SearchField",
+  "source": "src/components/SearchField.tsx",
+  "propsType": "SearchFieldProps",
+  "description": "SearchField — a text field for a search query.\n\nNOT `<Input type=\"search\">`. That gets the right input type and nothing\nelse. `useSearchField` adds what a search box owes its user:\n\n  `role=\"searchbox\"`, so a screen reader announces a search field, not a\n  text field. Enter calls `onSubmit` with the query. Escape clears it — a\n  second Escape then reaches whatever the field sits in, so a search inside\n  a dialog clears first and closes second. A clear button appears once there\n  is something to clear, named in the user's language by React Aria.\n\nThe clear button is out of the tab order on purpose, as React Aria sets it:\nEscape is the keyboard's way to clear, and an extra tab stop in every search\nbox costs every keyboard user a keystroke. Pressing it puts focus back in the\nfield.\n\nThe box IS Input's — the component renders `.ion-input` and its size and\nstate classes, so a search field beside an Input in a toolbar matches it\nexactly and cannot drift. Same arrangement as NumberInput.",
+  "import": "import { SearchField } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A text field for a search query: role=\"searchbox\", Enter submits, Escape clears, and a clear button once there is something to clear. Input's box and sizes.",
+  "useWhen": [
+    "the user types to search or filter a list, a table or a page — the search above a DataTable, the filter at the top of a Sidebar",
+    "the query is free text that narrows what is shown, not a value chosen from a list"
+  ],
+  "useInstead": [
+    {
+      "when": "the typed text picks one value from a known list — an assignee, a country",
+      "use": "Combobox",
+      "why": "a combobox commits a choice and offers the options; a search field commits a query and offers nothing"
+    },
+    {
+      "when": "the user is looking for a page or an action anywhere in the product",
+      "use": "CommandPalette",
+      "why": "that is global and keyboard-first; a SearchField searches the content in front of it"
+    },
+    {
+      "when": "it is ordinary text entry — a name, an email — that happens to be used for lookup later",
+      "use": "Input",
+      "why": "announcing a searchbox promises search behaviour: Escape clears, Enter searches"
+    }
+  ],
+  "composition": {
+    "order": [
+      "SearchField"
+    ],
+    "note": "Filter as the user types with `onChange`, or search on Enter with `onSubmit` — pick one per field and say which in the placeholder or label. In a table toolbar, give it `aria-label` naming what it searches.",
+    "example": "<SearchField aria-label=\"Search agents\" placeholder=\"Search by name or purpose\" value={query} onChange={setQuery} />"
+  },
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "toolbars, table headers and Sidebar filters, beside small Buttons"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a page whose main task is searching"
+      }
+    }
+  },
+  "a11y": {
+    "role": "searchbox",
+    "guarantees": [
+      "the input is role=\"searchbox\" and type=\"search\", so it is announced as a search field",
+      "Escape clears the query; a second Escape is left for whatever contains the field, so a search in a dialog clears before it closes",
+      "Enter calls onSubmit with the query",
+      "the clear button is named by React Aria in the user's language, appears only when there is something to clear, and returns focus to the field",
+      "the clear button is out of the tab order on purpose: Escape is the keyboard's way to clear, and an extra tab stop in every search box costs every keyboard user a keystroke",
+      "the browser's own cancel button is hidden, so there are never two"
+    ],
+    "requires": [
+      "`label`, or an `aria-label` naming what is searched when no visible label is rendered — \"Search\" alone does not say what"
+    ],
+    "notes": [
+      "When filtering as the user types, announce the result count with a polite live region near the results. The field cannot know how many results its query produced; the list does."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Input type=\"search\"> with a magnifier as leadingIcon",
+      "why": "it looks the same and has none of the behaviour: no searchbox role, no Escape to clear, no labelled clear button"
+    },
+    {
+      "dont": "placeholder as the only name",
+      "why": "a placeholder disappears once the user types, and is not a reliable accessible name. Pass `aria-label` or `label`"
+    },
+    {
+      "dont": "a separate Search button beside a field that already filters as you type",
+      "why": "it teaches the user that nothing happens until they press it, and it does nothing when they do"
+    }
+  ],
+  "stylesheet": "src/styles/search-field.css",
+  "tokens": [
+    "--border-focus",
+    "--border-width-thick",
+    "--icon-default",
+    "--icon-secondary",
+    "--ion-input-height",
+    "--ion-input-icon-size",
+    "--radius-sm",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-pressed"
+  ],
+  "props": {
+    "size": {
+      "type": "SearchFieldSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Input's sizes: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the control box (`.ion-input`)."
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the `.ion-field` wrapper when a label or helper is shown."
+    },
+    "enterKeyHint": {
+      "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
+      "values": [
+        "done",
+        "enter",
+        "go",
+        "next",
+        "previous",
+        "search",
+        "send"
+      ]
+    },
+    "type": {
+      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+      "tags": {
+        "default": "'search'"
+      }
+    },
+    "onSubmit": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "other",
+      "description": "Handler that is called when the SearchField is submitted."
+    },
+    "onClear": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "other",
+      "description": "Handler that is called when the clear button is pressed."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input is disabled."
+    },
+    "isReadOnly": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input can be selected but not changed by the user."
+    },
+    "isRequired": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether user input is required on the input before form submission."
+    },
+    "isInvalid": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the input value is invalid."
+    },
+    "validationState": {
+      "type": "ValidationState | undefined",
+      "required": false,
+      "origin": "aria",
+      "values": [
+        "valid",
+        "invalid"
+      ],
+      "tags": {
+        "deprecated": "Use `isInvalid` instead."
+      }
+    },
+    "validationBehavior": {
+      "type": "\"aria\" | \"native\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to use native HTML form validation to prevent form submission\nwhen the value is missing or invalid, or mark the field as required\nor invalid via ARIA.",
+      "values": [
+        "aria",
+        "native"
+      ],
+      "tags": {
+        "default": "'aria'"
+      }
+    },
+    "validate": {
+      "type": "((value: string) => ValidationError | true | null | undefined) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A function that returns an error message if a given value is invalid.\nValidation errors are displayed to the user when the form is submitted\nif `validationBehavior=\"native\"`. For realtime validation, use the `isInvalid`\nprop instead."
+    },
+    "description": {
+      "type": "ReactNode",
+      "required": false,
+      "origin": "aria",
+      "description": "A description for the field. Provides a hint such as specific requirements for what to choose."
+    },
+    "errorMessage": {
+      "type": "ReactNode | ((v: ValidationResult) => ReactNode)",
+      "required": false,
+      "origin": "aria",
+      "description": "An error message for the field."
+    },
+    "autoFocus": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether the element should receive focus on render."
+    },
+    "onFocus": {
+      "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element receives focus."
+    },
+    "onBlur": {
+      "type": "((e: FocusEvent<HTMLInputElement, Element>) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element loses focus."
+    },
+    "onFocusChange": {
+      "type": "((isFocused: boolean) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the element's focus status changes."
+    },
+    "onKeyDown": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is pressed."
+    },
+    "onKeyUp": {
+      "type": "((e: KeyboardEvent) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a key is released."
+    },
+    "placeholder": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Temporary text that occupies the text input when it is empty."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The default value (uncontrolled)."
+    },
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the value changes."
+    },
+    "label": {
+      "type": "ReactNode",
+      "required": false,
+      "origin": "aria",
+      "description": "The content to display as the label."
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The element's unique identifier. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id)."
+    },
+    "spellCheck": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An enumerated attribute that defines whether the element may be checked for spelling errors.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/spellcheck)."
+    },
+    "autoCorrect": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An attribute that takes as its value a space-separated string that describes what, if any, type\nof autocomplete functionality the input should provide. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#autocomplete)."
+    },
+    "inputMode": {
+      "type": "\"none\" | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"numeric\" | \"decimal\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Hints at the type of data that might be entered by the user while editing the element or its\ncontents. See\n[MDN](https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute).",
+      "values": [
+        "none",
+        "search",
+        "text",
+        "url",
+        "tel",
+        "email",
+        "numeric",
+        "decimal"
+      ]
+    },
+    "aria-activedescendant": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the currently active element when DOM focus is on a composite widget, textbox,\ngroup, or application."
+    },
+    "aria-autocomplete": {
+      "type": "\"inline\" | \"list\" | \"none\" | \"both\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates whether inputting text could trigger display of one or more predictions of the user's\nintended value for an input and specifies how predictions would be presented if they are made.",
+      "values": [
+        "inline",
+        "list",
+        "none",
+        "both"
+      ]
+    },
+    "aria-controls": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
+    },
+    "aria-describedby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that describes the object."
+    },
+    "aria-details": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that provide a detailed, extended description for the\nobject."
+    },
+    "aria-errormessage": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element that provides an error message for the object."
+    },
+    "aria-haspopup": {
+      "type": "boolean | \"true\" | \"false\" | \"menu\" | \"listbox\" | \"tree\" | \"grid\" | \"dialog\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Indicates the availability and type of interactive popup element, such as menu or dialog, that\ncan be triggered by an element."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Defines a string value that labels the current element."
+    },
+    "aria-labelledby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Identifies the element (or elements) that labels the current element."
+    },
+    "onCopy": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user copies text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncopy)."
+    },
+    "onCut": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user cuts text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/oncut)."
+    },
+    "onPaste": {
+      "type": "ClipboardEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the user pastes text. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/onpaste)."
+    },
+    "onCompositionEnd": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a text composition system completes or cancels the current text\ncomposition session. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionend_event)."
+    },
+    "onCompositionStart": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a text composition system starts a new text composition session.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)."
+    },
+    "onCompositionUpdate": {
+      "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when a new character is received in the current text composition\nsession. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event)."
+    },
+    "onBeforeInput": {
+      "type": "FormEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the input value is about to be modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event)."
+    },
+    "onInput": {
+      "type": "FormEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when the input value is modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)."
+    },
+    "onSelect": {
+      "type": "ReactEventHandler<HTMLInputElement> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+    },
+    "autoComplete": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
+    },
+    "maxLength": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The maximum number of characters supported by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength)."
+    },
+    "minLength": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
+    },
+    "pattern": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Regex pattern that the value of the input must match to be valid. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern)."
+    },
+    "excludeFromTabOrder": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+    }
+  },
+  "propCounts": {
+    "own": 3,
+    "aria": 51,
+    "dom": 264,
+    "other": 2
+  }
+}

package/dist/meta/Select.json

@@ -27,7 +27,8 @@
     },
     {
       "when": "the user may pick more than one",
-      "use": "Checkbox"
+      "use": "MultiSelect",
+      "why": "a native <select multiple> needs Ctrl or Cmd for a second pick and cannot filter; for a handful of options use CheckboxGroup"
     }
   ],
   "variants": {

package/dist/meta/Stepper.json

@@ -115,8 +115,8 @@
       "origin": "own",
       "description": "`horizontal` for a page-width header above the form, `vertical` for a side\nrail. Below 40rem a horizontal stepper hides every label but the current\none, so it does not need a second variant for mobile.",
       "values": [
-        "horizontal",
-        "vertical"
+        "vertical",
+        "horizontal"
       ]
     },
     "children": {

package/dist/meta/Tabs.json

@@ -163,13 +163,13 @@
       "default": "md"
     },
     "orientation": {
-      "type": "\"horizontal\" | \"vertical\" | undefined",
+      "type": "\"vertical\" | \"horizontal\" | undefined",
       "required": false,
       "origin": "own",
       "description": "Drives both the arrow-key axis and the track layout.\n\n`vertical` is keyboard- and ARIA-complete — up/down move between tabs, and\nthe track stacks — but its *decoration* is not: the underline rule and the\npill track's padding are still written for the horizontal axis only. Those\nare Figma's to specify, not this file's to invent. See tabs.css.",
       "values": [
-        "horizontal",
-        "vertical"
+        "vertical",
+        "horizontal"
       ],
       "tags": {
         "default": "'horizontal'"

package/dist/meta/Toolbar.json

@@ -0,0 +1,130 @@
+{
+  "name": "Toolbar",
+  "source": "src/components/Toolbar.tsx",
+  "propsType": "ToolbarProps",
+  "description": "Toolbar — a row of controls that act on one thing, reached as one stop.\n\nReact Aria's `useToolbar` gives it `role=\"toolbar\"` and `aria-orientation`,\narrow keys between its controls (mirrored in right-to-left), Tab that leaves\nthe whole toolbar rather than walking every button, and focus returned to the\ncontrol used last when Tab brings the user back. A toolbar inside a toolbar\nbecomes a `group`, so nesting one for grouping is safe.\n\nEvery control keeps its own tab stop in the DOM — React Aria moves focus to\nthe first or last control on Tab and lets the browser take it from there —\nso nothing here rewrites a child's `tabIndex`, and a control that mounts\nlater (the bulk actions appearing on selection) needs no registration.\n\nWHAT IT IS NOT FOR\n\nA filter bar. Tab leaves a toolbar in one press, so a search field inside one\nstrands the filters after it: Tab skips them and ← → belong to the caret.\nThat is WAI-ARIA's own caution about text fields in toolbars. A table's\nsearch and filters stay ordinary tab stops; the toolbar is the row of\nactions — the batch bar, a record's actions, an editor's formatting.",
+  "import": "import { Toolbar } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A row of controls that act on one thing, reached as one tab stop: arrow keys between the controls, Tab out in one press, and back to the control used last.",
+  "useWhen": [
+    "a set of actions on one selection or one record — the batch bar over a table, a run's Resume/Pause/Stop, an editor's formatting",
+    "the row has enough controls that tabbing through each one costs a keyboard user more than it gives"
+  ],
+  "useInstead": [
+    {
+      "when": "the row holds a search field or filters",
+      "use": "a plain flex row",
+      "why": "Tab leaves a toolbar in one press and ← → belong to the caret, so a text field inside strands every filter after it — WAI-ARIA's own caution"
+    },
+    {
+      "when": "two or three actions at the top of a page",
+      "use": "PageHeader",
+      "why": "its `actions` slot is a row of ordinary tab stops, which for a few buttons is what a keyboard user expects"
+    },
+    {
+      "when": "the controls are one choice among options",
+      "use": "SegmentedControl",
+      "why": "that is a radio group with a selected value; a toolbar holds independent actions"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Toolbar",
+      "Button",
+      "Divider",
+      "MenuTrigger"
+    ],
+    "note": "Buttons in the order they are read, a vertical Divider between groups, and a MenuTrigger with an icon-only Button last for the overflow. Name it with `aria-label` for what it acts on — \"Bulk actions\", not \"Toolbar\".",
+    "example": "<Toolbar aria-label=\"Bulk actions\"><Button size=\"sm\" variant=\"secondary\">Pause</Button><Divider orientation=\"vertical\" /><Button size=\"sm\" variant=\"destructive\">Delete 3</Button></Toolbar>"
+  },
+  "variants": {
+    "orientation": {
+      "horizontal": {
+        "use": "the default — ← → move between controls; wraps rather than overflowing"
+      },
+      "vertical": {
+        "use": "a side rail of tools — ↑ ↓ move between controls"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "Button, MenuTrigger, SegmentedControl, Divider, Toolbar",
+      "note": "a nested Toolbar becomes a named `group`, and the outer toolbar keeps the arrow keys"
+    }
+  },
+  "a11y": {
+    "role": "toolbar, with aria-orientation",
+    "guarantees": [
+      "React Aria's `useToolbar`: arrow keys move between controls, skipping disabled ones and separators, and are mirrored in right-to-left",
+      "Tab leaves the whole toolbar in one press, and Shift+Tab or Tab back in returns to the control used last",
+      "a text field, native select, combobox, slider or radio inside keeps its own arrow keys — the caret moves and the value changes instead of focus jumping",
+      "↓ still reaches a MenuTrigger in a horizontal toolbar, so an overflow menu opens as it does anywhere else"
+    ],
+    "requires": [
+      "`aria-label` or `aria-labelledby` naming what the toolbar acts on"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a table's search field and filters inside a Toolbar",
+      "why": "Tab from the search field leaves the toolbar, so the filters after it can only be reached by Shift+Tab and arrows"
+    },
+    {
+      "dont": "a Toolbar with one button",
+      "why": "a single stop gains nothing from arrow keys, and screen readers announce a toolbar the user has to learn"
+    },
+    {
+      "dont": "an unnamed Toolbar",
+      "why": "\"toolbar\" alone does not say what the buttons act on, and pages with two cannot be told apart"
+    }
+  ],
+  "stylesheet": "src/styles/toolbar.css",
+  "tokens": [
+    "--spacing-4",
+    "--spacing-8"
+  ],
+  "props": {
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the toolbar — \"Bulk actions\", \"Formatting\". Required, or `aria-labelledby`.",
+      "tags": {
+        "see": "aria-labelledby."
+      }
+    },
+    "aria-labelledby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Identifies the element (or elements) that labels the current element.",
+      "tags": {
+        "see": "aria-describedby."
+      }
+    },
+    "orientation": {
+      "type": "ToolbarOrientation | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Which arrow keys move between controls. Horizontal: ← →; vertical: ↑ ↓.",
+      "values": [
+        "vertical",
+        "horizontal"
+      ],
+      "default": "horizontal"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Buttons, MenuTriggers, a SegmentedControl, and a vertical Divider between groups."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 274,
+    "other": 0
+  }
+}