ionbase-ui 0.84.0 → 0.88.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.84.0",
+  "version": "0.88.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useAgentRun",
@@ -3080,8 +3080,7 @@
       "summary": "A native checkbox with the system's styling, supporting an indeterminate state.",
       "useWhen": [
         "a single on/off choice inside a form that is submitted",
-        "selecting rows in a Table",
-        "several independent options where more than one may be picked"
+        "selecting rows in a Table"
       ],
       "useInstead": [
         {
@@ -3089,6 +3088,11 @@
           "use": "Toggle",
           "why": "a switch reads as a setting taking effect now; a checkbox reads as a value being collected"
         },
+        {
+          "when": "several options answer one question",
+          "use": "CheckboxGroup",
+          "why": "it announces the question with each option, carries the group's error, and can require at least one"
+        },
         {
           "when": "the options are mutually exclusive",
           "use": "RadioGroup"
@@ -3220,8 +3224,7 @@
             "sm",
             "md",
             "lg"
-          ],
-          "default": "md"
+          ]
         },
         "intent": {
           "type": "CheckboxIntent | undefined",
@@ -3232,8 +3235,7 @@
             "neutral",
             "danger",
             "brand"
-          ],
-          "default": "brand"
+          ]
         },
         "isIndeterminate": {
           "type": "boolean | undefined",
@@ -3282,6 +3284,274 @@
         "other": 0
       }
     },
+    "CheckboxGroup": {
+      "name": "CheckboxGroup",
+      "source": "src/components/Checkbox.tsx",
+      "propsType": "CheckboxGroupProps",
+      "description": "A set of checkboxes that answers one question — \"notify me when…\", \"which\nregions\". Owns the selected values, the group's label, help text and error,\nand \"select at least one\".\n\nA row of loose Checkboxes can do none of that accessibly: the question is\nnot announced with the options, an error has nothing to attach to, and\n\"at least one\" has no native expression at all. See the `required` note in\nCheckbox for how that last one is done.",
+      "import": "import { CheckboxGroup } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A set of checkboxes answering one question. Owns the selected values, the group's label, help and error, and \"select at least one\".",
+      "useWhen": [
+        "several options may be picked and they answer one question — \"notify me when\", \"regions\", \"columns to show\"",
+        "the group needs a rule of its own — at least one, or an error that belongs to the set rather than to an option"
+      ],
+      "useInstead": [
+        {
+          "when": "only one option may be picked",
+          "use": "RadioGroup"
+        },
+        {
+          "when": "the options are many, or space is tight",
+          "use": "MultiSelect",
+          "why": "past about seven options a list of boxes is longer than the form around it; MultiSelect filters them and shows the chosen ones as tags"
+        },
+        {
+          "when": "there is one on/off choice",
+          "use": "Checkbox",
+          "why": "a group of one announces a question and then its only answer"
+        },
+        {
+          "when": "each option takes effect immediately",
+          "use": "Toggle"
+        }
+      ],
+      "composition": {
+        "order": [
+          "CheckboxGroup",
+          "Checkbox"
+        ],
+        "note": "Give every Checkbox a `value`; the group's `onChange` receives the array of ticked values. Selection lives on the group — do not also set `isSelected` on the boxes.",
+        "example": "<CheckboxGroup label=\"Notify the team when\" isRequired value={notifyOn} onChange={setNotifyOn} isInvalid={!!error} errorMessage={error}><Checkbox value=\"failed\">A run fails</Checkbox><Checkbox value=\"approval\">A run needs approval</Checkbox></CheckboxGroup>"
+      },
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms and filter panels"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "touch targets and prominent choices"
+          }
+        },
+        "intent": {
+          "brand": {
+            "use": "the default"
+          },
+          "neutral": {
+            "use": "facts rather than approvals — the columns shown, the filters applied"
+          },
+          "danger": {
+            "use": "a set of destructive consents"
+          }
+        },
+        "orientation": {
+          "vertical": {
+            "use": "the default, and always when a label runs past a few words"
+          },
+          "horizontal": {
+            "use": "two to four one-word options — weekdays, regions. Wraps rather than overflows"
+          }
+        }
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "renders as the <legend> — the question the options answer"
+        },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "shown only while `isInvalid` is set"
+        },
+        "children": {
+          "accepts": "Checkbox"
+        }
+      },
+      "a11y": {
+        "role": "group, from <fieldset> and <legend>",
+        "guarantees": [
+          "the legend is announced as the group's name when focus enters any box",
+          "the description or error is on every box's `aria-describedby` as well as the fieldset's, so it is read on the box that takes focus",
+          "`isInvalid` sets `aria-invalid` on every box",
+          "`isRequired` sets native `required` on every box while none is ticked and on none once one is: the browser blocks the submit in its own language, and each box announces \"required\" exactly while the rule is unmet",
+          "`isDisabled` cascades to every Checkbox that has not set its own"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when the question is already visible elsewhere",
+          "a `value` on every Checkbox — the group tracks the selection by it"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "loose Checkboxes under a text label",
+          "why": "the question is not announced with the options, an error has nothing to attach to, and \"at least one\" cannot be expressed"
+        },
+        {
+          "dont": "`isSelected` or `checked` on a Checkbox inside a group",
+          "why": "the group owns the selection; the box's own value is ignored"
+        },
+        {
+          "dont": "`isRequired` on every Checkbox in the group",
+          "why": "that means every box must be ticked; `isRequired` on the group means at least one"
+        }
+      ],
+      "stylesheet": "src/styles/checkbox.css",
+      "tokens": [
+        "--border-disabled",
+        "--border-error-strong",
+        "--border-focus",
+        "--border-inverse",
+        "--border-primary-strong",
+        "--border-stronger",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--icon-disabled",
+        "--icon-on-color",
+        "--ion-checkbox-border",
+        "--ion-checkbox-fill",
+        "--ion-checkbox-font-size",
+        "--ion-checkbox-gap",
+        "--ion-checkbox-line-height",
+        "--ion-checkbox-mark",
+        "--ion-checkbox-radius",
+        "--ion-checkbox-raised",
+        "--ion-checkbox-size",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-shadow-raised-flush-lg",
+        "--ion-shadow-raised-flush-sm",
+        "--ion-shadow-raised-flush-xs",
+        "--radius-sm",
+        "--radius-xs",
+        "--spacing-12",
+        "--spacing-16",
+        "--spacing-20",
+        "--spacing-24",
+        "--spacing-4",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-error",
+        "--surface-inverse",
+        "--surface-primary",
+        "--text-disabled",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The question the options answer. Renders as the `<legend>`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in the description's place while `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Marks every box invalid and shows `errorMessage`."
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "At least one option must be selected — enforced by native validation."
+        },
+        "value": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The selected values (controlled)."
+        },
+        "defaultValue": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The initially selected values (uncontrolled)."
+        },
+        "onChange": {
+          "type": "((value: string[]) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Receives the whole new selection, in the order the options were ticked."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Shared input name, so a form submits every ticked value under it."
+        },
+        "size": {
+          "type": "CheckboxSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "intent": {
+          "type": "CheckboxIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "neutral",
+            "danger",
+            "brand"
+          ]
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether every checkbox in the group is disabled."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "vertical",
+            "horizontal"
+          ]
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Checkboxes, each with a `value`."
+        }
+      },
+      "propCounts": {
+        "own": 14,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
     "Citation": {
       "name": "Citation",
       "source": "src/components/Citation.tsx",
@@ -3584,6 +3854,11 @@
           "use": "Select",
           "why": "the native control brings keyboard handling and the mobile platform picker for free; this rebuilds all of it"
         },
+        {
+          "when": "more than one value may be picked",
+          "use": "MultiSelect",
+          "why": "its input holds only the filter text, the list stays open between picks, and the chosen values show as tags"
+        },
         {
           "when": "there are two or three mutually exclusive choices worth showing at once",
           "use": "RadioGroup"
@@ -3625,6 +3900,9 @@
         "requires": [
           "`label`, or an `aria-label` when no visible label is rendered",
           "`emptyLabel` wording that says why nothing is listed, if the default is too terse"
+        ],
+        "notes": [
+          "While the list is open, React Aria hides everything outside the field and the list from assistive technology. That is the platform pattern for a combobox; a whole-page accessibility scan taken with the list open reports the hidden page, not this control."
         ]
       },
       "antiPatterns": [
@@ -4736,8 +5014,8 @@
           "origin": "own",
           "description": "Matches Figma's `Style` variant.",
           "values": [
-            "horizontal",
-            "vertical"
+            "vertical",
+            "horizontal"
           ]
         }
       },
@@ -5219,37 +5497,199 @@
         "other": 0
       }
     },
-    "FileUpload": {
-      "name": "FileUpload",
-      "source": "src/components/FileUpload.tsx",
-      "propsType": "FileUploadProps",
-      "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
-      "import": "import { FileUpload } from 'ionbase-ui';",
+    "Fieldset": {
+      "name": "Fieldset",
+      "source": "src/components/Fieldset.tsx",
+      "propsType": "FieldsetProps",
+      "description": "Groups related fields under one label, with one description and one error —\nan address, a date range typed as two fields, a set of limits.\n\nFor checkboxes use CheckboxGroup and for radios RadioGroup: both render this\nsame shell, and add the selection state it deliberately does not own.\n\nThere is no `isDisabled`. A native `disabled` fieldset does disable every\ncontrol inside, but Input, Select and the rest draw their disabled state from\ntheir own prop, so the fields would stop working while still looking live.\nDisable the fields themselves; the choice groups can cascade because their\ncheckboxes and radios style off `:disabled`.",
+      "import": "import { Fieldset } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
+      "summary": "A <fieldset>/<legend> that groups related fields under one label, one description and one error — an address, a pair of limits, a date typed as two fields.",
       "useWhen": [
-        "the user attaches one or more files to a form or a message",
-        "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
+        "several fields answer one question and a reader must hear the question with each of them — street, city and postcode under \"Billing address\"",
+        "one error belongs to the group rather than to a field — \"the minimum must be below the maximum\""
       ],
       "useInstead": [
         {
-          "when": "a single file is picked and no drop target or file list is wanted",
-          "use": "a plain <input type=\"file\">",
-          "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
+          "when": "the fields are checkboxes",
+          "use": "CheckboxGroup",
+          "why": "it renders this same shell and adds the selected values and \"select at least one\""
         },
         {
-          "when": "upload progress needs to be shown",
-          "use": "ProgressBar",
-          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+          "when": "the fields are radios",
+          "use": "RadioGroup",
+          "why": "it renders this same shell and adds the shared name and the selected value"
+        },
+        {
+          "when": "a single field needs a label and help text",
+          "use": "Input",
+          "why": "every field already renders its own label, description and error; a fieldset around one field announces the label twice"
+        },
+        {
+          "when": "the grouping is visual — a titled section of a settings page",
+          "use": "Card",
+          "why": "a fieldset is a form grouping that assistive technology announces on entry; a section of unrelated settings is not one question"
         }
       ],
+      "composition": {
+        "order": [
+          "Fieldset",
+          "Input"
+        ],
+        "note": "Each field keeps its own label — the legend names the group, not the fields. Put a group-level error in `errorMessage` with `isInvalid`, and keep field-level errors on the fields.",
+        "example": "<Fieldset label=\"Run limits\" description=\"Runs stop at whichever comes first.\" orientation=\"horizontal\"><NumberInput label=\"Max steps\" /><NumberInput label=\"Max minutes\" /></Fieldset>"
+      },
       "variants": {
-        "size": {
-          "sm": {
-            "use": "inside a dense form, or beside other fields"
+        "orientation": {
+          "vertical": {
+            "use": "the default — fields stacked, as a form reads"
           },
-          "md": {
-            "use": "the default — a standalone attachment area"
+          "horizontal": {
+            "use": "two or three short fields that read as one value — a range, a size, a city and postcode. Wraps rather than overflows"
+          }
+        }
+      },
+      "slots": {
+        "label": {
+          "accepts": "text",
+          "note": "renders as the <legend> — the question the fields answer"
+        },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the fields; replaced by `errorMessage` while `isInvalid` is set, as Input's is"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "the group's error, shown only while `isInvalid` is set"
+        },
+        "children": {
+          "accepts": "Input, Select, NumberInput, DatePicker and other fields"
+        }
+      },
+      "a11y": {
+        "role": "group, from <fieldset> and <legend>",
+        "guarantees": [
+          "the legend is announced as the group's name when focus enters any field inside",
+          "`aria-describedby` on the fieldset points at whichever of the description or the error is showing"
+        ],
+        "requires": [
+          "`label`, or `aria-label` when the question is already visible as a heading"
+        ],
+        "notes": [
+          "There is no `isDisabled`. A native disabled fieldset disables every control inside, but Input, Select and the rest draw their disabled look from their own prop — the fields would stop working while still looking live. Disable the fields themselves."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "a Fieldset around one field",
+          "why": "the field's label and the legend both announce, saying the same thing twice"
+        },
+        {
+          "dont": "a Fieldset of Checkboxes",
+          "do": "<CheckboxGroup label=\"Notify me when\">…</CheckboxGroup>",
+          "why": "it looks the same, but nothing owns the selected values or \"select at least one\""
+        },
+        {
+          "dont": "<fieldset disabled> around Inputs",
+          "why": "the fields stop accepting input while still drawn as enabled"
+        }
+      ],
+      "stylesheet": "src/styles/fieldset.css",
+      "tokens": [
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-regular",
+        "--ion-fieldset-gap",
+        "--ion-fieldset-inline-gap",
+        "--spacing-16",
+        "--spacing-6",
+        "--spacing-8",
+        "--text-error",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "label": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "The question the fields answer. Renders as the `<legend>`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Help text beneath the fields. Replaced by `errorMessage` while invalid."
+        },
+        "errorMessage": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in the description's place while `isInvalid` is set."
+        },
+        "isInvalid": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether the group as a whole fails validation."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "How the fields flow. Horizontal wraps rather than overflowing.",
+          "values": [
+            "vertical",
+            "horizontal"
+          ],
+          "default": "vertical"
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 279,
+        "other": 0
+      }
+    },
+    "FileUpload": {
+      "name": "FileUpload",
+      "source": "src/components/FileUpload.tsx",
+      "propsType": "FileUploadProps",
+      "description": "FileUpload — a drop target wrapped around a real `<input type=\"file\">`.\n\nDrawn in Figma as `File Upload` (1367:2333) — two sizes by five states. The\nmeasurements came from `Input` and `EmptyState` rather than being invented:\nthe border, radius and disabled treatment are Input's; the centred\nicon-over-text stack is EmptyState's. Figma draws the drop zone alone, the\nsame split `Input` makes against `Form Field`.\n\nTHE INPUT IS THE CONTROL. THE DROP ZONE IS DECORATION.\n\nThe usual build of this component is a `<div>` with drag handlers and a\nclick that calls `input.click()`. That version cannot be reached by keyboard,\nhas no accessible name, does not participate in a form, and does not work in\nany environment without a pointer — which includes switch access, voice\ncontrol and most screen-reader browse modes.\n\nHere the file input is a real, focusable, labelled control that is visually\nhidden but NOT `display: none` — it keeps its place in the tab order and its\nlabel. Drag-and-drop is layered on top as an enhancement, and every path it\noffers is also reachable without it. That ordering is the whole component.\n\nVALIDATION IS ADVISORY, NOT SECURITY. `accept` and `maxSize` are checked here\nso the user finds out immediately instead of after an upload. A server that\ntrusts either one is trusting a value the client chose.",
+      "import": "import { FileUpload } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A drop target wrapped around a real file input, with client-side accept and size checks.",
+      "useWhen": [
+        "the user attaches one or more files to a form or a message",
+        "the constraints (types, size, count) should be stated before the upload is attempted rather than after"
+      ],
+      "useInstead": [
+        {
+          "when": "a single file is picked and no drop target or file list is wanted",
+          "use": "a plain <input type=\"file\">",
+          "why": "this component adds a drop zone and a removable list; without either it is a heavier way to render the same control"
+        },
+        {
+          "when": "upload progress needs to be shown",
+          "use": "ProgressBar",
+          "why": "FileUpload selects files; it does not transfer them, and deliberately owns no network state"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "inside a dense form, or beside other fields"
+          },
+          "md": {
+            "use": "the default — a standalone attachment area"
           }
         }
       },
@@ -8074,128 +8514,397 @@
         "other": 0
       }
     },
-    "NavItem": {
-      "name": "NavItem",
-      "source": "src/components/NavItem.tsx",
-      "propsType": "NavItemProps",
-      "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
-      "import": "import { NavItem } from 'ionbase-ui';",
+    "MultiSelect": {
+      "name": "MultiSelect",
+      "source": "src/components/MultiSelect.tsx",
+      "propsType": "MultiSelectProps",
+      "description": "MultiSelect — a text field that filters a list, with any number of selected\nvalues shown as removable tags beneath it.\n\nWHY IT IS ITS OWN COMPONENT, NOT `Combobox selectionMode=\"multiple\"`\n\nThe two differ in what the field holds. Combobox's input shows the chosen\nlabel — typing edits the value. Here the input only ever holds the filter\ntext, the value lives in the tags, and choosing an option leaves the list\nopen for the next one. One prop switching the meaning of the text in the\nbox is the kind of contract agents get wrong in generated code.\n\nWHAT REACT ARIA GIVES IT\n\n`useComboBoxState` and `useComboBox` in `selectionMode: 'multiple'`: the\nlistbox is `aria-multiselectable`, Enter and click toggle an option without\nclosing the list, the filter text clears after each pick, and native\n`required` is set only while nothing is chosen — \"at least one\", the same\nrule CheckboxGroup enforces.\n\nWHAT IT ADDS\n\n  - The tags. A TagGroup under the field, named by the field's label, one\n    tab stop, Delete or the × to remove. The selection must be visible with\n    the list closed, and \"3 selected\" hides which three.\n  - The value is announced with the field. React Aria points the input's\n    `aria-describedby` at a value element; this fills it with the chosen\n    labels joined by `Intl.ListFormat`, so \"Billing, Legal and Ops\" is read\n    in the user's language with no string shipped for it.\n  - Backspace in an empty field removes the last value, which is what\n    every tag input on the web has taught people to expect.\n  - Focus lands back in the field when the last tag is removed, instead of\n    falling to <body> with the TagGroup that held it.",
+      "import": "import { MultiSelect } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
+      "summary": "A text field that filters a list, with any number of values chosen. The choices show as removable tags beneath the field and are read with it.",
       "useWhen": [
-        "building a header nav bar, a sidebar or a section switcher",
-        "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
+        "the user picks several values from a list too long to show as checkboxes — teams, regions, labels, assignees",
+        "a table filter can match more than one value — \"Status is Failing or Paused\""
       ],
       "useInstead": [
         {
-          "when": "the link sits inside body copy or a content block",
-          "use": "Link"
+          "when": "exactly one value is picked",
+          "use": "Combobox",
+          "why": "Combobox's input shows the chosen label; here the input only ever holds the filter text, and the list stays open for the next pick"
         },
         {
-          "when": "it is a row in a dropdown list rather than a top-level destination",
-          "use": "MenuItem"
+          "when": "there are about seven options or fewer",
+          "use": "CheckboxGroup",
+          "why": "every option visible at once beats typing to find one, and nothing is hidden behind a popover"
+        },
+        {
+          "when": "the values are free text the user invents, not options from a list",
+          "use": "TagGroup",
+          "why": "MultiSelect only chooses from `options`; a free-text tag input is a TagGroup beside an Input"
         }
       ],
+      "composition": {
+        "order": [
+          "MultiSelect"
+        ],
+        "note": "Pass the full `options` list; filtering, the tags and the announcement are the component's. In a table's filter bar, give it `aria-label` and `hideTags`, and list its values in the table's active-filters TagGroup — one removable tag per value, not the same tags twice.",
+        "example": "<MultiSelect label=\"Notify teams\" options={teams} value={teamIds} onChange={setTeamIds} placeholder=\"Search teams\" />"
+      },
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "dense forms, table filters"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "prominent single-field forms"
+          }
+        }
+      },
       "slots": {
-        "icon": {
-          "accepts": "Icon",
-          "note": "leading icon; omit its `label` — the item's text names it"
+        "label": {
+          "accepts": "text",
+          "note": "names the field and the tags beneath it"
+        },
+        "description": {
+          "accepts": "text",
+          "note": "replaced by `errorMessage` while `isInvalid` is set"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "shown only while `isInvalid` is set"
+        },
+        "emptyLabel": {
+          "accepts": "text",
+          "note": "shown in the list when the filter matches nothing"
         }
       },
       "a11y": {
-        "role": "link when `href` is set, button when it is not",
+        "role": "combobox, controlling a listbox that is aria-multiselectable",
         "guarantees": [
-          "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
-          "the focus ring shows for keyboard navigation only",
-          "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React",
-          "`isCurrent` sets `aria-current=\"page\"`, and the current item is marked by an underline as well as colour, which survives forced-colours mode"
+          "React Aria's multi-select combobox: arrow keys move through the list while focus stays in the input, Enter or click toggles an option, and the list stays open for the next pick",
+          "the chosen labels are on the input's `aria-describedby`, joined by `Intl.ListFormat` — read with the field in the user's language, with no string shipped for it",
+          "the chosen values are a TagGroup named by the field's label: one tab stop, arrow keys between tags, Delete or the × to remove",
+          "Backspace in an empty field removes the last value; with text in the field it only edits the text",
+          "removing the last tag returns focus to the field instead of dropping it on <body>",
+          "`isRequired` marks the field required only while nothing is chosen — at least one"
         ],
         "requires": [
-          "an accessible name — `children`, or `aria-label` on an icon-only item"
+          "`label`, or `aria-label` when there is no visible label — it names the tags as well as the field"
         ],
         "notes": [
-          "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
+          "While the list is open, React Aria hides everything outside the field and the list from assistive technology, the tags included. That is the platform pattern for a combobox, not a defect: the chosen options are marked selected in the list itself."
         ]
       },
       "antiPatterns": [
         {
-          "dont": "`showChevron` on a plain link that navigates",
-          "why": "the chevron promises a menu; nothing opens"
+          "dont": "a Combobox that appends each pick to a TagGroup by hand",
+          "why": "the list closes after every pick, the input shows the last label, and nothing announces what is chosen"
         },
         {
-          "dont": "marking the current page with colour only",
-          "do": "`aria-current=\"page\"`",
-          "why": "a screen-reader user is otherwise never told where they are"
+          "dont": "a native <select multiple>",
+          "why": "it needs Ctrl or Cmd to pick a second option, which most people never discover, and it cannot filter"
         },
         {
-          "dont": "marking the current page with a className or colour of your own instead of `isCurrent`",
-          "why": "a screen reader hears nothing without `aria-current`, and a colour-only marker fails anyone who cannot see the difference"
-        }
-      ],
-      "deprecated": [
+          "dont": "a count in place of the values — \"3 selected\"",
+          "why": "it hides which three; the tags show them and the field reads them"
+        },
         {
-          "prop": "disabled",
-          "replacement": "isDisabled"
+          "dont": "`hideTags` with nowhere else showing the values",
+          "why": "the field shows only the filter text, so the choice is invisible until the list is opened"
         }
       ],
-      "stylesheet": "src/styles/nav-item.css",
+      "stylesheet": "src/styles/multi-select.css",
       "tokens": [
-        "--border-focus",
-        "--border-primary",
+        "--border-disabled",
+        "--border-primary-strong",
+        "--border-stronger",
+        "--border-width-default",
         "--border-width-thick",
-        "--font-family-sans",
-        "--font-weight-medium",
-        "--icon-disabled",
-        "--icon-interactive-hover",
-        "--icon-primary",
-        "--icon-size-sm",
-        "--icon-tertiary",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--radius-sm",
+        "--font-weight-regular",
+        "--icon-on-color",
+        "--ion-shadow-raised-flush-xs",
+        "--radius-xs",
+        "--spacing-16",
+        "--spacing-2",
         "--spacing-4",
         "--spacing-8",
-        "--text-default",
-        "--text-disabled",
-        "--text-interactive-hover",
-        "--text-secondary",
-        "--type-body-sm",
-        "--type-body-sm-line-height"
+        "--surface-default",
+        "--surface-disabled",
+        "--surface-hover",
+        "--surface-primary",
+        "--type-body-line-height"
       ],
       "props": {
-        "icon": {
+        "options": {
+          "type": "readonly ComboboxOption[]",
+          "required": true,
+          "origin": "own",
+          "description": "The full option list. Filtering happens here, against what is typed."
+        },
+        "label": {
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Icon` slot — an optional leading icon."
+          "description": "Field label. Required for a usable control — see `a11y.requires`."
         },
-        "showChevron": {
-          "type": "boolean | undefined",
+        "aria-label": {
+          "type": "string | undefined",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Show Chevron`. Set on a nav item that opens a menu, not a plain link."
+          "description": "Names the field, and its tags, when there is no visible `label`."
         },
-        "isCurrent": {
-          "type": "boolean | undefined",
+        "description": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "The page the user is on. Marks the item `aria-current=\"page\"` and draws\nthe same indicator Tabs' underline does — so a section switcher built from\nNavItems says where you are, in words for a screen reader and in more than\ncolour for everyone else."
+          "description": "Helper text below the field."
         },
-        "isDisabled": {
-          "type": "boolean | undefined",
+        "errorMessage": {
+          "type": "React.ReactNode",
           "required": false,
-          "origin": "own"
+          "origin": "own",
+          "description": "Replaces the helper text when `isInvalid` is set."
         },
-        "disabled": {
+        "isInvalid": {
           "type": "boolean | undefined",
           "required": false,
-          "origin": "own",
-          "tags": {
-            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-          }
+          "origin": "own"
         },
-        "children": {
-          "type": "React.ReactNode",
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isReadOnly": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "At least one value must be chosen."
+        },
+        "size": {
+          "type": "MultiSelectSize | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "placeholder": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "value": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The selected values (controlled), in the order they were chosen."
+        },
+        "defaultValue": {
+          "type": "readonly string[] | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The initially selected values (uncontrolled)."
+        },
+        "onChange": {
+          "type": "((value: string[]) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Receives the whole new selection."
+        },
+        "inputValue": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Controlled filter text. Usually only needed for remote filtering."
+        },
+        "onInputChange": {
+          "type": "((value: string) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "hideTags": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Leave the tags out, when the chosen values are already on screen as\nremovable tags — a table's active-filters row. The values are still read\nwith the field, and still marked in the list."
+        },
+        "emptyLabel": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Shown in place of the list when nothing matches."
+        },
+        "buttonLabel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible label for the disclosure button."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Posts every selected value under this name, for an uncontrolled form."
+        },
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the field box (`.ion-input`)."
+        },
+        "wrapperClassName": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Class names for the `.ion-field` wrapper."
+        },
+        "id": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 23,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "NavItem": {
+      "name": "NavItem",
+      "source": "src/components/NavItem.tsx",
+      "propsType": "NavItemProps",
+      "description": "Nav Item renders an `<a>` when given `href`, a `<button>` otherwise —\nchosen by what the caller is actually building, the same judgment call\nMenu and Select make. A primary nav bar is links; a nav item with\n`showChevron` that opens a menu (no `href` of its own) is a button.\n\nInteraction state comes from React Aria rather than CSS pseudo-classes,\nmatching Button: `useHover` is pointer-aware so a tap does not stay\n\"hovered\" until the next tap elsewhere, and `useFocusRing` shows the ring\nonly for keyboard navigation. The CSS keeps its own `:hover` /\n`:focus-visible` rules so the stylesheet still works without React.",
+      "import": "import { NavItem } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A primary navigation destination. Renders an <a> when given `href`, a <button> otherwise.",
+      "useWhen": [
+        "building a header nav bar, a sidebar or a section switcher",
+        "an item opens a menu rather than navigating — pass `showChevron` and no `href`"
+      ],
+      "useInstead": [
+        {
+          "when": "the link sits inside body copy or a content block",
+          "use": "Link"
+        },
+        {
+          "when": "it is a row in a dropdown list rather than a top-level destination",
+          "use": "MenuItem"
+        }
+      ],
+      "slots": {
+        "icon": {
+          "accepts": "Icon",
+          "note": "leading icon; omit its `label` — the item's text names it"
+        }
+      },
+      "a11y": {
+        "role": "link when `href` is set, button when it is not",
+        "guarantees": [
+          "hover state comes from React Aria's pointer-aware `useHover`, so a tap does not stay hovered until the next tap elsewhere",
+          "the focus ring shows for keyboard navigation only",
+          "the CSS keeps its own `:hover` / `:focus-visible` rules, so the styling survives without React",
+          "`isCurrent` sets `aria-current=\"page\"`, and the current item is marked by an underline as well as colour, which survives forced-colours mode"
+        ],
+        "requires": [
+          "an accessible name — `children`, or `aria-label` on an icon-only item"
+        ],
+        "notes": [
+          "NavItem is one item, not the landmark. Wrap the set in a <nav> with its own accessible name."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "`showChevron` on a plain link that navigates",
+          "why": "the chevron promises a menu; nothing opens"
+        },
+        {
+          "dont": "marking the current page with colour only",
+          "do": "`aria-current=\"page\"`",
+          "why": "a screen-reader user is otherwise never told where they are"
+        },
+        {
+          "dont": "marking the current page with a className or colour of your own instead of `isCurrent`",
+          "why": "a screen reader hears nothing without `aria-current`, and a colour-only marker fails anyone who cannot see the difference"
+        }
+      ],
+      "deprecated": [
+        {
+          "prop": "disabled",
+          "replacement": "isDisabled"
+        }
+      ],
+      "stylesheet": "src/styles/nav-item.css",
+      "tokens": [
+        "--border-focus",
+        "--border-primary",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--icon-disabled",
+        "--icon-interactive-hover",
+        "--icon-primary",
+        "--icon-size-sm",
+        "--icon-tertiary",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--radius-sm",
+        "--spacing-4",
+        "--spacing-8",
+        "--text-default",
+        "--text-disabled",
+        "--text-interactive-hover",
+        "--text-secondary",
+        "--type-body-sm",
+        "--type-body-sm-line-height"
+      ],
+      "props": {
+        "icon": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Icon` slot — an optional leading icon."
+        },
+        "showChevron": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Show Chevron`. Set on a nav item that opens a menu, not a plain link."
+        },
+        "isCurrent": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The page the user is on. Marks the item `aria-current=\"page\"` and draws\nthe same indicator Tabs' underline does — so a section switcher built from\nNavItems says where you are, in words for a screen reader and in more than\ncolour for everyone else."
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "disabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+          }
+        },
+        "children": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own"
         },
@@ -10212,7 +10921,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -10304,10 +11012,10 @@
       "name": "RadioGroup",
       "source": "src/components/Radio.tsx",
       "propsType": "RadioGroupProps",
-      "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.",
+      "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.\n\nThe fieldset itself is Fieldset's shell, shared with CheckboxGroup, so the\ntwo choice groups take the same label, help, error and orientation props.",
       "import": "import { RadioGroup } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value.",
+      "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value, and the group's label, help and error.",
       "useWhen": [
         "exactly one choice from a small set, all worth showing at once",
         "the options need explaining — each one can carry its own label text"
@@ -10319,7 +11027,7 @@
         },
         {
           "when": "more than one may be picked",
-          "use": "Checkbox"
+          "use": "CheckboxGroup"
         },
         {
           "when": "there are exactly two states and the change is immediate",
@@ -10348,6 +11056,14 @@
           "danger": {
             "use": "a set where the options are destructive"
           }
+        },
+        "orientation": {
+          "vertical": {
+            "use": "the default, and always when a label runs past a few words"
+          },
+          "horizontal": {
+            "use": "two to four one-word options. Wraps rather than overflows"
+          }
         }
       },
       "slots": {
@@ -10355,6 +11071,14 @@
           "accepts": "text",
           "note": "renders as the <legend> — the question the options answer"
         },
+        "description": {
+          "accepts": "text",
+          "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
+        },
+        "errorMessage": {
+          "accepts": "text",
+          "note": "shown only while `isInvalid` is set"
+        },
         "children": {
           "accepts": "Radio"
         }
@@ -10364,7 +11088,10 @@
         "guarantees": [
           "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
           "`name` is generated when omitted, so two groups on one page never collide",
-          "`isDisabled` cascades to every Radio that has not set its own"
+          "`isDisabled` cascades to every Radio that has not set its own",
+          "the fieldset is Fieldset's shell, shared with CheckboxGroup — the same label, help, error and orientation props",
+          "the description or error is on every radio's `aria-describedby` as well as the fieldset's, so it is read on the radio that takes focus",
+          "`isRequired` is native `required` on the radios, which the platform already reads as \"one of this name\""
         ],
         "requires": [
           "`label`, or `aria-label` when the question is already visible elsewhere"
@@ -10401,7 +11128,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -10461,35 +11187,69 @@
         "label": {
           "type": "React.ReactNode",
           "required": false,
-          "origin": "own"
+          "origin": "own",
+          "description": "The question the options answer. Renders as the `<legend>`."
         },
-        "size": {
-          "type": "RadioSize | undefined",
+        "description": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "values": [
-            "sm",
-            "md",
-            "lg"
-          ]
+          "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
         },
-        "intent": {
-          "type": "RadioIntent | undefined",
+        "errorMessage": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "values": [
-            "neutral",
-            "danger",
-            "brand"
-          ]
+          "description": "Shown in the description's place while `isInvalid` is set."
         },
-        "isDisabled": {
+        "isInvalid": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Whether every radio in the group is disabled."
+          "description": "Shows `errorMessage` in the description's place."
         },
-        "disabled": {
+        "isRequired": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "One option must be chosen before the form submits."
+        },
+        "orientation": {
+          "type": "FieldsetOrientation | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "vertical",
+            "horizontal"
+          ]
+        },
+        "size": {
+          "type": "RadioSize | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ]
+        },
+        "intent": {
+          "type": "RadioIntent | undefined",
+          "required": false,
+          "origin": "own",
+          "values": [
+            "neutral",
+            "danger",
+            "brand"
+          ]
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether every radio in the group is disabled."
+        },
+        "disabled": {
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
@@ -10504,7 +11264,7 @@
         }
       },
       "propCounts": {
-        "own": 10,
+        "own": 15,
         "aria": 0,
         "dom": 276,
         "other": 0
@@ -10527,126 +11287,613 @@
           "when": "the sections are peer views rather than positions in one document",
           "use": "Tabs"
         },
-        {
-          "when": "it is site navigation rather than in-page position",
-          "use": "NavItem"
-        }
-      ],
-      "variants": {
-        "placement": {
-          "right": {
-            "use": "the default — a rail on the left of the content, opening across it"
-          },
-          "left": {
-            "use": "a rail against the right edge of the page; `right` would open the list off the screen"
-          }
-        }
-      },
-      "a11y": {
-        "role": "disclosure — a real <button> with aria-expanded and aria-controls",
-        "guarantees": [
-          "the rail is reachable by Tab and opens with Enter or Space, not just hover",
-          "closes on outside pointerdown and on Escape"
-        ],
-        "requires": [
-          "`progress` as 0–100 and `activeId` — the component has no opinion on where they come from",
-          "handling `onSelect` yourself: it reports the choice and does not scroll anywhere"
-        ],
-        "notes": [
-          "Deliberately not `role=\"menu\"` — see the stylesheet header. It is a disclosure with a list inside it, not a menu with roving focus.",
-          "Not a focus trap: it is the minimum a disclosure needs to not trap the page once opened."
-        ]
-      },
-      "antiPatterns": [
-        {
-          "dont": "expecting it to scroll the page when a section is chosen",
-          "why": "it reports the choice, matching Menu — what \"select this section\" means is the page's decision"
+        {
+          "when": "it is site navigation rather than in-page position",
+          "use": "NavItem"
+        }
+      ],
+      "variants": {
+        "placement": {
+          "right": {
+            "use": "the default — a rail on the left of the content, opening across it"
+          },
+          "left": {
+            "use": "a rail against the right edge of the page; `right` would open the list off the screen"
+          }
+        }
+      },
+      "a11y": {
+        "role": "disclosure — a real <button> with aria-expanded and aria-controls",
+        "guarantees": [
+          "the rail is reachable by Tab and opens with Enter or Space, not just hover",
+          "closes on outside pointerdown and on Escape"
+        ],
+        "requires": [
+          "`progress` as 0–100 and `activeId` — the component has no opinion on where they come from",
+          "handling `onSelect` yourself: it reports the choice and does not scroll anywhere"
+        ],
+        "notes": [
+          "Deliberately not `role=\"menu\"` — see the stylesheet header. It is a disclosure with a list inside it, not a menu with roving focus.",
+          "Not a focus trap: it is the minimum a disclosure needs to not trap the page once opened."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "expecting it to scroll the page when a section is chosen",
+          "why": "it reports the choice, matching Menu — what \"select this section\" means is the page's decision"
+        },
+        {
+          "dont": "deriving `progress` from a scroll listener without throttling",
+          "why": "this re-renders the rail on every scroll frame"
+        },
+        {
+          "dont": "expecting every section to be visible at once",
+          "why": "the panel caps at 60vh and scrolls — a document-length index would otherwise grow off both edges of the viewport, taking the rows nearest the active one with it"
+        },
+        {
+          "dont": "leaving `placement` at `right` for a rail on the page's right edge",
+          "why": "the open list runs past the viewport; `left` opens it back over the content"
+        }
+      ],
+      "stylesheet": "src/styles/scroll-progress.css",
+      "tokens": [
+        "--border-default",
+        "--border-focus",
+        "--border-strong",
+        "--border-stronger",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-scroll-progress-slide",
+        "--ion-shadow-shadow-md",
+        "--radius-full",
+        "--radius-md",
+        "--radius-sm",
+        "--spacing-24",
+        "--spacing-32",
+        "--spacing-4",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-muted",
+        "--text-default",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body-sm",
+        "--type-body-sm-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "progress": {
+          "type": "number",
+          "required": true,
+          "origin": "own",
+          "description": "0-100. The caller computes this from whatever it is tracking — a\nwindow scroll fraction, a custom scroll container, a reading-time\nestimate. This component has no opinion on the source."
+        },
+        "sections": {
+          "type": "ScrollProgressSection[]",
+          "required": true,
+          "origin": "own"
+        },
+        "activeId": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The section the rail's heavier tick and the panel's selected row point\nto. Also the caller's to compute — see `progress`."
+        },
+        "onSelect": {
+          "type": "((id: string) => void) | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Fired when a row is chosen. The component does not scroll anywhere\nitself; matching Menu, it reports the choice and lets the caller decide\nwhat \"select this section\" means for their page."
+        },
+        "placement": {
+          "type": "ScrollProgressPlacement | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Which way the section list opens. `right` suits a rail on the left of the\ncontent; a rail against the right edge of the page needs `left`, or the\nopen list runs off the screen.",
+          "values": [
+            "right",
+            "left"
+          ]
+        }
+      },
+      "propCounts": {
+        "own": 5,
+        "aria": 0,
+        "dom": 277,
+        "other": 0
+      }
+    },
+    "SearchField": {
+      "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)."
         },
-        {
-          "dont": "deriving `progress` from a scroll listener without throttling",
-          "why": "this re-renders the rail on every scroll frame"
+        "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)."
         },
-        {
-          "dont": "expecting every section to be visible at once",
-          "why": "the panel caps at 60vh and scrolls — a document-length index would otherwise grow off both edges of the viewport, taking the rows nearest the active one with it"
+        "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)."
         },
-        {
-          "dont": "leaving `placement` at `right` for a rail on the page's right edge",
-          "why": "the open list runs past the viewport; `left` opens it back over the content"
-        }
-      ],
-      "stylesheet": "src/styles/scroll-progress.css",
-      "tokens": [
-        "--border-default",
-        "--border-focus",
-        "--border-strong",
-        "--border-stronger",
-        "--border-width-default",
-        "--border-width-thick",
-        "--font-family-sans",
-        "--font-weight-regular",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--ion-scroll-progress-slide",
-        "--ion-shadow-shadow-md",
-        "--radius-full",
-        "--radius-md",
-        "--radius-sm",
-        "--spacing-24",
-        "--spacing-32",
-        "--spacing-4",
-        "--spacing-6",
-        "--spacing-8",
-        "--surface-default",
-        "--surface-muted",
-        "--text-default",
-        "--text-secondary",
-        "--text-tertiary",
-        "--type-body-sm",
-        "--type-body-sm-line-height",
-        "--type-caption",
-        "--type-caption-line-height"
-      ],
-      "props": {
-        "progress": {
-          "type": "number",
-          "required": true,
-          "origin": "own",
-          "description": "0-100. The caller computes this from whatever it is tracking — a\nwindow scroll fraction, a custom scroll container, a reading-time\nestimate. This component has no opinion on the source."
+        "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)."
         },
-        "sections": {
-          "type": "ScrollProgressSection[]",
-          "required": true,
-          "origin": "own"
+        "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)."
         },
-        "activeId": {
+        "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": "own",
-          "description": "The section the rail's heavier tick and the panel's selected row point\nto. Also the caller's to compute — see `progress`."
+          "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)."
         },
-        "onSelect": {
-          "type": "((id: string) => void) | undefined",
+        "name": {
+          "type": "string | undefined",
           "required": false,
-          "origin": "own",
-          "description": "Fired when a row is chosen. The component does not scroll anywhere\nitself; matching Menu, it reports the choice and lets the caller decide\nwhat \"select this section\" means for their page."
+          "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)."
         },
-        "placement": {
-          "type": "ScrollProgressPlacement | undefined",
+        "autoComplete": {
+          "type": "string | undefined",
           "required": false,
-          "origin": "own",
-          "description": "Which way the section list opens. `right` suits a rail on the left of the\ncontent; a rail against the right edge of the page needs `left`, or the\nopen list runs off the screen.",
-          "values": [
-            "right",
-            "left"
-          ]
+          "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": 5,
-        "aria": 0,
-        "dom": 277,
-        "other": 0
+        "own": 3,
+        "aria": 51,
+        "dom": 264,
+        "other": 2
       }
     },
     "SegmentedControl": {
@@ -11017,7 +12264,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": {
@@ -12339,8 +13587,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": {
@@ -13467,13 +14715,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'"
@@ -15107,6 +16355,136 @@
         "other": 0
       }
     },
+    "Toolbar": {
+      "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
+      }
+    },
     "ToolCall": {
       "name": "ToolCall",
       "source": "src/components/ToolCall.tsx",