ionbase-ui 0.81.1 → 0.86.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.81.1",
+  "version": "0.86.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": "Select",
+          "why": "past about seven options a list of boxes is longer than the form around it"
+        },
+        {
+          "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",
@@ -4736,8 +5006,8 @@
           "origin": "own",
           "description": "Matches Figma's `Style` variant.",
           "values": [
-            "horizontal",
-            "vertical"
+            "vertical",
+            "horizontal"
           ]
         }
       },
@@ -5219,44 +5489,206 @@
         "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"
           }
         }
       },
-      "a11y": {
-        "guarantees": [
-          "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
-          "the zone is a <label> for that input, so clicking anywhere opens the picker without any script",
+      "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"
+          }
+        }
+      },
+      "a11y": {
+        "guarantees": [
+          "the control is a real <input type=\"file\">, focusable and in the tab order — the drop zone is an enhancement layered on top, never the only way in",
+          "the zone is a <label> for that input, so clicking anywhere opens the picker without any script",
           "the input is clipped to 1px rather than display:none, which would remove it from the tab order and the accessibility tree",
           "the focus ring is drawn on the zone, where the user is looking, not on the clipped input",
           "a polite live region announces the number of files held, because a drop changes nothing near the user's focus",
@@ -7046,65 +7478,108 @@
       "name": "Menu",
       "source": "src/components/Menu.tsx",
       "propsType": "MenuProps",
-      "description": "Menu is the list surface, not a popover.\n\nFigma models the list alone — there is no trigger, anchor or open state in\nthe design — so this renders the surface and nothing else. Positioning it\nagainst a button is the caller's job until Figma has a component that says\nhow. Building a popover here would be inventing design, and it would be the\nhard half to unpick later.\n\n`role=\"menu\"` is deliberately NOT set. A real ARIA menu owes the user\nroving-tabindex arrow navigation, typeahead and focus containment; claiming\nthe role without them is worse for a screen-reader user than an honest list,\nbecause it promises interactions that are not there. When the popover exists,\nthe role comes with it.",
+      "description": "Menu — Figma `Menu` (82:306), `Menu Item` and `Menu Section Title`.\n\nA real ARIA menu: `role=\"menu\"`, one tab stop, arrow keys, Home and End,\ntypeahead, and disabled rows listed but skipped. Figma's `Type` is\n`selectionMode` — Single draws one check, Multi draws several — and with\na selection mode the rows become `menuitemradio` / `menuitemcheckbox` and\nannounce their checked state.\n\nOn its own it is the surface only, rendered in flow. Inside a MenuTrigger it\nfloats, opens and closes, is named by its trigger, and can open submenus.",
       "import": "import { Menu } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "The list surface only — no trigger, no anchor, no open state. Positioning it is the caller's job.",
+      "summary": "An ARIA menu: one tab stop, arrow keys, typeahead, and optional single or multiple selection. Children are MenuItem and MenuSection. Inside a MenuTrigger it floats, opens and closes, and can open submenus; on its own it renders in flow.",
       "useWhen": [
-        "rendering a list of actions or options as a surface you have already positioned",
-        "the rows need icons, a selected check, or two lines — more than a native <select> can hold"
+        "a list of actions or choices for the thing the user is on — row actions, a workspace switcher, a sort order",
+        "the rows need icons, a selected check, or grouping under headings — more than a native <select> can hold"
       ],
       "useInstead": [
         {
-          "when": "you want a self-contained dropdown with a trigger and open state",
-          "use": "Popover",
-          "why": "Menu is the surface alone; Popover owns the trigger, positioning, focus containment and Escape"
+          "when": "a button opens it",
+          "use": "MenuTrigger",
+          "why": "it gives the trigger aria-haspopup and aria-expanded, opens on ArrowDown, and closes on an action and returns focus — a Popover round a Menu does none of that"
         },
         {
-          "when": "one value is picked from a modest list of plain text options",
+          "when": "one value is picked for a form field from a modest list of plain text options",
           "use": "Select",
-          "why": "the native picker brings keyboard handling, type-ahead and the mobile platform picker for free"
+          "why": "a form value is a listbox, not a menu; the native picker brings type-ahead and the mobile platform picker for free"
         },
         {
-          "when": "it is primary navigation rather than a dropdown",
-          "use": "NavItem"
+          "when": "the user types to narrow a long list down to one value",
+          "use": "Combobox"
+        },
+        {
+          "when": "it is primary navigation rather than a list of actions",
+          "use": "NavItem",
+          "why": "a menu's rows are actions; links to pages belong in the document's navigation, where a screen reader's landmarks find them"
+        },
+        {
+          "when": "any action or page should be reachable by searching",
+          "use": "CommandPalette"
         }
       ],
       "composition": {
         "order": [
           "Menu",
+          "MenuSection",
           "MenuItem"
         ],
-        "example": "<Menu><MenuItem icon={<Icon as={Copy} />}>Duplicate</MenuItem><MenuItem isSelected>Archive</MenuItem></Menu>"
+        "note": "MenuItem and MenuSection are collection elements: Menu reads them from its DIRECT children to build the collection, and neither renders anything itself. Every MenuItem needs a `key`, and `onAction`, `selectedKeys` and `disabledKeys` all speak in those keys. To open it from a button, put the Button and the Menu inside a MenuTrigger.",
+        "example": "<Menu aria-label=\"Row actions\" onAction={(key) => run(key)}><MenuSection title=\"Edit\"><MenuItem key=\"rename\" icon={<Icon as={Pencil} />}>Rename</MenuItem><MenuItem key=\"duplicate\">Duplicate</MenuItem></MenuSection><MenuSection aria-label=\"Danger\"><MenuItem key=\"archive\" isDisabled>Archive</MenuItem></MenuSection></Menu>"
+      },
+      "variants": {
+        "selectionMode": {
+          "none": {
+            "use": "the default — a list of actions. Rows are `menuitem`, and there is no check slot"
+          },
+          "single": {
+            "use": "Figma's Type=Single — one current choice, such as a sort order or the active workspace. Rows are `menuitemradio`"
+          },
+          "multiple": {
+            "use": "Figma's Type=Multi — independent toggles, such as visible columns. Rows are `menuitemcheckbox`"
+          }
+        }
       },
       "slots": {
         "children": {
-          "accepts": "MenuItem"
+          "accepts": [
+            "MenuItem",
+            "MenuSection"
+          ]
         }
       },
       "a11y": {
-        "role": "none — it is a plain <ul>",
+        "role": "menu",
         "guarantees": [
-          "no `role=\"menu\"`, deliberately: a real ARIA menu owes the user roving tabindex, arrow-key navigation and typeahead, and claiming the role without them promises interactions that are not there"
+          "one tab stop; arrow keys move between rows, Home and End jump, and typing a letter moves to the next row starting with it",
+          "disabled rows are listed and announced as unavailable, and the arrow keys skip them",
+          "with a selection mode, rows are `menuitemradio` or `menuitemcheckbox` and announce `aria-checked` — the check glyph is never the only signal",
+          "the pointer and the keyboard share one highlighted row: hovering a row focuses it"
+        ],
+        "requires": [
+          "an accessible name — `aria-label` or `aria-labelledby` naming what the actions are for"
         ],
         "notes": [
-          "Each MenuItem is a real <button>, so Tab reaches every row. That is honest, and it is not the same as arrow-key menu navigation.",
-          "The role arrives when the popover that owns it does."
+          "A menu is not a form control. It has no `name` and submits nothing; `selectedKeys` is state you hold.",
+          "Titled sections are named groups. An untitled section needs `aria-label`, and is set off by a rule.",
+          "Submenus need a MenuTrigger. In a standalone Menu a row with MenuItem children renders as a plain row: there is no root to open a submenu from."
         ]
       },
       "antiPatterns": [
         {
-          "dont": "adding `role=\"menu\"` yourself",
-          "why": "the keyboard behaviour that role promises is not implemented; an honest list is better for a screen-reader user than a lying menu"
+          "dont": "wrapping MenuItems in a <div>, a fragment or your own component inside Menu",
+          "why": "Menu reads its collection from its direct children; a wrapped row is invisible to it and renders nothing"
+        },
+        {
+          "dont": "an `onClick` on MenuItem",
+          "why": "MenuItem renders nothing, so there is no element to click. Pass `onAction` to Menu; it receives the item's key, from the pointer, Enter and Space alike"
         },
         {
-          "dont": "using Menu as a dropdown without positioning it",
-          "why": "it renders in flow — it has no anchor logic of its own"
+          "dont": "using Menu for a form field's value",
+          "why": "a screen reader announces a menu as actions, and a form cannot read it. Use Select or Combobox"
+        },
+        {
+          "dont": "putting links to other pages in a Menu",
+          "why": "they vanish from the page's link list and landmarks. Navigation belongs in NavItem or Sidebar"
         }
       ],
       "stylesheet": "src/styles/menu.css",
       "tokens": [
         "--border-focus",
+        "--border-strong",
         "--border-subtle",
         "--border-width-default",
         "--border-width-thick",
@@ -7116,10 +7591,13 @@
         "--icon-size-sm",
         "--ion-duration-base",
         "--ion-ease-out",
+        "--ion-menu-min-width",
+        "--ion-shadow-shadow-lg",
         "--radius-sm",
         "--radius-xl",
         "--spacing-12",
         "--spacing-2",
+        "--spacing-4",
         "--spacing-40",
         "--spacing-6",
         "--spacing-8",
@@ -7129,20 +7607,148 @@
         "--text-disabled",
         "--text-primary",
         "--text-secondary",
+        "--text-tertiary",
         "--type-body",
-        "--type-body-line-height"
+        "--type-body-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
       ],
       "props": {
-        "children": {
-          "type": "React.ReactNode",
+        "className": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "style": {
+          "type": "React.CSSProperties | undefined",
           "required": false,
           "origin": "own"
+        },
+        "escapeKeyBehavior": {
+          "type": "\"none\" | \"clearSelection\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether pressing the escape key should clear selection in the menu or not.\n\nMost experiences should not modify this option as it eliminates a keyboard user's ability to\neasily clear selection. Only use if the escape key is being handled externally or should not\ntrigger selection clearing contextually.",
+          "values": [
+            "none",
+            "clearSelection"
+          ],
+          "tags": {
+            "default": "'clearSelection'"
+          }
+        },
+        "autoFocus": {
+          "type": "boolean | FocusStrategy | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Where the focus should be set."
+        },
+        "shouldFocusWrap": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether keyboard navigation is circular."
+        },
+        "onAction": {
+          "type": "((key: Key, value: T) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when an item is selected."
+        },
+        "onClose": {
+          "type": "(() => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the menu should close after selecting an item."
+        },
+        "children": {
+          "type": "CollectionChildren<T>",
+          "required": true,
+          "origin": "aria",
+          "description": "The contents of the collection."
+        },
+        "items": {
+          "type": "Iterable<T> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Item objects in the collection."
+        },
+        "disabledKeys": {
+          "type": "Iterable<Key> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The item keys that are disabled. These items cannot be selected, focused, or otherwise\ninteracted with."
+        },
+        "selectionMode": {
+          "type": "SelectionMode | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The type of selection that is allowed in the collection.",
+          "values": [
+            "multiple",
+            "none",
+            "single"
+          ]
+        },
+        "disallowEmptySelection": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether the collection allows empty selection."
+        },
+        "selectedKeys": {
+          "type": "Iterable<Key> | \"all\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The currently selected keys in the collection (controlled)."
+        },
+        "defaultSelectedKeys": {
+          "type": "Iterable<Key> | \"all\" | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The initial selected keys in the collection (uncontrolled)."
+        },
+        "onSelectionChange": {
+          "type": "((keys: Selection) => void) | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the selection changes."
+        },
+        "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)."
+        },
+        "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."
+        },
+        "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."
         }
       },
       "propCounts": {
-        "own": 1,
-        "aria": 0,
-        "dom": 277,
+        "own": 2,
+        "aria": 18,
+        "dom": 0,
         "other": 0
       }
     },
@@ -7150,11 +7756,12 @@
       "name": "MenuItem",
       "source": "src/components/Menu.tsx",
       "propsType": "MenuItemProps",
+      "description": "One row of a Menu. A collection element, like TabItem: it renders nothing\nitself — Menu reads its props and draws the row — so it only means anything\nas a direct child of Menu or MenuSection. Give it a `key`; that key is what\n`onAction` and `selectedKeys` speak in.",
       "import": "import { MenuItem } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+      "summary": "One row of a Menu. A collection element: Menu reads its props and draws the row as `menuitem`, `menuitemradio` or `menuitemcheckbox`.",
       "useWhen": [
-        "a row in a Menu surface"
+        "a row in a Menu or a MenuSection — it is not usable anywhere else"
       ],
       "useInstead": [
         {
@@ -7166,6 +7773,14 @@
           "use": "Button"
         }
       ],
+      "composition": {
+        "order": [
+          "Menu",
+          "MenuItem"
+        ],
+        "note": "A collection element, like TabItem: it renders nothing itself and never appears in the DOM. `key` identifies it to Menu's `onAction`, `selectedKeys` and `disabledKeys`.",
+        "example": "<MenuItem key=\"duplicate\" icon={<Icon as={Copy} />}>Duplicate</MenuItem>\n<MenuItem key=\"move\" title=\"Move to\"><MenuItem key=\"archive\">Archive</MenuItem></MenuItem>"
+      },
       "slots": {
         "icon": {
           "accepts": "Icon",
@@ -7174,37 +7789,50 @@
         "children": {
           "accepts": "text",
           "note": "the row label"
+        },
+        "title": {
+          "accepts": "text",
+          "note": "only on a row that opens a submenu: the row's label, while its children are the submenu's MenuItems. Submenus open only inside a MenuTrigger"
         }
       },
       "a11y": {
-        "role": "button",
         "guarantees": [
-          "`isSelected` sets `aria-pressed`, so the selected state is announced and not only drawn",
-          "the check glyph always occupies its slot, so rows never reflow as the selection moves"
+          "the role, `aria-checked` and `aria-disabled` are supplied by Menu from its selection mode and keys, not by this element",
+          "the check glyph occupies its slot whenever the menu has a selection mode, so rows never reflow as the selection moves"
         ],
         "requires": [
-          "a text label in `children`"
+          "a stable `key`",
+          "text in `children`, or `textValue` when the children are not plain text — typeahead matches against it"
         ]
       },
       "antiPatterns": [
         {
           "dont": "using MenuItem outside a Menu",
-          "why": "it renders an <li>, which is only valid inside a list"
+          "why": "it renders nothing on its own"
         },
         {
           "dont": "an icon-only MenuItem with no children",
-          "why": "the row announces nothing"
+          "why": "the row announces nothing and typeahead cannot reach it"
+        },
+        {
+          "dont": "array indexes as keys in a list that can change",
+          "why": "selection and actions are expressed in keys, so the selected row silently becomes a different row"
         }
       ],
       "deprecated": [
         {
           "prop": "disabled",
           "replacement": "isDisabled"
+        },
+        {
+          "prop": "isSelected",
+          "note": "Put the item's key in Menu's `selectedKeys` and set its `selectionMode`."
         }
       ],
       "stylesheet": "src/styles/menu.css",
       "tokens": [
         "--border-focus",
+        "--border-strong",
         "--border-subtle",
         "--border-width-default",
         "--border-width-thick",
@@ -7216,10 +7844,13 @@
         "--icon-size-sm",
         "--ion-duration-base",
         "--ion-ease-out",
+        "--ion-menu-min-width",
+        "--ion-shadow-shadow-lg",
         "--radius-sm",
         "--radius-xl",
         "--spacing-12",
         "--spacing-2",
+        "--spacing-4",
         "--spacing-40",
         "--spacing-6",
         "--spacing-8",
@@ -7229,15 +7860,18 @@
         "--text-disabled",
         "--text-primary",
         "--text-secondary",
+        "--text-tertiary",
         "--type-body",
-        "--type-body-line-height"
+        "--type-body-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
       ],
       "props": {
-        "isSelected": {
-          "type": "boolean | undefined",
+        "title": {
+          "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Selected` / `Selected-hover` states. Shows the trailing check."
+          "description": "Only on a row that opens a submenu: the row's label. Its children are then\nthe submenu's MenuItems rather than its label. Submenus open only inside a\nMenuTrigger — a standalone Menu has nothing to open them from."
         },
         "icon": {
           "type": "React.ReactNode",
@@ -7249,7 +7883,7 @@
           "type": "boolean | undefined",
           "required": false,
           "origin": "own",
-          "description": "Whether the item is disabled."
+          "description": "Whether the item is disabled. Listed, skipped by the arrow keys."
         },
         "disabled": {
           "type": "boolean | undefined",
@@ -7259,113 +7893,472 @@
             "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
           }
         },
+        "isSelected": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "deprecated": "Put the item's key in Menu's `selectedKeys`. Accepted for one\nminor version: when no item's key is in `selectedKeys` and Menu is given\nneither `selectedKeys` nor `defaultSelectedKeys`, the items passing this\nbecome the selection."
+          }
+        },
         "children": {
-          "type": "React.ReactNode",
+          "type": "ReactNode",
+          "required": true,
+          "origin": "aria",
+          "description": "Rendered contents of the item or child items."
+        },
+        "textValue": {
+          "type": "string | undefined",
           "required": false,
-          "origin": "own"
+          "origin": "aria",
+          "description": "A string representation of the item's contents, used for features like typeahead."
+        },
+        "aria-label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "An accessibility label for this item."
+        },
+        "childItems": {
+          "type": "Iterable<T> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A list of child item objects. Used for dynamic collections."
+        },
+        "hasChildItems": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether this item has children, even if not loaded yet."
+        },
+        "href": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href)."
+        },
+        "hrefLang": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Hints at the human language of the linked URL.\nSee[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang)."
+        },
+        "target": {
+          "type": "HTMLAttributeAnchorTarget | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The target window for the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)."
+        },
+        "rel": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
+        },
+        "download": {
+          "type": "string | boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Causes the browser to download the linked URL. A string may be provided to suggest a file name.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download)."
+        },
+        "ping": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "A space-separated list of URLs to ping when the link is followed. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping)."
+        },
+        "referrerPolicy": {
+          "type": "HTMLAttributeReferrerPolicy | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "How much of the referrer to send when following the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy).",
+          "values": [
+            "",
+            "origin",
+            "no-referrer",
+            "no-referrer-when-downgrade",
+            "origin-when-cross-origin",
+            "same-origin",
+            "strict-origin",
+            "strict-origin-when-cross-origin",
+            "unsafe-url"
+          ]
+        },
+        "routerOptions": {
+          "type": "undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Options for the configured client side router."
         }
       },
       "propCounts": {
         "own": 5,
+        "aria": 13,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "MenuSection": {
+      "name": "MenuSection",
+      "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Section.d.ts",
+      "propsType": null,
+      "import": "import { MenuSection } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "A named group of MenuItems. Re-exported from react-stately's collection Section — `title` is Figma's Menu Section Title.",
+      "useWhen": [
+        "a Menu has more than one kind of action, such as editing actions and destructive ones",
+        "the rows fall into groups the user scans by name"
+      ],
+      "useInstead": [
+        {
+          "when": "the menu has one group",
+          "use": "MenuItem",
+          "why": "a single section adds a heading the user must hear before every menu, and says nothing the menu's own label does not"
+        }
+      ],
+      "composition": {
+        "order": [
+          "Menu",
+          "MenuSection",
+          "MenuItem"
+        ],
+        "note": "A collection element: Menu reads it from its direct children. With `title`, the heading is drawn with a rule after it; without one, `aria-label` names the group and a rule is drawn above it instead.",
+        "example": "<MenuSection title=\"Sort by\"><MenuItem key=\"name\">Name</MenuItem><MenuItem key=\"updated\">Last updated</MenuItem></MenuSection>"
+      },
+      "a11y": {
+        "role": "group",
+        "guarantees": [
+          "the group is named by its title, so a screen reader announces it on entering the first row"
+        ],
+        "requires": [
+          "a `title`; an untitled section still needs a label for the group, or it is announced as an unnamed group"
+        ],
+        "notes": [
+          "The accessible-name lint rule is deliberately not driven from here: a titled section is named by its title and needs nothing more, so demanding a label on every MenuSection would be wrong for the common case."
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "nesting a MenuSection inside another",
+          "why": "a menu has one level of grouping; a section inside a section renders nothing"
+        }
+      ],
+      "stylesheet": "src/styles/menu.css",
+      "tokens": [
+        "--border-focus",
+        "--border-strong",
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--icon-default",
+        "--icon-disabled",
+        "--icon-primary",
+        "--icon-size-sm",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-menu-min-width",
+        "--ion-shadow-shadow-lg",
+        "--radius-sm",
+        "--radius-xl",
+        "--spacing-12",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-40",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-hover",
+        "--surface-primary-subtle",
+        "--text-disabled",
+        "--text-primary",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {},
+      "propCounts": {
+        "own": 0,
         "aria": 0,
-        "dom": 285,
+        "dom": 0,
         "other": 0
       }
     },
-    "Modal": {
-      "name": "Modal",
-      "source": "src/components/Modal.tsx",
-      "propsType": "ModalProps",
-      "description": "Modal — Figma `Modal` (792:1537).\n\n`Size` x `Align`, with the sections as props rather than variants. The panel\nhugs its content at every size except `fullscreen`, which fills the viewport\nand pushes the actions to the bottom edge.\n\nRENDERS NOTHING WHEN CLOSED, and mounts into a portal when open. Both come\nfrom React Aria's `Overlay`, and both matter: a modal left in the tree while\nclosed is still focusable by keyboard, and one rendered inline inherits any\n`overflow: hidden` or stacking context from wherever it was written.\n\nThe scrim is part of this component in code, unlike in Figma — see the note\nin modal.css.",
-      "import": "import { Modal } from 'ionbase-ui';",
+    "MenuTrigger": {
+      "name": "MenuTrigger",
+      "source": "src/components/Menu.tsx",
+      "propsType": "MenuTriggerProps",
+      "description": "MenuTrigger — a Button that opens a Menu.\n\nThe \"⋯\" overflow menu is this with an icon-only Button; there is no separate\ncomponent for it, because the only difference is the Button's content and\nits required aria-label.\n\n`useMenuTrigger` does what a Popover wrapped round a Menu could not: the\ntrigger announces `aria-haspopup=\"menu\"` and `aria-expanded`, the menu is\nnamed by the trigger, ArrowDown and ArrowUp open it with focus on the first\nor last row, and choosing an action closes it and returns focus to the\ntrigger.",
+      "import": "import { MenuTrigger } from 'ionbase-ui';",
       "status": "stable",
-      "since": "0.11.0",
-      "summary": "A focus-trapping dialog. Renders nothing when closed and portals when open.",
+      "summary": "A Button that opens a Menu. The \"⋯\" overflow menu is this with an icon-only Button. Owns open state, positioning, focus, and the ARIA link between the two.",
       "useWhen": [
-        "the task must be completed or abandoned before anything else",
-        "confirming a destructive action",
-        "a short focused form that would otherwise need its own page"
+        "a button opens a list of actions — row actions, an overflow \"⋯\", a \"New\" button with several kinds of new",
+        "a button opens a list of choices applied immediately, such as a sort order",
+        "the actions nest one level or more — submenus open only inside a MenuTrigger"
       ],
       "useInstead": [
         {
-          "when": "the content is supplementary and the page stays usable",
+          "when": "the button opens a form, a filter panel or anything that is not a list of rows",
           "use": "Popover",
-          "why": "a Popover does not trap focus or block the page"
+          "why": "a menu promises arrow keys between rows and nothing else; a field inside it cannot be reached"
         },
         {
-          "when": "it is a short label for a control",
-          "use": "Tooltip"
+          "when": "the choice is a form field's value",
+          "use": "Select",
+          "why": "a form value is a listbox the form can read, not a menu of actions"
+        },
+        {
+          "when": "there are only two or three actions and room to show them",
+          "use": "Button",
+          "why": "hiding actions behind a menu costs a click and makes them undiscoverable; show them when they fit"
         }
       ],
+      "composition": {
+        "order": [
+          "MenuTrigger",
+          "Button",
+          "Menu"
+        ],
+        "note": "Exactly two children, in this order: the Button, then the Menu. The Menu is named by the Button unless it has its own aria-label. A MenuItem with a `title` and MenuItem children opens a submenu; `onAction` on the root Menu receives actions from every level.",
+        "example": "<MenuTrigger><Button variant=\"tertiary\" aria-label=\"Actions for Payroll\" startIcon={<Icon as={Ellipsis} />} /><Menu onAction={(key) => run(key)}><MenuItem key=\"rename\">Rename</MenuItem><MenuItem key=\"move\" title=\"Move to\"><MenuItem key=\"archive\">Archive</MenuItem><MenuItem key=\"trash\">Trash</MenuItem></MenuItem></Menu></MenuTrigger>"
+      },
       "variants": {
-        "size": {
-          "sm": {
-            "use": "confirmations and single-question prompts"
-          },
-          "md": {
-            "use": "the default; short forms"
+        "placement": {
+          "bottom start": {
+            "use": "the default — below, aligned to the trigger's start edge"
           },
-          "lg": {
-            "use": "multi-section forms"
+          "bottom end": {
+            "use": "a trigger at the end of a row or toolbar, so the menu does not run off the edge"
           },
-          "fullscreen": {
-            "use": "immersive tasks; fills the viewport and pins the actions to the bottom edge"
-          }
-        },
-        "align": {
-          "left": {
-            "use": "the default; forms and anything the user reads"
+          "top start": {
+            "use": "a trigger near the bottom of the viewport, such as a footer"
           },
-          "center": {
-            "use": "single-message confirmations only"
+          "top end": {
+            "use": "as top start, for a trigger at the end of its row"
           }
         }
       },
       "slots": {
-        "footer": {
-          "accepts": "Button",
-          "note": "the primary action goes last, at the trailing edge"
-        },
-        "media": {
-          "note": "rendered above the title"
+        "children": {
+          "accepts": [
+            "Button",
+            "Menu"
+          ],
+          "note": "the Button first, the Menu second"
         }
       },
       "a11y": {
-        "role": "dialog",
+        "role": "none — the Button gets aria-haspopup=\"menu\" and aria-expanded; the Menu is the menu",
+        "namesChild": true,
         "guarantees": [
-          "focus moves into the panel on open and returns to the trigger on close",
-          "Escape and a scrim click both close it",
-          "focus is trapped while open",
-          "nothing is rendered at all while closed, so no closed-modal content is keyboard reachable"
+          "Enter, Space and ArrowDown open the menu with focus on its first row; ArrowUp opens it on the last",
+          "choosing an action closes every open level and returns focus to the trigger; so do Escape and an outside click",
+          "the menu is named by the trigger unless it has its own aria-label",
+          "a submenu opens with the right arrow, Enter or Space and closes with the left arrow or Escape, which puts focus back on the row that opened it",
+          "submenus are non-modal: the parent menu stays on screen and hoverable, so the pointer can move between levels"
         ],
         "requires": [
-          "`title`, which provides the dialog's accessible name"
+          "an icon-only trigger Button needs its own aria-label — it names the menu too"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "rendering <Modal> only when a state flag is true",
-          "do": "render it always and drive `isOpen`",
-          "why": "Modal already renders nothing when closed. Wrapping it in a conditional discards the open/close transition and the focus-return behaviour."
+          "dont": "wrapping a Menu in a Popover to make a dropdown",
+          "why": "the trigger then announces a dialog, not a menu, the arrow keys cannot open it, and choosing an action does not close it. That is exactly what MenuTrigger exists to replace"
         },
         {
-          "dont": "opening a Modal from inside another Modal",
-          "why": "two focus traps compete and Escape becomes ambiguous"
+          "dont": "a plain <button> as the trigger",
+          "why": "the trigger must accept react-aria press props and a ref; IonBase's Button does, a DOM button silently never opens"
         },
         {
-          "dont": "a destructive action as the only button, with no cancel",
-          "why": "a confirmation with no way out is not a confirmation"
+          "dont": "more than two levels of submenu",
+          "why": "each level is a hover target narrower than the last; past two, the pointer falls off the path and the menu closes. Flatten with sections instead"
         }
       ],
-      "stylesheet": "src/styles/modal.css",
+      "stylesheet": "src/styles/menu.css",
       "tokens": [
+        "--border-focus",
+        "--border-strong",
         "--border-subtle",
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
         "--font-weight-regular",
-        "--font-weight-semibold",
-        "--icon-primary",
+        "--icon-default",
+        "--icon-disabled",
+        "--icon-primary",
+        "--icon-size-sm",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-menu-min-width",
+        "--ion-shadow-shadow-lg",
+        "--radius-sm",
+        "--radius-xl",
+        "--spacing-12",
+        "--spacing-2",
+        "--spacing-4",
+        "--spacing-40",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-default",
+        "--surface-hover",
+        "--surface-primary-subtle",
+        "--text-disabled",
+        "--text-primary",
+        "--text-secondary",
+        "--text-tertiary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-caption",
+        "--type-caption-line-height"
+      ],
+      "props": {
+        "children": {
+          "type": "[React.ReactElement<unknown, string | React.JSXElementConstructor<any>>, React.ReactElement<unknown, string | React.JSXElementConstructor<any>>]",
+          "required": true,
+          "origin": "own",
+          "description": "Exactly two children: the Button that opens the menu, then the Menu. The\nButton must accept a ref and react-aria press props — IonBase's Button\ndoes; a plain `<button>` does not."
+        },
+        "placement": {
+          "type": "MenuTriggerPlacement | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Where the menu opens, relative to the trigger. A preference, not a\nguarantee: it flips when there is no room.",
+          "values": [
+            "bottom start",
+            "bottom end",
+            "top start",
+            "top end"
+          ]
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether the trigger is disabled."
+        },
+        "isOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "defaultOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onOpenChange": {
+          "type": "((isOpen: boolean) => void) | undefined",
+          "required": false,
+          "origin": "own"
+        }
+      },
+      "propCounts": {
+        "own": 6,
+        "aria": 0,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "Modal": {
+      "name": "Modal",
+      "source": "src/components/Modal.tsx",
+      "propsType": "ModalProps",
+      "description": "Modal — Figma `Modal` (792:1537).\n\n`Size` x `Align`, with the sections as props rather than variants. The panel\nhugs its content at every size except `fullscreen`, which fills the viewport\nand pushes the actions to the bottom edge.\n\nRENDERS NOTHING WHEN CLOSED, and mounts into a portal when open. Both come\nfrom React Aria's `Overlay`, and both matter: a modal left in the tree while\nclosed is still focusable by keyboard, and one rendered inline inherits any\n`overflow: hidden` or stacking context from wherever it was written.\n\nThe scrim is part of this component in code, unlike in Figma — see the note\nin modal.css.",
+      "import": "import { Modal } from 'ionbase-ui';",
+      "status": "stable",
+      "since": "0.11.0",
+      "summary": "A focus-trapping dialog. Renders nothing when closed and portals when open.",
+      "useWhen": [
+        "the task must be completed or abandoned before anything else",
+        "confirming a destructive action",
+        "a short focused form that would otherwise need its own page"
+      ],
+      "useInstead": [
+        {
+          "when": "the content is supplementary and the page stays usable",
+          "use": "Popover",
+          "why": "a Popover does not trap focus or block the page"
+        },
+        {
+          "when": "it is a short label for a control",
+          "use": "Tooltip"
+        }
+      ],
+      "variants": {
+        "size": {
+          "sm": {
+            "use": "confirmations and single-question prompts"
+          },
+          "md": {
+            "use": "the default; short forms"
+          },
+          "lg": {
+            "use": "multi-section forms"
+          },
+          "fullscreen": {
+            "use": "immersive tasks; fills the viewport and pins the actions to the bottom edge"
+          }
+        },
+        "align": {
+          "left": {
+            "use": "the default; forms and anything the user reads"
+          },
+          "center": {
+            "use": "single-message confirmations only"
+          }
+        }
+      },
+      "slots": {
+        "footer": {
+          "accepts": "Button",
+          "note": "the primary action goes last, at the trailing edge"
+        },
+        "media": {
+          "note": "rendered above the title"
+        }
+      },
+      "a11y": {
+        "role": "dialog",
+        "guarantees": [
+          "focus moves into the panel on open and returns to the trigger on close",
+          "Escape and a scrim click both close it",
+          "focus is trapped while open",
+          "nothing is rendered at all while closed, so no closed-modal content is keyboard reachable"
+        ],
+        "requires": [
+          "`title`, which provides the dialog's accessible name"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "dont": "rendering <Modal> only when a state flag is true",
+          "do": "render it always and drive `isOpen`",
+          "why": "Modal already renders nothing when closed. Wrapping it in a conditional discards the open/close transition and the focus-return behaviour."
+        },
+        {
+          "dont": "opening a Modal from inside another Modal",
+          "why": "two focus traps compete and Escape becomes ambiguous"
+        },
+        {
+          "dont": "a destructive action as the only button, with no cancel",
+          "why": "a confirmation with no way out is not a confirmation"
+        }
+      ],
+      "stylesheet": "src/styles/modal.css",
+      "tokens": [
+        "--border-subtle",
+        "--border-width-default",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-regular",
+        "--font-weight-semibold",
+        "--icon-primary",
         "--icon-secondary",
         "--icon-size-lg",
         "--icon-size-md",
@@ -8063,112 +9056,281 @@
         "other": 2
       }
     },
-    "Pagination": {
-      "name": "Pagination",
-      "source": "src/components/Pagination.tsx",
-      "propsType": "PaginationProps",
-      "description": "Page navigation for a table or list.\n\nGeometry from the Figma `Pagination` (1291:503) and `Pagination Item`\n(1283:289) components. The Figma item set is not exported — a caller places a\nPagination, never a cell.",
-      "import": "import { Pagination } from 'ionbase-ui';",
+    "PageHeader": {
+      "name": "PageHeader",
+      "source": "src/components/PageHeader.tsx",
+      "propsType": "PageHeaderProps",
+      "description": "PageHeader — the top of a page: where you are, what it is, and what you can\ndo to it.\n\nPromoted from the demo app, where five screens hand-wrote it in three\ndifferent shapes (`.demo-page__header`, `.demo-run-header`, and a bare\n`<div>`), each with its own gap and its own idea of where the actions\naligned. Every enterprise system ships one — Carbon's PageHeader,\nLightning's page headers — because every page has one.\n\nNOT A LANDMARK\n\nIt renders a `<div>`, not a `<header>`. A `<header>` that is a child of\n`<body>` is the page's banner, and the app shell's Header already is that.\nThe page's landmark is `<main>`, named by this title: pass `titleId` and\npoint `<main aria-labelledby>` at it.\n\nNo `'use client'`: `useId` resolves on the server, and nothing here is\ninteractive. Interactive parts arrive through the slots.",
+      "import": "import { PageHeader } from 'ionbase-ui';",
       "status": "stable",
-      "summary": "Page navigation for a table or list. Renders prev/next arrows, a truncated run of page numbers, and an optional rows-per-page Select.",
+      "summary": "The top of a page: breadcrumb, the page's h1, a description, the record's status, and the page's actions. Not a landmark — main is, named by this title.",
       "useWhen": [
-        "a result set is split into pages and the user needs to move between them",
-        "the total number of pages is known — the numbered run needs a last page to anchor to"
+        "the top of every page inside the app shell — list pages, record pages, settings, wizards",
+        "the page has a title and actions that act on the whole page, such as New agent or Pause"
       ],
       "useInstead": [
         {
-          "when": "the total is unknown or unbounded, as with a cursor-based or infinite feed",
-          "use": "Button",
-          "why": "a numbered pager has to draw a last page; with no total there is nothing to draw, and a bare Load more button is honest about that"
+          "when": "it is the bar across the top of the whole app, with the logo and the account menu",
+          "use": "Header",
+          "why": "Header is the banner landmark, rendered once by the shell. PageHeader is inside main and changes with each page"
         },
         {
-          "when": "the user is moving between peer views rather than through one long list",
-          "use": "Tabs",
-          "why": "pagination implies a sequence with a position; tabs are peers in any order"
+          "when": "it titles one section of a page rather than the page",
+          "use": "Card",
+          "why": "a Card's title is an h2 for a named region; a page has one PageHeader and one h1"
         },
         {
-          "when": "it is navigation between pages of the app rather than pages of data",
-          "use": "NavItem"
+          "when": "the page is empty or failed to load",
+          "use": "EmptyState",
+          "why": "keep the PageHeader so the user still knows where they are, and put the EmptyState beneath it with headingLevel 2"
         }
       ],
-      "variants": {
-        "type": {
-          "numbered": {
-            "use": "the default — prev, the page numbers, next. Use wherever the numbers fit"
-          },
-          "simple": {
-            "use": "prev, \"Page N of M\", next. For drawers, narrow columns and mobile, where a numbered run would wrap or truncate to uselessness"
-          }
+      "composition": {
+        "order": [
+          "PageHeader",
+          "Breadcrumb",
+          "Badge",
+          "Button",
+          "MenuTrigger",
+          "Tabs"
+        ],
+        "note": "Slots, not children: `breadcrumb` above, `status` beside the title, `actions` at the end of the title row, and `children` as a row beneath for the page's Tabs or filters. Pass `titleId` and point `<main aria-labelledby>` at it.",
+        "example": "<main aria-labelledby=\"page-title\"><PageHeader titleId=\"page-title\" title=\"Payroll reconciler\" description=\"Matches payroll exports against the ledger every night.\" breadcrumb={<Breadcrumb><BreadcrumbItem href=\"/agents\">Agents</BreadcrumbItem><BreadcrumbItem isCurrent>Payroll reconciler</BreadcrumbItem></Breadcrumb>} status={<Badge intent=\"warning\">Paused</Badge>} actions={<><MenuTrigger><Button variant=\"tertiary\" aria-label=\"More actions\" startIcon={<Icon as={Ellipsis} />} /><Menu onAction={run}><MenuItem key=\"delete\">Delete…</MenuItem></Menu></MenuTrigger><Button variant=\"primary-brand\">Resume</Button></>} /></main>"
+      },
+      "slots": {
+        "breadcrumb": {
+          "accepts": "Breadcrumb"
         },
-        "size": {
-          "sm": {
-            "use": "dense tables, and toolbars"
-          },
-          "md": {
-            "use": "the default"
-          },
-          "lg": {
-            "use": "roomy layouts, and touch targets on tablet"
-          }
+        "status": {
+          "accepts": [
+            "Badge",
+            "Tag"
+          ],
+          "note": "the record's state. Never an action, and never colour alone — a Badge carries its label"
+        },
+        "actions": {
+          "accepts": [
+            "Button",
+            "MenuTrigger",
+            "Link"
+          ],
+          "note": "most important last, so the primary action sits at the end of the row. One primary Button at most; beyond two or three actions, put the rest in a MenuTrigger"
+        },
+        "children": {
+          "accepts": [
+            "Tabs",
+            "SegmentedControl"
+          ],
+          "note": "a row that belongs to the header: the page's own tabs, or the filters its table answers to"
         }
       },
       "a11y": {
-        "role": "navigation / list",
+        "role": "none — a <div>. The page's landmark is <main>, named by this title",
         "guarantees": [
-          "the whole control is a landmark — a `nav` with an accessible name, defaulting to \"Pagination\"",
-          "the current page carries `aria-current=\"page\"`, not `aria-pressed`: this is a position in a set, not a toggle",
-          "every cell has an explicit label — \"Go to page 4\", \"Go to previous page\" — so a screen reader never announces a bare digit",
-          "the ellipsis is `aria-hidden` and not focusable: it marks absent pages, and a tab stop that does nothing when activated is worse than no tab stop",
-          "in `simple`, the \"Page N of M\" text is an `aria-live=\"polite\"` region, because the page can change without anything else on screen announcing it",
-          "prev and next are genuinely `disabled` at the ends rather than styled to look it",
-          "the focus ring shows for keyboard focus only, and hover does not latch on touch"
+          "the title is a real heading, h1 by default, with a stable id for aria-labelledby",
+          "actions keep their DOM order when they wrap beneath the title on a narrow screen, so reading order matches visual order"
         ],
-        "requires": [
-          "`aria-label` when more than one Pagination is on a page — two identically named landmarks are two indistinguishable landmarks",
-          "`pageSize` when `showPageSize` is set, or the rows-per-page Select renders with nothing selected"
+        "notes": [
+          "`headingLevel` is 1 by default. Use 2 only for a header on a pane that is not the page — the detail half of a list-detail layout, under the list's h1.",
+          "It is deliberately not a <header>: a <header> directly inside <body> is the banner, and the app shell's Header already is that."
         ]
       },
       "antiPatterns": [
         {
-          "avoid": "passing `pageCount={0}` for an empty result set",
-          "instead": "render EmptyState and no pager — the component clamps to a single page, which draws a lone disabled `1` that says a page exists when none does"
+          "dont": "two PageHeaders on one page",
+          "why": "two h1s, and two answers to where am I. Sections below the header are Cards with h2 titles"
         },
         {
-          "avoid": "raising `siblingCount` to avoid truncation",
-          "instead": "switch to `type=\"simple\"`. Widening the run past the container is the problem truncation exists to solve, and it reappears one breakpoint down"
+          "dont": "dropping the PageHeader while the page loads or fails",
+          "why": "the user loses where they are exactly when something went wrong. Keep the title; put Skeleton or EmptyState beneath it"
         },
         {
-          "avoid": "treating `page` as 0-based",
-          "instead": "it is 1-based, matching what the numbers say. An off-by-one here is silent — the pager looks right and fetches the wrong rows"
+          "dont": "putting filters or a search field in `actions`",
+          "why": "actions act on the page; filters narrow what it shows. Filters go in `children`, the row beneath"
+        },
+        {
+          "dont": "several primary Buttons in `actions`",
+          "why": "a page has one next step. The one-primary-action lint rule counts them"
         }
       ],
-      "stylesheet": "src/styles/pagination.css",
+      "stylesheet": "src/styles/page-header.css",
       "tokens": [
-        "--border-focus",
-        "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
-        "--font-weight-regular",
-        "--icon-size-lg",
-        "--icon-size-md",
-        "--icon-size-xs",
-        "--ion-duration-base",
-        "--ion-ease-out",
-        "--ion-pagination-box",
-        "--ion-pagination-font-size",
-        "--ion-pagination-icon",
-        "--ion-pagination-line-height",
-        "--radius-md",
+        "--font-weight-semibold",
+        "--ion-page-header-heading-basis",
         "--spacing-16",
-        "--spacing-2",
-        "--spacing-32",
         "--spacing-4",
-        "--spacing-40",
-        "--spacing-48",
-        "--spacing-6",
         "--spacing-8",
-        "--surface-hover",
-        "--surface-selected",
+        "--text-default",
+        "--text-secondary",
+        "--type-body",
+        "--type-body-line-height",
+        "--type-h4",
+        "--type-h4-line-height"
+      ],
+      "props": {
+        "title": {
+          "type": "React.ReactNode",
+          "required": true,
+          "origin": "own",
+          "description": "The page's title. Rendered as the `h1`."
+        },
+        "titleId": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "The title's id. Pass it when something else points at the heading —\n`<main aria-labelledby>` is the usual one. Generated when omitted."
+        },
+        "headingLevel": {
+          "type": "PageHeaderHeadingLevel | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Heading element for the title. Defaults to `1`."
+        },
+        "description": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "One or two sentences under the title: what this page is for."
+        },
+        "breadcrumb": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "A Breadcrumb, above the title."
+        },
+        "status": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "Beside the title: a Badge or two for the record's state — \"Paused\",\n\"Draft\". State, not actions."
+        },
+        "actions": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "At the end of the title row: the page's actions, most important last.\nOne primary Button at most; several more go in a MenuTrigger."
+        },
+        "children": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "description": "A row beneath, that belongs to the header rather than the page's\ncontent: the page's Tabs, or the filters its table answers to."
+        }
+      },
+      "propCounts": {
+        "own": 8,
+        "aria": 0,
+        "dom": 276,
+        "other": 0
+      }
+    },
+    "Pagination": {
+      "name": "Pagination",
+      "source": "src/components/Pagination.tsx",
+      "propsType": "PaginationProps",
+      "description": "Page navigation for a table or list.\n\nGeometry from the Figma `Pagination` (1291:503) and `Pagination Item`\n(1283:289) components. The Figma item set is not exported — a caller places a\nPagination, never a cell.",
+      "import": "import { Pagination } from 'ionbase-ui';",
+      "status": "stable",
+      "summary": "Page navigation for a table or list. Renders prev/next arrows, a truncated run of page numbers, and an optional rows-per-page Select.",
+      "useWhen": [
+        "a result set is split into pages and the user needs to move between them",
+        "the total number of pages is known — the numbered run needs a last page to anchor to"
+      ],
+      "useInstead": [
+        {
+          "when": "the total is unknown or unbounded, as with a cursor-based or infinite feed",
+          "use": "Button",
+          "why": "a numbered pager has to draw a last page; with no total there is nothing to draw, and a bare Load more button is honest about that"
+        },
+        {
+          "when": "the user is moving between peer views rather than through one long list",
+          "use": "Tabs",
+          "why": "pagination implies a sequence with a position; tabs are peers in any order"
+        },
+        {
+          "when": "it is navigation between pages of the app rather than pages of data",
+          "use": "NavItem"
+        }
+      ],
+      "variants": {
+        "type": {
+          "numbered": {
+            "use": "the default — prev, the page numbers, next. Use wherever the numbers fit"
+          },
+          "simple": {
+            "use": "prev, \"Page N of M\", next. For drawers, narrow columns and mobile, where a numbered run would wrap or truncate to uselessness"
+          }
+        },
+        "size": {
+          "sm": {
+            "use": "dense tables, and toolbars"
+          },
+          "md": {
+            "use": "the default"
+          },
+          "lg": {
+            "use": "roomy layouts, and touch targets on tablet"
+          }
+        }
+      },
+      "a11y": {
+        "role": "navigation / list",
+        "guarantees": [
+          "the whole control is a landmark — a `nav` with an accessible name, defaulting to \"Pagination\"",
+          "the current page carries `aria-current=\"page\"`, not `aria-pressed`: this is a position in a set, not a toggle",
+          "every cell has an explicit label — \"Go to page 4\", \"Go to previous page\" — so a screen reader never announces a bare digit",
+          "the ellipsis is `aria-hidden` and not focusable: it marks absent pages, and a tab stop that does nothing when activated is worse than no tab stop",
+          "in `simple`, the \"Page N of M\" text is an `aria-live=\"polite\"` region, because the page can change without anything else on screen announcing it",
+          "prev and next are genuinely `disabled` at the ends rather than styled to look it",
+          "the focus ring shows for keyboard focus only, and hover does not latch on touch"
+        ],
+        "requires": [
+          "`aria-label` when more than one Pagination is on a page — two identically named landmarks are two indistinguishable landmarks",
+          "`pageSize` when `showPageSize` is set, or the rows-per-page Select renders with nothing selected"
+        ]
+      },
+      "antiPatterns": [
+        {
+          "avoid": "passing `pageCount={0}` for an empty result set",
+          "instead": "render EmptyState and no pager — the component clamps to a single page, which draws a lone disabled `1` that says a page exists when none does"
+        },
+        {
+          "avoid": "raising `siblingCount` to avoid truncation",
+          "instead": "switch to `type=\"simple\"`. Widening the run past the container is the problem truncation exists to solve, and it reappears one breakpoint down"
+        },
+        {
+          "avoid": "treating `page` as 0-based",
+          "instead": "it is 1-based, matching what the numbers say. An off-by-one here is silent — the pager looks right and fetches the wrong rows"
+        }
+      ],
+      "stylesheet": "src/styles/pagination.css",
+      "tokens": [
+        "--border-focus",
+        "--border-width-thick",
+        "--font-family-sans",
+        "--font-weight-medium",
+        "--font-weight-regular",
+        "--icon-size-lg",
+        "--icon-size-md",
+        "--icon-size-xs",
+        "--ion-duration-base",
+        "--ion-ease-out",
+        "--ion-pagination-box",
+        "--ion-pagination-font-size",
+        "--ion-pagination-icon",
+        "--ion-pagination-line-height",
+        "--radius-md",
+        "--spacing-16",
+        "--spacing-2",
+        "--spacing-32",
+        "--spacing-4",
+        "--spacing-40",
+        "--spacing-48",
+        "--spacing-6",
+        "--spacing-8",
+        "--surface-hover",
+        "--surface-selected",
         "--surface-selected-hover",
         "--text-default",
         "--text-disabled",
@@ -9482,7 +10644,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -9574,10 +10735,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"
@@ -9589,7 +10750,7 @@
         },
         {
           "when": "more than one may be picked",
-          "use": "Checkbox"
+          "use": "CheckboxGroup"
         },
         {
           "when": "there are exactly two states and the change is immediate",
@@ -9618,6 +10779,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": {
@@ -9625,6 +10794,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"
         }
@@ -9634,7 +10811,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"
@@ -9671,7 +10851,6 @@
         "--border-width-default",
         "--border-width-thick",
         "--font-family-sans",
-        "--font-weight-medium",
         "--icon-disabled",
         "--icon-on-color",
         "--ion-duration-base",
@@ -9731,7 +10910,41 @@
         "label": {
           "type": "React.ReactNode",
           "required": false,
-          "origin": "own"
+          "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": "Shows `errorMessage` in the description's place."
+        },
+        "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",
@@ -9774,7 +10987,7 @@
         }
       },
       "propCounts": {
-        "own": 10,
+        "own": 15,
         "aria": 0,
         "dom": 276,
         "other": 0
@@ -9919,6 +11132,493 @@
         "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)."
+        },
+        "onCompositionStart": {
+          "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a text composition system starts a new text composition session.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionstart_event)."
+        },
+        "onCompositionUpdate": {
+          "type": "CompositionEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when a new character is received in the current text composition\nsession. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/compositionupdate_event)."
+        },
+        "onBeforeInput": {
+          "type": "FormEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is about to be modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/beforeinput_event)."
+        },
+        "onInput": {
+          "type": "FormEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when the input value is modified. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event)."
+        },
+        "onSelect": {
+          "type": "ReactEventHandler<HTMLInputElement> | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Handler that is called when text in the input is selected. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/select_event)."
+        },
+        "form": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+        },
+        "name": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+        },
+        "autoComplete": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
+        },
+        "maxLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The maximum number of characters supported by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefmaxlength)."
+        },
+        "minLength": {
+          "type": "number | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
+        },
+        "pattern": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Regex pattern that the value of the input must match to be valid. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern)."
+        },
+        "excludeFromTabOrder": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "aria",
+          "description": "Whether to exclude the element from the sequential tab order. If true,\nthe element will not be focusable via the keyboard by tabbing. This should\nbe avoided except in rare scenarios where an alternative means of accessing\nthe element or its functionality via the keyboard is available."
+        }
+      },
+      "propCounts": {
+        "own": 3,
+        "aria": 51,
+        "dom": 264,
+        "other": 2
+      }
+    },
     "SegmentedControl": {
       "name": "SegmentedControl",
       "source": "src/components/SegmentedControl.tsx",
@@ -11609,8 +13309,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": {
@@ -12737,13 +14437,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'"