ionbase-ui 0.81.0 → 0.84.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.81.0",
+  "version": "0.84.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useAgentRun",
@@ -4181,7 +4181,8 @@
           "every day cell carries the full date as its accessible name in the reader's own language, so the narrow weekday headers are never load-bearing",
           "unavailable and disabled days are distinguished visually and in the accessible name, not by colour alone",
           "today is marked with a dot rather than a ring, so it cannot be mistaken for a second selected day",
-          "the selected fill and the segment focus box are redeclared under forced-colors, where background-color is discarded"
+          "the selected fill and the segment focus box are redeclared under forced-colors, where background-color is discarded",
+          "a typed date outside `minValue`/`maxValue` turns the field invalid and names the bound in the reader's own format, without `isInvalid` — the value is kept, not silently clamped"
         ],
         "requires": [
           "`label`, or an `aria-label` when no visible label is rendered",
@@ -4289,7 +4290,7 @@
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Replaces the helper text when `isInvalid` is set."
+          "description": "Replaces the helper text while the field is invalid — `isInvalid`, or its own bounds check."
         },
         "isInvalid": {
           "type": "boolean | undefined",
@@ -4444,7 +4445,8 @@
           "preset rows are buttons in a labelled group carrying aria-pressed, so 'which shortcut is active' is answerable without seeing the tint",
           "the selected preset is marked by weight as well as by background, so it does not rely on colour alone",
           "range endpoints and the band between them keep their fill under forced-colors, where background-color is otherwise discarded",
-          "the rail stacks above the grids below 32rem rather than being hidden, because shortcuts matter most on the device where dragging across two months is worst"
+          "the rail stacks above the grids below 32rem rather than being hidden, because shortcuts matter most on the device where dragging across two months is worst",
+          "a typed date outside `minValue`/`maxValue`, or an end before the start, turns the field invalid with React Aria's localized message, without `isInvalid` — the value is kept, not silently clamped"
         ],
         "requires": [
           "`label`, or an `aria-label` when no visible label is rendered",
@@ -4545,7 +4547,7 @@
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Replaces the helper text when `isInvalid` is set."
+          "description": "Replaces the helper text while the field is invalid — `isInvalid`, or its own bounds check."
         },
         "isInvalid": {
           "type": "boolean | undefined",
@@ -7022,87 +7024,597 @@
           "required": false,
           "origin": "own",
           "values": [
-            "sm",
-            "lg"
+            "sm",
+            "lg"
+          ]
+        },
+        "label": {
+          "type": "string | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Accessible name for the mark used standalone. Omit when it sits beside\na visible wordmark, which already carries the name."
+        }
+      },
+      "propCounts": {
+        "own": 2,
+        "aria": 0,
+        "dom": 487,
+        "other": 0
+      }
+    },
+    "Menu": {
+      "name": "Menu",
+      "source": "src/components/Menu.tsx",
+      "propsType": "MenuProps",
+      "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": "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": [
+        "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": "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 for a form field from a modest list of plain text options",
+          "use": "Select",
+          "why": "a form value is a listbox, not a menu; the native picker brings type-ahead and the mobile platform picker for free"
+        },
+        {
+          "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"
+        ],
+        "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",
+            "MenuSection"
+          ]
+        }
+      },
+      "a11y": {
+        "role": "menu",
+        "guarantees": [
+          "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": [
+          "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": "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 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",
+        "--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": {
+        "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": 2,
+        "aria": 18,
+        "dom": 0,
+        "other": 0
+      }
+    },
+    "MenuItem": {
+      "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 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 or a MenuSection — it is not usable anywhere else"
+      ],
+      "useInstead": [
+        {
+          "when": "it is a top-level navigation destination",
+          "use": "NavItem"
+        },
+        {
+          "when": "it is a standalone action outside a list",
+          "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",
+          "note": "leading icon; omit its `label` — the row's text names it"
+        },
+        "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": {
+        "guarantees": [
+          "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 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 nothing on its own"
+        },
+        {
+          "dont": "an icon-only MenuItem with no children",
+          "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",
+        "--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": {
+        "title": {
+          "type": "React.ReactNode",
+          "required": false,
+          "origin": "own",
+          "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",
+          "required": false,
+          "origin": "own",
+          "description": "Figma's `Show Leading Icon` + `Leading Icon` swap."
+        },
+        "isDisabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "description": "Whether the item is disabled. Listed, skipped by the arrow keys."
+        },
+        "disabled": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own",
+          "tags": {
+            "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": "ReactNode",
+          "required": true,
+          "origin": "aria",
+          "description": "Rendered contents of the item or child items."
+        },
+        "textValue": {
+          "type": "string | undefined",
+          "required": false,
+          "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"
           ]
         },
-        "label": {
-          "type": "string | undefined",
+        "routerOptions": {
+          "type": "undefined",
           "required": false,
-          "origin": "own",
-          "description": "Accessible name for the mark used standalone. Omit when it sits beside\na visible wordmark, which already carries the name."
+          "origin": "aria",
+          "description": "Options for the configured client side router."
         }
       },
       "propCounts": {
-        "own": 2,
-        "aria": 0,
-        "dom": 487,
+        "own": 5,
+        "aria": 13,
+        "dom": 0,
         "other": 0
       }
     },
-    "Menu": {
-      "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.",
-      "import": "import { Menu } from 'ionbase-ui';",
+    "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": "The list surface only — no trigger, no anchor, no open state. Positioning it is the caller's job.",
+      "summary": "A named group of MenuItems. Re-exported from react-stately's collection Section — `title` is Figma's Menu Section Title.",
       "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 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": "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": "one value is picked 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"
-        },
-        {
-          "when": "it is primary navigation rather than a dropdown",
-          "use": "NavItem"
+          "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"
         ],
-        "example": "<Menu><MenuItem icon={<Icon as={Copy} />}>Duplicate</MenuItem><MenuItem isSelected>Archive</MenuItem></Menu>"
-      },
-      "slots": {
-        "children": {
-          "accepts": "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": "none — it is a plain <ul>",
+        "role": "group",
         "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"
+          "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": [
-          "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."
+          "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": "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": "using Menu as a dropdown without positioning it",
-          "why": "it renders in flow — it has no anchor logic of its own"
+          "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",
@@ -7114,10 +7626,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",
@@ -7127,82 +7642,116 @@
         "--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",
-          "required": false,
-          "origin": "own"
-        }
-      },
+      "props": {},
       "propCounts": {
-        "own": 1,
+        "own": 0,
         "aria": 0,
-        "dom": 277,
+        "dom": 0,
         "other": 0
       }
     },
-    "MenuItem": {
-      "name": "MenuItem",
+    "MenuTrigger": {
+      "name": "MenuTrigger",
       "source": "src/components/Menu.tsx",
-      "propsType": "MenuItemProps",
-      "import": "import { MenuItem } from 'ionbase-ui';",
+      "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",
-      "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+      "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": [
-        "a row in a Menu surface"
+        "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": "it is a top-level navigation destination",
-          "use": "NavItem"
+          "when": "the button opens a form, a filter panel or anything that is not a list of rows",
+          "use": "Popover",
+          "why": "a menu promises arrow keys between rows and nothing else; a field inside it cannot be reached"
         },
         {
-          "when": "it is a standalone action outside a list",
-          "use": "Button"
+          "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": {
+        "placement": {
+          "bottom start": {
+            "use": "the default — below, aligned to the trigger's start edge"
+          },
+          "bottom end": {
+            "use": "a trigger at the end of a row or toolbar, so the menu does not run off the edge"
+          },
+          "top start": {
+            "use": "a trigger near the bottom of the viewport, such as a footer"
+          },
+          "top end": {
+            "use": "as top start, for a trigger at the end of its row"
+          }
+        }
+      },
       "slots": {
-        "icon": {
-          "accepts": "Icon",
-          "note": "leading icon; omit its `label` — the row's text names it"
-        },
         "children": {
-          "accepts": "text",
-          "note": "the row label"
+          "accepts": [
+            "Button",
+            "Menu"
+          ],
+          "note": "the Button first, the Menu second"
         }
       },
       "a11y": {
-        "role": "button",
+        "role": "none — the Button gets aria-haspopup=\"menu\" and aria-expanded; the Menu is the menu",
+        "namesChild": true,
         "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"
+          "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": [
-          "a text label in `children`"
+          "an icon-only trigger Button needs its own aria-label — it names the menu too"
         ]
       },
       "antiPatterns": [
         {
-          "dont": "using MenuItem outside a Menu",
-          "why": "it renders an <li>, which is only valid inside a list"
+          "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": "an icon-only MenuItem with no children",
-          "why": "the row announces nothing"
-        }
-      ],
-      "deprecated": [
+          "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"
+        },
         {
-          "prop": "disabled",
-          "replacement": "isDisabled"
+          "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/menu.css",
       "tokens": [
         "--border-focus",
+        "--border-strong",
         "--border-subtle",
         "--border-width-default",
         "--border-width-thick",
@@ -7214,10 +7763,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",
@@ -7227,46 +7779,57 @@
         "--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",
-          "required": false,
+        "children": {
+          "type": "[React.ReactElement<unknown, string | React.JSXElementConstructor<any>>, React.ReactElement<unknown, string | React.JSXElementConstructor<any>>]",
+          "required": true,
           "origin": "own",
-          "description": "Figma's `Selected` / `Selected-hover` states. Shows the trailing check."
+          "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."
         },
-        "icon": {
-          "type": "React.ReactNode",
+        "placement": {
+          "type": "MenuTriggerPlacement | undefined",
           "required": false,
           "origin": "own",
-          "description": "Figma's `Show Leading Icon` + `Leading Icon` swap."
+          "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 item is disabled."
+          "description": "Whether the trigger is disabled."
         },
-        "disabled": {
+        "isOpen": {
           "type": "boolean | undefined",
           "required": false,
-          "origin": "own",
-          "tags": {
-            "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-          }
+          "origin": "own"
         },
-        "children": {
-          "type": "React.ReactNode",
+        "defaultOpen": {
+          "type": "boolean | undefined",
+          "required": false,
+          "origin": "own"
+        },
+        "onOpenChange": {
+          "type": "((isOpen: boolean) => void) | undefined",
           "required": false,
           "origin": "own"
         }
       },
       "propCounts": {
-        "own": 5,
+        "own": 6,
         "aria": 0,
-        "dom": 285,
+        "dom": 0,
         "other": 0
       }
     },
@@ -8061,6 +8624,175 @@
         "other": 2
       }
     },
+    "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": "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": [
+        "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": "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": "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": "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"
+        }
+      ],
+      "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"
+        },
+        "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": "none — a <div>. The page's landmark is <main>, named by this title",
+        "guarantees": [
+          "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"
+        ],
+        "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": [
+        {
+          "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"
+        },
+        {
+          "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"
+        },
+        {
+          "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/page-header.css",
+      "tokens": [
+        "--font-family-sans",
+        "--font-weight-semibold",
+        "--ion-page-header-heading-basis",
+        "--spacing-16",
+        "--spacing-4",
+        "--spacing-8",
+        "--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",
@@ -13746,7 +14478,7 @@
           "type": "React.ReactNode",
           "required": false,
           "origin": "own",
-          "description": "Replaces the helper text when `isInvalid` is set."
+          "description": "Replaces the helper text while the field is invalid — `isInvalid`, or its own bounds check."
         },
         "isInvalid": {
           "type": "boolean | undefined",