ionbase-ui 0.81.1 → 0.84.0

package/dist/meta/components.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.81.1",
+  "version": "0.84.0",
   "generated": "by scripts/build-meta.mjs — do not edit; intent lives in meta/*.json",
   "hooks": [
     "useAgentRun",
@@ -7046,65 +7046,575 @@
       "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 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)."
         },
-        {
-          "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"
+        "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": "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",
@@ -7116,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",
@@ -7129,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",
@@ -7216,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",
@@ -7229,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
       }
     },
@@ -8063,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",