ionbase-ui 0.86.0 → 0.88.0

package/dist/figma-map.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "figmaFile": "gaLbGd0QNb1fUl6BjSpfBA",
   "figmaExported": "2026-09-25",
   "usage": "Given a Figma node id or component name, look it up here for the React component, its import, and how each Figma property maps onto a real prop. Every mapping is verified against both the Figma export and the TypeScript API on each build.",
@@ -1260,6 +1260,35 @@
         }
       }
     },
+    "1510:666": {
+      "figmaComponent": "Multi Select",
+      "figmaNodeId": "1510:666",
+      "figmaPage": "Multi Select",
+      "component": "MultiSelect",
+      "import": "import { MultiSelect } from 'ionbase-ui';",
+      "docs": "components/multi-select/index.html.md",
+      "props": {
+        "Size": {
+          "prop": "size",
+          "values": {
+            "Small": "sm",
+            "Medium": "md",
+            "Large": "lg"
+          }
+        },
+        "State": {
+          "prop": "isInvalid",
+          "when": {
+            "Invalid": true
+          },
+          "note": "Hover, Focus and Filled are CSS or content; Disabled is isDisabled and Read-only is isReadOnly, and both hide the tags’ × buttons. The field is Combobox’s, which is Input’s box — the same split both record."
+        },
+        "Show Tags#1510:0": {
+          "prop": "hideTags",
+          "note": "Inverted: Show Tags off is `hideTags`, for a filter bar whose active-filters row already shows the values. With tags shown, they are the chosen `value`, labelled from `options`, and appear whenever something is chosen."
+        }
+      }
+    },
     "53:13": {
       "figmaComponent": "Nav Item",
       "figmaNodeId": "53:13",
@@ -2316,6 +2345,24 @@
         }
       }
     },
+    "1517:583": {
+      "figmaComponent": "Toolbar",
+      "figmaNodeId": "1517:583",
+      "figmaPage": "Toolbar",
+      "component": "Toolbar",
+      "import": "import { Toolbar } from 'ionbase-ui';",
+      "docs": "components/toolbar/index.html.md",
+      "props": {
+        "Orientation": {
+          "prop": "orientation",
+          "values": {
+            "Horizontal": "horizontal",
+            "Vertical": "vertical"
+          },
+          "note": "Horizontal moves with ← →, vertical with ↑ ↓. The children are the caller's: Buttons, a Divider between groups (vertical in a horizontal toolbar), and a MenuTrigger with an icon-only Button for the overflow. Name it with aria-label for what it acts on."
+        }
+      }
+    },
     "801:68": {
       "figmaComponent": "Tooltip",
       "figmaNodeId": "801:68",
@@ -3677,6 +3724,35 @@
         }
       }
     },
+    "Multi Select": {
+      "figmaComponent": "Multi Select",
+      "figmaNodeId": "1510:666",
+      "figmaPage": "Multi Select",
+      "component": "MultiSelect",
+      "import": "import { MultiSelect } from 'ionbase-ui';",
+      "docs": "components/multi-select/index.html.md",
+      "props": {
+        "Size": {
+          "prop": "size",
+          "values": {
+            "Small": "sm",
+            "Medium": "md",
+            "Large": "lg"
+          }
+        },
+        "State": {
+          "prop": "isInvalid",
+          "when": {
+            "Invalid": true
+          },
+          "note": "Hover, Focus and Filled are CSS or content; Disabled is isDisabled and Read-only is isReadOnly, and both hide the tags’ × buttons. The field is Combobox’s, which is Input’s box — the same split both record."
+        },
+        "Show Tags#1510:0": {
+          "prop": "hideTags",
+          "note": "Inverted: Show Tags off is `hideTags`, for a filter bar whose active-filters row already shows the values. With tags shown, they are the chosen `value`, labelled from `options`, and appear whenever something is chosen."
+        }
+      }
+    },
     "Nav Item": {
       "figmaComponent": "Nav Item",
       "figmaNodeId": "53:13",
@@ -4733,6 +4809,24 @@
         }
       }
     },
+    "Toolbar": {
+      "figmaComponent": "Toolbar",
+      "figmaNodeId": "1517:583",
+      "figmaPage": "Toolbar",
+      "component": "Toolbar",
+      "import": "import { Toolbar } from 'ionbase-ui';",
+      "docs": "components/toolbar/index.html.md",
+      "props": {
+        "Orientation": {
+          "prop": "orientation",
+          "values": {
+            "Horizontal": "horizontal",
+            "Vertical": "vertical"
+          },
+          "note": "Horizontal moves with ← →, vertical with ↑ ↓. The children are the caller's: Buttons, a Divider between groups (vertical in a horizontal toolbar), and a MenuTrigger with an icon-only Button for the overflow. Name it with aria-label for what it acts on."
+        }
+      }
+    },
     "Tooltip": {
       "figmaComponent": "Tooltip",
       "figmaNodeId": "801:68",
@@ -4855,7 +4949,8 @@
     "Screen Frame": "The frame FullCard draws around its media slot. The component owns it, so there is nothing for a caller to place.",
     "Side Menu Item": "A 32-tall side-navigation row on the Side Menu page, which predates Sidebar. It shared the name Menu Item with the real one (82:217) until 25 Sep 2026, and because the export keyed on the name it silently replaced it — the mapping, the gates and the Dev Mode block all pointed here. Sidebar Item is the side-navigation row code ships.",
     "Side Menu Section Title": "The section heading of the same pre-Sidebar side menu. Menu Section Title (1468:271) is the menu's own, drawn on the Menu page; Sidebar Section is the side navigation's.",
-    "Table/Cell Text": "TableCell covers Figma's Table Cell and Cell Text together; the two are never used apart in the design. Recorded in TableCell's contract."
+    "Table/Cell Text": "TableCell covers Figma's Table Cell and Cell Text together; the two are never used apart in the design. Recorded in TableCell's contract.",
+    "Multi Select Menu": "The list MultiSelect opens, with a check on each row. Not a separate export, for Combobox Menu's reason: the list and the field are one control, and a listbox with nothing to own it is not a thing a caller should be able to mount. Drawn separately because a frame cannot both hug a field and overlay a list."
   },
   "codeUnmapped": {
     "DateRangePicker": "Drawn, but not as a set of its own: its field is Date Picker Type=Range and its calendar is Calendar Mode=Range. A Figma set maps to exactly one code component, and splitting one field into two sets to satisfy that would draw the same box twice. Read Date Picker’s Type note for the handoff.",

package/dist/meta/CheckboxGroup.json

@@ -17,8 +17,8 @@
     },
     {
       "when": "the options are many, or space is tight",
-      "use": "Select",
-      "why": "past about seven options a list of boxes is longer than the form around it"
+      "use": "MultiSelect",
+      "why": "past about seven options a list of boxes is longer than the form around it; MultiSelect filters them and shows the chosen ones as tags"
     },
     {
       "when": "there is one on/off choice",

package/dist/meta/Combobox.json

@@ -17,6 +17,11 @@
       "use": "Select",
       "why": "the native control brings keyboard handling and the mobile platform picker for free; this rebuilds all of it"
     },
+    {
+      "when": "more than one value may be picked",
+      "use": "MultiSelect",
+      "why": "its input holds only the filter text, the list stays open between picks, and the chosen values show as tags"
+    },
     {
       "when": "there are two or three mutually exclusive choices worth showing at once",
       "use": "RadioGroup"
@@ -58,6 +63,9 @@
     "requires": [
       "`label`, or an `aria-label` when no visible label is rendered",
       "`emptyLabel` wording that says why nothing is listed, if the default is too terse"
+    ],
+    "notes": [
+      "While the list is open, React Aria hides everything outside the field and the list from assistive technology. That is the platform pattern for a combobox; a whole-page accessibility scan taken with the list open reports the hidden page, not this control."
     ]
   },
   "antiPatterns": [

package/dist/meta/MultiSelect.json

@@ -0,0 +1,269 @@
+{
+  "name": "MultiSelect",
+  "source": "src/components/MultiSelect.tsx",
+  "propsType": "MultiSelectProps",
+  "description": "MultiSelect — a text field that filters a list, with any number of selected\nvalues shown as removable tags beneath it.\n\nWHY IT IS ITS OWN COMPONENT, NOT `Combobox selectionMode=\"multiple\"`\n\nThe two differ in what the field holds. Combobox's input shows the chosen\nlabel — typing edits the value. Here the input only ever holds the filter\ntext, the value lives in the tags, and choosing an option leaves the list\nopen for the next one. One prop switching the meaning of the text in the\nbox is the kind of contract agents get wrong in generated code.\n\nWHAT REACT ARIA GIVES IT\n\n`useComboBoxState` and `useComboBox` in `selectionMode: 'multiple'`: the\nlistbox is `aria-multiselectable`, Enter and click toggle an option without\nclosing the list, the filter text clears after each pick, and native\n`required` is set only while nothing is chosen — \"at least one\", the same\nrule CheckboxGroup enforces.\n\nWHAT IT ADDS\n\n  - The tags. A TagGroup under the field, named by the field's label, one\n    tab stop, Delete or the × to remove. The selection must be visible with\n    the list closed, and \"3 selected\" hides which three.\n  - The value is announced with the field. React Aria points the input's\n    `aria-describedby` at a value element; this fills it with the chosen\n    labels joined by `Intl.ListFormat`, so \"Billing, Legal and Ops\" is read\n    in the user's language with no string shipped for it.\n  - Backspace in an empty field removes the last value, which is what\n    every tag input on the web has taught people to expect.\n  - Focus lands back in the field when the last tag is removed, instead of\n    falling to <body> with the TagGroup that held it.",
+  "import": "import { MultiSelect } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A text field that filters a list, with any number of values chosen. The choices show as removable tags beneath the field and are read with it.",
+  "useWhen": [
+    "the user picks several values from a list too long to show as checkboxes — teams, regions, labels, assignees",
+    "a table filter can match more than one value — \"Status is Failing or Paused\""
+  ],
+  "useInstead": [
+    {
+      "when": "exactly one value is picked",
+      "use": "Combobox",
+      "why": "Combobox's input shows the chosen label; here the input only ever holds the filter text, and the list stays open for the next pick"
+    },
+    {
+      "when": "there are about seven options or fewer",
+      "use": "CheckboxGroup",
+      "why": "every option visible at once beats typing to find one, and nothing is hidden behind a popover"
+    },
+    {
+      "when": "the values are free text the user invents, not options from a list",
+      "use": "TagGroup",
+      "why": "MultiSelect only chooses from `options`; a free-text tag input is a TagGroup beside an Input"
+    }
+  ],
+  "composition": {
+    "order": [
+      "MultiSelect"
+    ],
+    "note": "Pass the full `options` list; filtering, the tags and the announcement are the component's. In a table's filter bar, give it `aria-label` and `hideTags`, and list its values in the table's active-filters TagGroup — one removable tag per value, not the same tags twice.",
+    "example": "<MultiSelect label=\"Notify teams\" options={teams} value={teamIds} onChange={setTeamIds} placeholder=\"Search teams\" />"
+  },
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "dense forms, table filters"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "prominent single-field forms"
+      }
+    }
+  },
+  "slots": {
+    "label": {
+      "accepts": "text",
+      "note": "names the field and the tags beneath it"
+    },
+    "description": {
+      "accepts": "text",
+      "note": "replaced by `errorMessage` while `isInvalid` is set"
+    },
+    "errorMessage": {
+      "accepts": "text",
+      "note": "shown only while `isInvalid` is set"
+    },
+    "emptyLabel": {
+      "accepts": "text",
+      "note": "shown in the list when the filter matches nothing"
+    }
+  },
+  "a11y": {
+    "role": "combobox, controlling a listbox that is aria-multiselectable",
+    "guarantees": [
+      "React Aria's multi-select combobox: arrow keys move through the list while focus stays in the input, Enter or click toggles an option, and the list stays open for the next pick",
+      "the chosen labels are on the input's `aria-describedby`, joined by `Intl.ListFormat` — read with the field in the user's language, with no string shipped for it",
+      "the chosen values are a TagGroup named by the field's label: one tab stop, arrow keys between tags, Delete or the × to remove",
+      "Backspace in an empty field removes the last value; with text in the field it only edits the text",
+      "removing the last tag returns focus to the field instead of dropping it on <body>",
+      "`isRequired` marks the field required only while nothing is chosen — at least one"
+    ],
+    "requires": [
+      "`label`, or `aria-label` when there is no visible label — it names the tags as well as the field"
+    ],
+    "notes": [
+      "While the list is open, React Aria hides everything outside the field and the list from assistive technology, the tags included. That is the platform pattern for a combobox, not a defect: the chosen options are marked selected in the list itself."
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a Combobox that appends each pick to a TagGroup by hand",
+      "why": "the list closes after every pick, the input shows the last label, and nothing announces what is chosen"
+    },
+    {
+      "dont": "a native <select multiple>",
+      "why": "it needs Ctrl or Cmd to pick a second option, which most people never discover, and it cannot filter"
+    },
+    {
+      "dont": "a count in place of the values — \"3 selected\"",
+      "why": "it hides which three; the tags show them and the field reads them"
+    },
+    {
+      "dont": "`hideTags` with nowhere else showing the values",
+      "why": "the field shows only the filter text, so the choice is invisible until the list is opened"
+    }
+  ],
+  "stylesheet": "src/styles/multi-select.css",
+  "tokens": [
+    "--border-disabled",
+    "--border-primary-strong",
+    "--border-stronger",
+    "--border-width-default",
+    "--border-width-thick",
+    "--font-weight-regular",
+    "--icon-on-color",
+    "--ion-shadow-raised-flush-xs",
+    "--radius-xs",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--surface-hover",
+    "--surface-primary",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "options": {
+      "type": "readonly ComboboxOption[]",
+      "required": true,
+      "origin": "own",
+      "description": "The full option list. Filtering happens here, against what is typed."
+    },
+    "label": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Field label. Required for a usable control — see `a11y.requires`."
+    },
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the field, and its tags, when there is no visible `label`."
+    },
+    "description": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Helper text below the field."
+    },
+    "errorMessage": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Replaces the helper text when `isInvalid` is set."
+    },
+    "isInvalid": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isReadOnly": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "isRequired": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "At least one value must be chosen."
+    },
+    "size": {
+      "type": "MultiSelectSize | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Matches Input's `Size` variant: Small, Medium, Large.",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "placeholder": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "value": {
+      "type": "readonly string[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The selected values (controlled), in the order they were chosen."
+    },
+    "defaultValue": {
+      "type": "readonly string[] | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "The initially selected values (uncontrolled)."
+    },
+    "onChange": {
+      "type": "((value: string[]) => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Receives the whole new selection."
+    },
+    "inputValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled filter text. Usually only needed for remote filtering."
+    },
+    "onInputChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "hideTags": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Leave the tags out, when the chosen values are already on screen as\nremovable tags — a table's active-filters row. The values are still read\nwith the field, and still marked in the list."
+    },
+    "emptyLabel": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Shown in place of the list when nothing matches."
+    },
+    "buttonLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible label for the disclosure button."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Posts every selected value under this name, for an uncontrolled form."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the field box (`.ion-input`)."
+    },
+    "wrapperClassName": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the `.ion-field` wrapper."
+    },
+    "id": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 23,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}

package/dist/meta/Select.json

@@ -27,7 +27,8 @@
     },
     {
       "when": "the user may pick more than one",
-      "use": "Checkbox"
+      "use": "MultiSelect",
+      "why": "a native <select multiple> needs Ctrl or Cmd for a second pick and cannot filter; for a handful of options use CheckboxGroup"
     }
   ],
   "variants": {

package/dist/meta/Toolbar.json

@@ -0,0 +1,130 @@
+{
+  "name": "Toolbar",
+  "source": "src/components/Toolbar.tsx",
+  "propsType": "ToolbarProps",
+  "description": "Toolbar — a row of controls that act on one thing, reached as one stop.\n\nReact Aria's `useToolbar` gives it `role=\"toolbar\"` and `aria-orientation`,\narrow keys between its controls (mirrored in right-to-left), Tab that leaves\nthe whole toolbar rather than walking every button, and focus returned to the\ncontrol used last when Tab brings the user back. A toolbar inside a toolbar\nbecomes a `group`, so nesting one for grouping is safe.\n\nEvery control keeps its own tab stop in the DOM — React Aria moves focus to\nthe first or last control on Tab and lets the browser take it from there —\nso nothing here rewrites a child's `tabIndex`, and a control that mounts\nlater (the bulk actions appearing on selection) needs no registration.\n\nWHAT IT IS NOT FOR\n\nA filter bar. Tab leaves a toolbar in one press, so a search field inside one\nstrands the filters after it: Tab skips them and ← → belong to the caret.\nThat is WAI-ARIA's own caution about text fields in toolbars. A table's\nsearch and filters stay ordinary tab stops; the toolbar is the row of\nactions — the batch bar, a record's actions, an editor's formatting.",
+  "import": "import { Toolbar } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A row of controls that act on one thing, reached as one tab stop: arrow keys between the controls, Tab out in one press, and back to the control used last.",
+  "useWhen": [
+    "a set of actions on one selection or one record — the batch bar over a table, a run's Resume/Pause/Stop, an editor's formatting",
+    "the row has enough controls that tabbing through each one costs a keyboard user more than it gives"
+  ],
+  "useInstead": [
+    {
+      "when": "the row holds a search field or filters",
+      "use": "a plain flex row",
+      "why": "Tab leaves a toolbar in one press and ← → belong to the caret, so a text field inside strands every filter after it — WAI-ARIA's own caution"
+    },
+    {
+      "when": "two or three actions at the top of a page",
+      "use": "PageHeader",
+      "why": "its `actions` slot is a row of ordinary tab stops, which for a few buttons is what a keyboard user expects"
+    },
+    {
+      "when": "the controls are one choice among options",
+      "use": "SegmentedControl",
+      "why": "that is a radio group with a selected value; a toolbar holds independent actions"
+    }
+  ],
+  "composition": {
+    "order": [
+      "Toolbar",
+      "Button",
+      "Divider",
+      "MenuTrigger"
+    ],
+    "note": "Buttons in the order they are read, a vertical Divider between groups, and a MenuTrigger with an icon-only Button last for the overflow. Name it with `aria-label` for what it acts on — \"Bulk actions\", not \"Toolbar\".",
+    "example": "<Toolbar aria-label=\"Bulk actions\"><Button size=\"sm\" variant=\"secondary\">Pause</Button><Divider orientation=\"vertical\" /><Button size=\"sm\" variant=\"destructive\">Delete 3</Button></Toolbar>"
+  },
+  "variants": {
+    "orientation": {
+      "horizontal": {
+        "use": "the default — ← → move between controls; wraps rather than overflowing"
+      },
+      "vertical": {
+        "use": "a side rail of tools — ↑ ↓ move between controls"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "Button, MenuTrigger, SegmentedControl, Divider, Toolbar",
+      "note": "a nested Toolbar becomes a named `group`, and the outer toolbar keeps the arrow keys"
+    }
+  },
+  "a11y": {
+    "role": "toolbar, with aria-orientation",
+    "guarantees": [
+      "React Aria's `useToolbar`: arrow keys move between controls, skipping disabled ones and separators, and are mirrored in right-to-left",
+      "Tab leaves the whole toolbar in one press, and Shift+Tab or Tab back in returns to the control used last",
+      "a text field, native select, combobox, slider or radio inside keeps its own arrow keys — the caret moves and the value changes instead of focus jumping",
+      "↓ still reaches a MenuTrigger in a horizontal toolbar, so an overflow menu opens as it does anywhere else"
+    ],
+    "requires": [
+      "`aria-label` or `aria-labelledby` naming what the toolbar acts on"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a table's search field and filters inside a Toolbar",
+      "why": "Tab from the search field leaves the toolbar, so the filters after it can only be reached by Shift+Tab and arrows"
+    },
+    {
+      "dont": "a Toolbar with one button",
+      "why": "a single stop gains nothing from arrow keys, and screen readers announce a toolbar the user has to learn"
+    },
+    {
+      "dont": "an unnamed Toolbar",
+      "why": "\"toolbar\" alone does not say what the buttons act on, and pages with two cannot be told apart"
+    }
+  ],
+  "stylesheet": "src/styles/toolbar.css",
+  "tokens": [
+    "--spacing-4",
+    "--spacing-8"
+  ],
+  "props": {
+    "aria-label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Names the toolbar — \"Bulk actions\", \"Formatting\". Required, or `aria-labelledby`.",
+      "tags": {
+        "see": "aria-labelledby."
+      }
+    },
+    "aria-labelledby": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Identifies the element (or elements) that labels the current element.",
+      "tags": {
+        "see": "aria-describedby."
+      }
+    },
+    "orientation": {
+      "type": "ToolbarOrientation | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Which arrow keys move between controls. Horizontal: ← →; vertical: ↑ ↓.",
+      "values": [
+        "vertical",
+        "horizontal"
+      ],
+      "default": "horizontal"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Buttons, MenuTriggers, a SegmentedControl, and a vertical Divider between groups."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 274,
+    "other": 0
+  }
+}