ionbase-ui 0.81.1 → 0.86.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
+  }
+}

package/dist/meta/PageHeader.json

@@ -0,0 +1,169 @@
+{
+  "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
+  }
+}

package/dist/meta/Radio.json

@@ -91,7 +91,6 @@
     "--border-width-default",
     "--border-width-thick",
     "--font-family-sans",
-    "--font-weight-medium",
     "--icon-disabled",
     "--icon-on-color",
     "--ion-duration-base",

package/dist/meta/RadioGroup.json

@@ -2,10 +2,10 @@
   "name": "RadioGroup",
   "source": "src/components/Radio.tsx",
   "propsType": "RadioGroupProps",
-  "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.",
+  "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.\n\nThe fieldset itself is Fieldset's shell, shared with CheckboxGroup, so the\ntwo choice groups take the same label, help, error and orientation props.",
   "import": "import { RadioGroup } from 'ionbase-ui';",
   "status": "stable",
-  "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value.",
+  "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value, and the group's label, help and error.",
   "useWhen": [
     "exactly one choice from a small set, all worth showing at once",
     "the options need explaining — each one can carry its own label text"
@@ -17,7 +17,7 @@
     },
     {
       "when": "more than one may be picked",
-      "use": "Checkbox"
+      "use": "CheckboxGroup"
     },
     {
       "when": "there are exactly two states and the change is immediate",
@@ -46,6 +46,14 @@
       "danger": {
         "use": "a set where the options are destructive"
       }
+    },
+    "orientation": {
+      "vertical": {
+        "use": "the default, and always when a label runs past a few words"
+      },
+      "horizontal": {
+        "use": "two to four one-word options. Wraps rather than overflows"
+      }
     }
   },
   "slots": {
@@ -53,6 +61,14 @@
       "accepts": "text",
       "note": "renders as the <legend> — the question the options answer"
     },
+    "description": {
+      "accepts": "text",
+      "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
+    },
+    "errorMessage": {
+      "accepts": "text",
+      "note": "shown only while `isInvalid` is set"
+    },
     "children": {
       "accepts": "Radio"
     }
@@ -62,7 +78,10 @@
     "guarantees": [
       "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
       "`name` is generated when omitted, so two groups on one page never collide",
-      "`isDisabled` cascades to every Radio that has not set its own"
+      "`isDisabled` cascades to every Radio that has not set its own",
+      "the fieldset is Fieldset's shell, shared with CheckboxGroup — the same label, help, error and orientation props",
+      "the description or error is on every radio's `aria-describedby` as well as the fieldset's, so it is read on the radio that takes focus",
+      "`isRequired` is native `required` on the radios, which the platform already reads as \"one of this name\""
     ],
     "requires": [
       "`label`, or `aria-label` when the question is already visible elsewhere"
@@ -99,7 +118,6 @@
     "--border-width-default",
     "--border-width-thick",
     "--font-family-sans",
-    "--font-weight-medium",
     "--icon-disabled",
     "--icon-on-color",
     "--ion-duration-base",
@@ -159,7 +177,41 @@
     "label": {
       "type": "React.ReactNode",
       "required": false,
-      "origin": "own"
+      "origin": "own",
+      "description": "The question the options answer. Renders as the `<legend>`."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
+    },
+    "errorMessage": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Shown in the description's place while `isInvalid` is set."
+    },
+    "isInvalid": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Shows `errorMessage` in the description's place."
+    },
+    "isRequired": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "One option must be chosen before the form submits."
+    },
+    "orientation": {
+      "type": "FieldsetOrientation | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "vertical",
+        "horizontal"
+      ]
     },
     "size": {
       "type": "RadioSize | undefined",
@@ -202,7 +254,7 @@
     }
   },
   "propCounts": {
-    "own": 10,
+    "own": 15,
     "aria": 0,
     "dom": 276,
     "other": 0