ionbase-ui 0.81.0 → 0.84.0

package/dist/meta/MenuItem.json

@@ -2,11 +2,12 @@
   "name": "MenuItem",
   "source": "src/components/Menu.tsx",
   "propsType": "MenuItemProps",
+  "description": "One row of a Menu. A collection element, like TabItem: it renders nothing\nitself — Menu reads its props and draws the row — so it only means anything\nas a direct child of Menu or MenuSection. Give it a `key`; that key is what\n`onAction` and `selectedKeys` speak in.",
   "import": "import { MenuItem } from 'ionbase-ui';",
   "status": "stable",
-  "summary": "One row in a Menu. A real <button> inside an <li>, with an optional leading icon and a trailing selected check.",
+  "summary": "One row of a Menu. A collection element: Menu reads its props and draws the row as `menuitem`, `menuitemradio` or `menuitemcheckbox`.",
   "useWhen": [
-    "a row in a Menu surface"
+    "a row in a Menu or a MenuSection — it is not usable anywhere else"
   ],
   "useInstead": [
     {
@@ -18,6 +19,14 @@
       "use": "Button"
     }
   ],
+  "composition": {
+    "order": [
+      "Menu",
+      "MenuItem"
+    ],
+    "note": "A collection element, like TabItem: it renders nothing itself and never appears in the DOM. `key` identifies it to Menu's `onAction`, `selectedKeys` and `disabledKeys`.",
+    "example": "<MenuItem key=\"duplicate\" icon={<Icon as={Copy} />}>Duplicate</MenuItem>\n<MenuItem key=\"move\" title=\"Move to\"><MenuItem key=\"archive\">Archive</MenuItem></MenuItem>"
+  },
   "slots": {
     "icon": {
       "accepts": "Icon",
@@ -26,37 +35,50 @@
     "children": {
       "accepts": "text",
       "note": "the row label"
+    },
+    "title": {
+      "accepts": "text",
+      "note": "only on a row that opens a submenu: the row's label, while its children are the submenu's MenuItems. Submenus open only inside a MenuTrigger"
     }
   },
   "a11y": {
-    "role": "button",
     "guarantees": [
-      "`isSelected` sets `aria-pressed`, so the selected state is announced and not only drawn",
-      "the check glyph always occupies its slot, so rows never reflow as the selection moves"
+      "the role, `aria-checked` and `aria-disabled` are supplied by Menu from its selection mode and keys, not by this element",
+      "the check glyph occupies its slot whenever the menu has a selection mode, so rows never reflow as the selection moves"
     ],
     "requires": [
-      "a text label in `children`"
+      "a stable `key`",
+      "text in `children`, or `textValue` when the children are not plain text — typeahead matches against it"
     ]
   },
   "antiPatterns": [
     {
       "dont": "using MenuItem outside a Menu",
-      "why": "it renders an <li>, which is only valid inside a list"
+      "why": "it renders nothing on its own"
     },
     {
       "dont": "an icon-only MenuItem with no children",
-      "why": "the row announces nothing"
+      "why": "the row announces nothing and typeahead cannot reach it"
+    },
+    {
+      "dont": "array indexes as keys in a list that can change",
+      "why": "selection and actions are expressed in keys, so the selected row silently becomes a different row"
     }
   ],
   "deprecated": [
     {
       "prop": "disabled",
       "replacement": "isDisabled"
+    },
+    {
+      "prop": "isSelected",
+      "note": "Put the item's key in Menu's `selectedKeys` and set its `selectionMode`."
     }
   ],
   "stylesheet": "src/styles/menu.css",
   "tokens": [
     "--border-focus",
+    "--border-strong",
     "--border-subtle",
     "--border-width-default",
     "--border-width-thick",
@@ -68,10 +90,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",
@@ -81,15 +106,18 @@
     "--text-disabled",
     "--text-primary",
     "--text-secondary",
+    "--text-tertiary",
     "--type-body",
-    "--type-body-line-height"
+    "--type-body-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
   ],
   "props": {
-    "isSelected": {
-      "type": "boolean | undefined",
+    "title": {
+      "type": "React.ReactNode",
       "required": false,
       "origin": "own",
-      "description": "Figma's `Selected` / `Selected-hover` states. Shows the trailing check."
+      "description": "Only on a row that opens a submenu: the row's label. Its children are then\nthe submenu's MenuItems rather than its label. Submenus open only inside a\nMenuTrigger — a standalone Menu has nothing to open them from."
     },
     "icon": {
       "type": "React.ReactNode",
@@ -101,7 +129,7 @@
       "type": "boolean | undefined",
       "required": false,
       "origin": "own",
-      "description": "Whether the item is disabled."
+      "description": "Whether the item is disabled. Listed, skipped by the arrow keys."
     },
     "disabled": {
       "type": "boolean | undefined",
@@ -111,16 +139,108 @@
         "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
       }
     },
+    "isSelected": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Put the item's key in Menu's `selectedKeys`. Accepted for one\nminor version: when no item's key is in `selectedKeys` and Menu is given\nneither `selectedKeys` nor `defaultSelectedKeys`, the items passing this\nbecome the selection."
+      }
+    },
     "children": {
-      "type": "React.ReactNode",
+      "type": "ReactNode",
+      "required": true,
+      "origin": "aria",
+      "description": "Rendered contents of the item or child items."
+    },
+    "textValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A string representation of the item's contents, used for features like typeahead."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "An accessibility label for this item."
+    },
+    "childItems": {
+      "type": "Iterable<T> | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A list of child item objects. Used for dynamic collections."
+    },
+    "hasChildItems": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Whether this item has children, even if not loaded yet."
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A URL to link to. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href)."
+    },
+    "hrefLang": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Hints at the human language of the linked URL.\nSee[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#hreflang)."
+    },
+    "target": {
+      "type": "HTMLAttributeAnchorTarget | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The target window for the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target)."
+    },
+    "rel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The relationship between the linked resource and the current page. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel)."
+    },
+    "download": {
+      "type": "string | boolean | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "Causes the browser to download the linked URL. A string may be provided to suggest a file name.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download)."
+    },
+    "ping": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "A space-separated list of URLs to ping when the link is followed. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#ping)."
+    },
+    "referrerPolicy": {
+      "type": "HTMLAttributeReferrerPolicy | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "How much of the referrer to send when following the link. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#referrerpolicy).",
+      "values": [
+        "",
+        "origin",
+        "no-referrer",
+        "no-referrer-when-downgrade",
+        "origin-when-cross-origin",
+        "same-origin",
+        "strict-origin",
+        "strict-origin-when-cross-origin",
+        "unsafe-url"
+      ]
+    },
+    "routerOptions": {
+      "type": "undefined",
       "required": false,
-      "origin": "own"
+      "origin": "aria",
+      "description": "Options for the configured client side router."
     }
   },
   "propCounts": {
     "own": 5,
-    "aria": 0,
-    "dom": 285,
+    "aria": 13,
+    "dom": 0,
     "other": 0
   }
 }

package/dist/meta/MenuSection.json

@@ -0,0 +1,90 @@
+{
+  "name": "MenuSection",
+  "source": "../../node_modules/.pnpm/react-stately@3.48.0_react@19.2.8/node_modules/react-stately/dist/types/src/collections/Section.d.ts",
+  "propsType": null,
+  "import": "import { MenuSection } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A named group of MenuItems. Re-exported from react-stately's collection Section — `title` is Figma's Menu Section Title.",
+  "useWhen": [
+    "a Menu has more than one kind of action, such as editing actions and destructive ones",
+    "the rows fall into groups the user scans by name"
+  ],
+  "useInstead": [
+    {
+      "when": "the menu has one group",
+      "use": "MenuItem",
+      "why": "a single section adds a heading the user must hear before every menu, and says nothing the menu's own label does not"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Menu",
+      "MenuSection",
+      "MenuItem"
+    ],
+    "note": "A collection element: Menu reads it from its direct children. With `title`, the heading is drawn with a rule after it; without one, `aria-label` names the group and a rule is drawn above it instead.",
+    "example": "<MenuSection title=\"Sort by\"><MenuItem key=\"name\">Name</MenuItem><MenuItem key=\"updated\">Last updated</MenuItem></MenuSection>"
+  },
+  "a11y": {
+    "role": "group",
+    "guarantees": [
+      "the group is named by its title, so a screen reader announces it on entering the first row"
+    ],
+    "requires": [
+      "a `title`; an untitled section still needs a label for the group, or it is announced as an unnamed group"
+    ],
+    "notes": [
+      "The accessible-name lint rule is deliberately not driven from here: a titled section is named by its title and needs nothing more, so demanding a label on every MenuSection would be wrong for the common case."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "nesting a MenuSection inside another",
+      "why": "a menu has one level of grouping; a section inside a section renders nothing"
+    }
+  ],
+  "stylesheet": "src/styles/menu.css",
+  "tokens": [
+    "--border-focus",
+    "--border-strong",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-regular",
+    "--icon-default",
+    "--icon-disabled",
+    "--icon-primary",
+    "--icon-size-sm",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-menu-min-width",
+    "--ion-shadow-shadow-lg",
+    "--radius-sm",
+    "--radius-xl",
+    "--spacing-12",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-40",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-primary-subtle",
+    "--text-disabled",
+    "--text-primary",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {},
+  "propCounts": {
+    "own": 0,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/MenuTrigger.json

@@ -0,0 +1,177 @@
+{
+  "name": "MenuTrigger",
+  "source": "src/components/Menu.tsx",
+  "propsType": "MenuTriggerProps",
+  "description": "MenuTrigger — a Button that opens a Menu.\n\nThe \"⋯\" overflow menu is this with an icon-only Button; there is no separate\ncomponent for it, because the only difference is the Button's content and\nits required aria-label.\n\n`useMenuTrigger` does what a Popover wrapped round a Menu could not: the\ntrigger announces `aria-haspopup=\"menu\"` and `aria-expanded`, the menu is\nnamed by the trigger, ArrowDown and ArrowUp open it with focus on the first\nor last row, and choosing an action closes it and returns focus to the\ntrigger.",
+  "import": "import { MenuTrigger } from 'ionbase-ui';",
+  "status": "stable",
+  "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 button opens a list of actions — row actions, an overflow \"⋯\", a \"New\" button with several kinds of new",
+    "a button opens a list of choices applied immediately, such as a sort order",
+    "the actions nest one level or more — submenus open only inside a MenuTrigger"
+  ],
+  "useInstead": [
+    {
+      "when": "the 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": "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": {
+    "children": {
+      "accepts": [
+        "Button",
+        "Menu"
+      ],
+      "note": "the Button first, the Menu second"
+    }
+  },
+  "a11y": {
+    "role": "none — the Button gets aria-haspopup=\"menu\" and aria-expanded; the Menu is the menu",
+    "namesChild": true,
+    "guarantees": [
+      "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": [
+      "an icon-only trigger Button needs its own aria-label — it names the menu too"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "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": "a plain <button> as the trigger",
+      "why": "the trigger must accept react-aria press props and a ref; IonBase's Button does, a DOM button silently never opens"
+    },
+    {
+      "dont": "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",
+    "--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": {
+    "children": {
+      "type": "[React.ReactElement<unknown, string | React.JSXElementConstructor<any>>, React.ReactElement<unknown, string | React.JSXElementConstructor<any>>]",
+      "required": true,
+      "origin": "own",
+      "description": "Exactly two children: the Button that opens the menu, then the Menu. The\nButton must accept a ref and react-aria press props — IonBase's Button\ndoes; a plain `<button>` does not."
+    },
+    "placement": {
+      "type": "MenuTriggerPlacement | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Where the menu opens, relative to the trigger. A preference, not a\nguarantee: it flips when there is no room.",
+      "values": [
+        "bottom start",
+        "bottom end",
+        "top start",
+        "top end"
+      ]
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Whether the trigger is disabled."
+    },
+    "isOpen": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "defaultOpen": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onOpenChange": {
+      "type": "((isOpen: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}