ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/Accordion.json

@@ -0,0 +1,123 @@
+{
+  "name": "Accordion",
+  "source": "src/components/Accordion.tsx",
+  "propsType": "AccordionProps",
+  "description": "Accordion — sections that collapse, with the heading structure intact.\n\nWHY THE TRIGGER IS A BUTTON INSIDE A HEADING\n\nBoth parts are load-bearing and the obvious implementations drop one of them.\nThe heading is how a screen-reader user navigates a long page — pressing `h`\nmoves between sections, and an accordion built from `div`s removes every one\nof those stops. The button is what makes the section operable by keyboard and\nannounced as expandable; a heading with a click handler is neither.\n\nSo the shape is `<h3><button aria-expanded aria-controls>`, which is the only\narrangement that keeps document structure AND operability.\n\n`headingLevel` is a prop with no safe default beyond 3, because the right\nlevel depends on the document around it and nothing here can see that. Two\naccordions at the wrong level produce a page whose outline is nonsense while\nlooking perfectly fine.\n\nTHE PANEL IS NOT UNMOUNTED\n\nCollapsed sections keep their DOM and are hidden with `hidden`. Unmounting\nwould lose form state in a collapsed section — the classic multi-step-form\nbug where answers vanish when a section is folded away — and would break\nin-page search, which cannot find text that is not there.",
+  "import": "import { Accordion } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Sections that collapse, with the document's heading structure intact. Holds the open set and the heading level.",
+  "useWhen": [
+    "a page has several long sections and most users need one of them",
+    "optional or advanced settings should be present but not in the way",
+    "an FAQ or a reference list where scanning titles is the primary action"
+  ],
+  "useInstead": [
+    {
+      "when": "the sections are alternatives and only one is ever relevant",
+      "use": "Tabs",
+      "why": "tabs say \"pick one\"; an accordion says \"all of these exist, open what you need\""
+    },
+    {
+      "when": "hiding the content would hide something the user must act on",
+      "use": "render it directly",
+      "why": "a required field inside a collapsed section is a form that cannot be completed without exploration"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "AccordionItem"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`headingLevel` that fits the surrounding document — the default of 3 is a guess this component cannot verify"
+    ],
+    "notes": [
+      "each section's trigger is a button inside a heading, which is the only arrangement that keeps both document structure and operability",
+      "collapsed panels are hidden rather than unmounted, so form state survives and in-page search still finds the text"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "allowsMultiple on a long FAQ",
+      "do": "leave it off, so opening one section closes the last",
+      "why": "with every section openable at once the page has no maximum height, and a user who opens six is scrolling a wall of text looking for the one they wanted. Reach for it when sections are settings or reference material a user may need to compare side by side"
+    },
+    {
+      "dont": "headingLevel left at 3 inside a section already under an h4",
+      "do": "headingLevel={5}",
+      "why": "the page looks correct and its outline is nonsense — a heading-level jump is invisible to sighted users and disorienting to everyone navigating by headings"
+    },
+    {
+      "dont": "an accordion holding a single section",
+      "do": "a heading and the content",
+      "why": "one collapsible section is a control that exists to hide the only thing on screen"
+    }
+  ],
+  "stylesheet": "src/styles/accordion.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-disabled",
+    "--icon-secondary",
+    "--icon-size-md",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-4",
+    "--text-default",
+    "--text-disabled",
+    "--text-primary",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "allowsMultiple": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Let more than one section be open at once."
+    },
+    "defaultExpandedKeys": {
+      "type": "string[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled: which sections start open."
+    },
+    "expandedKeys": {
+      "type": "string[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled: which sections are open. Pass `onExpandedChange` with it."
+    },
+    "onExpandedChange": {
+      "type": "((keys: string[]) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "headingLevel": {
+      "type": "AccordionHeadingLevel | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The level each section's heading renders at. Must fit the surrounding\ndocument — a panel inside an `h2` section wants `3`."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 6,
+    "aria": 0,
+    "dom": 276,
+    "other": 0
+  }
+}

package/dist/meta/AccordionItem.json

@@ -0,0 +1,90 @@
+{
+  "name": "AccordionItem",
+  "source": "src/components/Accordion.tsx",
+  "propsType": "AccordionItemProps",
+  "import": "import { AccordionItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One collapsible section: an always-visible title that toggles a region beneath it.",
+  "useWhen": [
+    "inside an Accordion, once per section"
+  ],
+  "slots": {
+    "title": {
+      "accepts": "text",
+      "note": "always visible, so it must say what is inside — \"Advanced\" tells the user nothing about whether to open it"
+    },
+    "children": {
+      "accepts": "any content"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "a stable `id`, which is the section's identity in the open set — an index breaks the moment the list reorders"
+    ],
+    "notes": [
+      "the trigger carries aria-expanded and aria-controls; the panel is a region labelled by the trigger",
+      "the panel keeps its DOM when collapsed, so a half-filled form inside one does not lose its answers"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a required form field inside a collapsed section",
+      "do": "keep required fields outside, or expand the section when validation fails",
+      "why": "a user cannot fix an error they cannot see, and the browser cannot focus a hidden invalid field"
+    }
+  ],
+  "stylesheet": "src/styles/accordion.css",
+  "tokens": [
+    "--border-focus",
+    "--border-subtle",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-disabled",
+    "--icon-secondary",
+    "--icon-size-md",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-4",
+    "--text-default",
+    "--text-disabled",
+    "--text-primary",
+    "--text-secondary",
+    "--type-body",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "id": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "Stable identity for the open set. Required."
+    },
+    "title": {
+      "type": "React.ReactNode",
+      "required": true,
+      "origin": "own",
+      "description": "The always-visible label."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 275,
+    "other": 0
+  }
+}

package/dist/meta/AgentActivityStep.json

@@ -43,8 +43,8 @@
       "note": "the step in plain language"
     },
     "detail": {
-      "accepts": "text",
-      "note": "the result, a count, a tool name — whatever makes the step checkable"
+      "accepts": "text, ToolCall, ApprovalGate",
+      "note": "the result, a count, a tool name — whatever makes the step checkable. Block content is valid here: a ToolCall as evidence under the step, or the ApprovalGate the step is waiting on"
     }
   },
   "a11y": {

package/dist/meta/Breadcrumb.json

@@ -0,0 +1,87 @@
+{
+  "name": "Breadcrumb",
+  "source": "src/components/Breadcrumb.tsx",
+  "propsType": "BreadcrumbProps",
+  "description": "Breadcrumb — where this page sits, and how to get back up.\n\nWHY AN ORDERED LIST INSIDE A NAMED LANDMARK\n\nThe trail is a sequence, and `ol` is what says so: a screen reader announces\n\"list, 4 items\" and the position within it, which is the entire content of a\nbreadcrumb. A row of `div`s with slashes conveys none of that, and the\nslashes themselves get read out as punctuation.\n\nThe separator here is drawn by CSS `::before` on each item after the first,\nso it is decoration that never enters the accessibility tree. Putting a \"/\"\nin the markup is the usual version of this component and the usual defect.\n\nTHE LAST CRUMB IS NOT A LINK\n\n`isCurrent` renders text with `aria-current=\"page\"`. A link to the page you\nare already on is a dead control: it announces as a link, invites a click,\nand does nothing. This is the most common breadcrumb bug and the reason the\nprop exists rather than being inferred from position — a trail whose last\ncrumb IS a link to somewhere else is legitimate, and inferring would break it.",
+  "import": "import { Breadcrumb } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Where this page sits in the hierarchy, and how to get back up. An ordered list inside a named landmark.",
+  "useWhen": [
+    "a page sits more than one level deep and the parent is not otherwise reachable",
+    "a record view needs its collection one click away",
+    "the hierarchy itself is information the user needs — which project, which environment"
+  ],
+  "useInstead": [
+    {
+      "when": "the destinations are siblings rather than ancestors",
+      "use": "Tabs",
+      "why": "a breadcrumb describes depth; tabs describe alternatives at the same depth"
+    },
+    {
+      "when": "the trail is the primary navigation for the whole app",
+      "use": "NavItem inside the app shell",
+      "why": "a breadcrumb supplements navigation, it does not replace it — it appears after a user has already gone somewhere"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "BreadcrumbItem",
+      "note": "ancestor first, current page last. Anything else and the trail reads backwards"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` when a page has more than one nav landmark — it defaults to \"Breadcrumb\", which is what screen-reader users listen for"
+    ],
+    "notes": [
+      "the separator is drawn by CSS ::before and never enters the accessibility tree; a \"/\" in the markup is announced as punctuation between every crumb",
+      "the list is an `ol`, so the position and length are announced — which is the entire content of a breadcrumb"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<div>Home / Projects / Invoice 12</div>",
+      "do": "<Breadcrumb><BreadcrumbItem href=\"/\">Home</BreadcrumbItem>…</Breadcrumb>",
+      "why": "a row of divs conveys neither sequence nor position, and the slashes are read aloud"
+    },
+    {
+      "dont": "a full trail on a top-level page",
+      "do": "omit it",
+      "why": "a breadcrumb with one crumb is furniture — it takes vertical space to say nothing"
+    }
+  ],
+  "stylesheet": "src/styles/breadcrumb.css",
+  "tokens": [
+    "--border-focus",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--radius-xs",
+    "--spacing-8",
+    "--text-default",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the landmark. A page with more than one `nav` needs them told apart,\nand \"Breadcrumb\" is what screen-reader users are listening for."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`BreadcrumbItem` elements, ancestor first."
+    }
+  },
+  "propCounts": {
+    "own": 2,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/BreadcrumbItem.json

@@ -0,0 +1,78 @@
+{
+  "name": "BreadcrumbItem",
+  "source": "src/components/Breadcrumb.tsx",
+  "propsType": "BreadcrumbItemProps",
+  "import": "import { BreadcrumbItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One crumb. A link to an ancestor, or the current page rendered as text.",
+  "useWhen": [
+    "inside a Breadcrumb, once per level"
+  ],
+  "useInstead": [
+    {
+      "when": "outside a breadcrumb trail",
+      "use": "Link",
+      "why": "the crumb's density, colour and truncation are tuned for a trail and look wrong on their own"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the name of the level, not its path"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`isCurrent` on the last crumb, which renders it as text with aria-current=\"page\" rather than as a link"
+    ],
+    "notes": [
+      "isCurrent is a prop rather than inferred from position: a trail whose last crumb legitimately links elsewhere exists, and inferring would break it"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<BreadcrumbItem href=\"/invoices/12\">Invoice 12</BreadcrumbItem> for the page you are on",
+      "do": "<BreadcrumbItem isCurrent>Invoice 12</BreadcrumbItem>",
+      "why": "a link to the current page is a dead control — it announces as a link, invites a click and does nothing"
+    }
+  ],
+  "stylesheet": "src/styles/breadcrumb.css",
+  "tokens": [
+    "--border-focus",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--radius-xs",
+    "--spacing-8",
+    "--text-default",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Omit on the current page — the last crumb is not a link."
+    },
+    "isCurrent": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The page the user is on. Marked `aria-current=\"page\"` and rendered as text\nrather than a link."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 3,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Checkbox.json

@@ -78,6 +78,11 @@
     {
       "dont": "a div with `role=\"checkbox\"`",
       "why": "form association, the indeterminate property and label clicking are not free to reimplement"
+    },
+    {
+      "dont": "<Checkbox isSelected={on} onChange={(isSelected) => setOn(isSelected)} />",
+      "do": "<Checkbox isSelected={on} onSelectionChange={setOn} />",
+      "why": "both selection shapes work, but they pair: `isSelected` goes with `onSelectionChange`, which receives the boolean, and `checked` goes with `onChange`, which receives the change event. Passing the Aria selection prop with the DOM handler name is the one combination that does not type — `onChange` is still the event handler. There is no `CheckboxChange` type; a generated eval invented one."
     }
   ],
   "deprecated": [
@@ -184,10 +189,22 @@
       "required": false,
       "origin": "own",
       "description": "Figma's `Show Label` + `Label`. Omit for a bare box."
+    },
+    "isSelected": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "React Aria's name for `checked`. Wins when both are passed."
+    },
+    "onSelectionChange": {
+      "type": "((isSelected: boolean) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Receives the new selection state rather than the change event."
     }
   },
   "propCounts": {
-    "own": 6,
+    "own": 8,
     "aria": 0,
     "dom": 304,
     "other": 0