@stackone/malachite 2.105.1 → 2.107.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/COMPONENTS.md +3 -3
- package/dist/components/FilterSearch.js +392 -355
- package/dist/components/FilterSearch.js.map +1 -1
- package/dist/components/FilterSearchPanel.js +167 -0
- package/dist/components/FilterSearchPanel.js.map +1 -0
- package/dist/components/SegmentedControl.js +25 -23
- package/dist/components/SegmentedControl.js.map +1 -1
- package/dist/components/SidePanel.js +145 -126
- package/dist/components/SidePanel.js.map +1 -1
- package/dist/components/SidePanelTabs.js +32 -0
- package/dist/components/SidePanelTabs.js.map +1 -0
- package/dist/components/TabStrip.js +81 -0
- package/dist/components/TabStrip.js.map +1 -0
- package/dist/components/Tabs.js +8 -78
- package/dist/components/Tabs.js.map +1 -1
- package/dist/components/filterSearchModel.js +32 -31
- package/dist/components/filterSearchModel.js.map +1 -1
- package/dist/components/sidePanelTabsContext.js +6 -0
- package/dist/components/sidePanelTabsContext.js.map +1 -0
- package/dist/components/useTabStripAndPanels.js +56 -0
- package/dist/components/useTabStripAndPanels.js.map +1 -0
- package/dist/index.d.ts +25 -6
- package/dist/tailwind.css.js +1 -1
- package/package.json +1 -1
package/COMPONENTS.md
CHANGED
|
@@ -29,7 +29,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
|
|
|
29
29
|
- **`ActionBar`** — A row of actions that collapses into a single `ActionMenu` once its container drops below `collapseBelow`. Measures the nearest genuinely-wider ancestor rather than itself, since the row shrinks to its own content. `dividerBefore` renders a vertical rule in the row and a divider in the collapsed menu, so both forms group the actions the same way. _Key props:_ `buttons` (`label`, `onClick`, `icon`, `variant`, `size`, `radius`, `tooltip`, `disabled`, `dividerBefore`), `collapseBelow`, `menuLabel`, `className`.
|
|
30
30
|
- **`Popover`** — An anchored, non-modal panel for arbitrary content — a workspace switcher, an org flyout. The panel renders in its own shadow root, so malachite components inside it are styled, and joins the top layer like the other overlays. It prefers its `placement` and flips to the opposite side when there is no room, clamping along the other axis. Click-opened panels take focus and hand it back to the trigger on close; `openOn="hover"` also opens on focus and stays open while the pointer or focus is in the panel. A nested Popover counts as inside its parent for outside-press and hover dismissal, and Escape closes the topmost only. A click panel also closes when focus moves somewhere outside it and its trigger, and on close it hands focus back to the trigger only if focus would otherwise fall to the page. _Key props:_ `trigger`, `children`, `open`, `defaultOpen`, `onOpenChange`, `placement` (`bottom-start` | `bottom-end` | `top-start` | `top-end` | `top-center` | `right-start` | `right-end` | `left-start`), `openOn` (`click` | `hover`), `width` (`content` | `trigger`), `padding` (`none` | `small` | `medium`), `anchorRef` (position against another element, e.g. the section a trigger row sits in), `offset` (`small` 8px | `medium` 12px | `large` 14px), `elevation` (`default` | `raised`), `initialFocus` (a ref, or a function read when the panel is shown, for what takes focus in place of the first focusable; it is read again as the panel's content changes, so focus follows content that mounts late or a focused element that is removed, but never leaves an element the user moved to; `initialFocusRef` is its deprecated form, read on open only), `openOnArrowKey` (a click panel also opens, focus inside, on the arrow key its placement points at — ArrowDown for a `bottom-*` placement; a text field trigger keeps its arrow keys), `role` (`dialog` | `menu` | `listbox`; `menu` brings no roving focus of its own), `aria-label` or `aria-labelledby` (one is required), `className`. The panel is capped to the viewport width, and only overlays opened from inside it (menus, dropdowns, modals) count as inside for outside-press dismissal. A side placement stays level with its anchor and scrolls within the room below, sliding up only when under 160px is left. Parts for the panel body: `Popover.Header` (`title`, `action`, `divider` — `false` drops the rule and sits it 4px over the list, as its label), `Popover.Action` (`icon`, `aria-label`, `onClick`, `href` (a link that opens in a new tab on Cmd/Ctrl-click or a middle click; a plain click runs `onClick` when one is given), `disabled`, `tooltip`), `Popover.List` (a scrolling list; `scrollToSelected` scrolls the list, never the page, to its selected row, one marked `aria-current`, `aria-selected` or a checked radio, each time the popover is shown, once that row mounts), `Popover.Section` (a bordered section), `Popover.Empty` (an empty-state line), `Popover.Search` (pads a `Search` above the list without a second rule), `Popover.Note` (a footnote section in small secondary text) and `Popover.Status` (`message`, `tone` (`default` | `error`), `action` (`label`, `onClick`, `pending`), `focusable`): one `status` live region for the panel's life, announcing each message it is given and staying mounted, visually hidden, while there is none, so clear `message` rather than unmounting it. Errors announce through the same region. `focusable` with a ref makes it an `initialFocus` target; resolve to it only while it has a message, since an empty one is invisible. Reach for `Status` when the message changes while the panel is open or carries an action (loading, failed, sign-in needed), and `Empty` for a static line in a list that simply has nothing in it.
|
|
31
31
|
- **`Modal`** — Centred dialog over a scrim, with header slots (icon/title/subtitle/extra), a scrolling body and a pinned footer. Locks background scroll and dismisses on ESC, the close button, or a scrim click unless `closeOnOverlayClick` is off; `busy` suppresses the two pointer routes while a request is in flight and sets `aria-busy`, so a stray click cannot tear the dialog down mid-write — but never ESC, which is the only guaranteed keyboard exit from a focus trap and so always reaches `onClose`. ESC, the Tab focus trap and `aria-modal` all apply to the topmost overlay only, so these may be stacked — a dialog opened from a panel keeps Tab to itself and the panel stops claiming to be modal. The Tab trap follows focus into a malachite popup portaled out of the dialog’s own tree — a `MultiSelect` listbox or a `Popover` opened from the body — and traps Tab within that popup while it holds focus, so Tab walks and wraps that popup’s own stops rather than being yanked back to the dialog’s first control or escaping the dialog altogether. A `Dropdown` list or an `ActionMenu` is dismissed by Tab rather than trapping it: it closes and focus returns to its trigger, so Tab carries on from there. A consumer’s own portaled popup is not known to the trap and Tab will pull focus out of it. Set `role="alertdialog"` for a consequential choice, which asks assistive tech to announce the body and not just the name, and point `aria-describedby` at whichever element carries it. Width comes from the `size` union (`small` 420px | `medium` 612px | `large` 760px | `fullscreen`, which fills the window in both directions) rather than a raw pixel prop. `titleAdornment` sits immediately after the title behind a hairline divider, for naming the thing being acted on — distinct from `headerExtra`, which pins to the far right. `tray` paints a tinted plate around the card and hangs a `caption` beneath it; the plate is the dialog element itself, so that caption stays inside the `aria-modal` subtree rather than being stranded outside it by the visual nesting, and it is added to `aria-describedby` automatically because it says what the dialog is asking. It takes a tone (`neutral` | `warning` | `error` | `success`) rather than a colour, so no consumer can paint it off-palette — and the tone sets the plate and its caption colour together, so the two cannot disagree. The caption is a `{ label?, message }` pair rather than a node, because its row height, type scale and colour belong to the plate. `size` names the card, and the plate’s 4px ring is added on top. Like `SidePanel` it sits in a z-index band from 1000 — one step per stacked overlay, so what paints on top is what holds the keyboard — and stays out of the browser top layer, so a host app’s own dialogs can still cover it. `callouts` stacks full-bleed `Alert` bands at the top of the body, as on `SidePanel`; they ignore `bodyPadding` and lead `aria-describedby`, ahead of the consumer’s own description and the tray caption. For a confirmation use `ConfirmationDialog`, which is a preset over this. _Key props:_ `open`, `onClose`, `title`, `subtitle`, `icon`, `headerExtra`, `titleAdornment`, `tray`, `callouts`, `renderLink`, `headerDivider`, `footer`, `size`, `showCloseButton`, `closeOnOverlayClick`, `bodyPadding`, `bodyHeight` (`auto` | `tall` — 600px, or the viewport less 160px when smaller, for an embedded iframe at `height: 100%`), `busy`, `role` (`dialog` | `alertdialog`), `aria-label`, `aria-labelledby`, `aria-describedby`.
|
|
32
|
-
- **`SidePanel`** — Right-hand slide-in overlay panel (drawer) with header slots (back/icon/title/subtitle/extra), scrollable body and optional footer. `subtitlePlacement="below"` stacks the subtitle on its own line under the title row, so neither truncates the other in a narrow panel. `toolbar` pins content between the header and the scrolling body (16px sides, 16px above, 8px below, no divider), such as a Search over the list it filters. Locks background scroll and dismisses on ESC, an overlay click or close. ESC and the Tab focus trap apply to the topmost overlay only, so a `Modal` may be stacked over it. The Tab trap follows focus into a malachite popup portaled out of the panel’s own tree — a `MultiSelect` listbox or a `Popover` opened from the body — and traps Tab within that popup while it holds focus, so Tab walks and wraps that popup’s own stops rather than being yanked back to the panel’s first control or escaping the panel altogether. A `Dropdown` list or an `ActionMenu` is dismissed by Tab rather than trapping it: it closes and focus returns to its trigger, so Tab carries on from there. A consumer’s own portaled popup is not known to the trap and Tab will pull focus out of it. `callouts` stacks full-bleed `Alert` bands at the top of the body, above `children` and unaffected by `bodyPadding` — the same band `ConfirmationDialog` gives its `callout` — and `renderLink` routes their root-relative markdown links through the app’s router. The callouts are announced as the panel’s description, ahead of `description`. `aside` opens a full-height column to the left, as wide again as `maxWidth`, for help that sits beside the content — a setup guide beside a form. The panel’s own header, body and footer keep their width and place, and the aside’s `title` (with an optional `headerExtra`, such as a `Stepper`) and `footer` line up with the panel’s header and footer; `bodyPadding` works as the panel’s does. The aside is never narrower than 360px, so a window too narrow for both columns scrolls the panel sideways. `onSubmit` makes the header, body and footer one `<form>` (`noValidate`, default prevented), so Enter in a field submits through a `type="submit"` footer button, as `FormActions` gives, the way a browser form does: not from a textarea, not mid-composition, and not while that button is disabled. Enter in the `toolbar` never submits, and the submit does not reach a form the panel is rendered inside.
|
|
32
|
+
- **`SidePanel`** — Right-hand slide-in overlay panel (drawer) with header slots (back/icon/title/subtitle/extra), scrollable body and optional footer. `subtitlePlacement="below"` stacks the subtitle on its own line under the title row, so neither truncates the other in a narrow panel. `toolbar` pins content between the header and the scrolling body (16px sides, 16px above, 8px below, no divider), such as a Search over the list it filters. `toolbarPadding="body"` insets it 28px either side instead, level with the body, for a full-width row such as a `KeyValueStrip`. `SidePanel.Tabs`, rendered anywhere in the body, pins its `Tabs` strip under the header and toolbar (arrow keys open the tab they reach), always inset by the panel’s 28px gutter (with `bodyPadding={false}`, pad the panels 28px to line them up), and keeps its panels where it sits, so a child that owns its tabs needs no plumbing; panels mount the first time their tab opens and stay mounted, hidden, until it unmounts, each tab reopens at the scroll position it was left at, and a tabbed body keeps a stable scrollbar gutter so tabs of any length line up. Outside a `SidePanel` it renders as `Tabs`. Locks background scroll and dismisses on ESC, an overlay click or close. ESC and the Tab focus trap apply to the topmost overlay only, so a `Modal` may be stacked over it. The Tab trap follows focus into a malachite popup portaled out of the panel’s own tree — a `MultiSelect` listbox or a `Popover` opened from the body — and traps Tab within that popup while it holds focus, so Tab walks and wraps that popup’s own stops rather than being yanked back to the panel’s first control or escaping the panel altogether. A `Dropdown` list or an `ActionMenu` is dismissed by Tab rather than trapping it: it closes and focus returns to its trigger, so Tab carries on from there. A consumer’s own portaled popup is not known to the trap and Tab will pull focus out of it. `callouts` stacks full-bleed `Alert` bands at the top of the body, above `children` and unaffected by `bodyPadding` — the same band `ConfirmationDialog` gives its `callout` — and `renderLink` routes their root-relative markdown links through the app’s router. The callouts are announced as the panel’s description, ahead of `description`. `aside` opens a full-height column to the left, as wide again as `maxWidth`, for help that sits beside the content — a setup guide beside a form. The panel’s own header, body and footer keep their width and place, and the aside’s `title` (with an optional `headerExtra`, such as a `Stepper`) and `footer` line up with the panel’s header and footer; `bodyPadding` works as the panel’s does. The aside is never narrower than 360px, so a window too narrow for both columns scrolls the panel sideways. `onSubmit` makes the header, body and footer one `<form>` (`noValidate`, default prevented), so Enter in a field submits through a `type="submit"` footer button, as `FormActions` gives, the way a browser form does: not from a textarea, not mid-composition, and not while that button is disabled. Enter in the `toolbar` never submits, and the submit does not reach a form the panel is rendered inside.
|
|
33
33
|
- **`useHasOpenOverlay`** — Hook reporting whether any modal-type overlay - `SidePanel` or `Modal` - is open anywhere in the app. For host chrome that has to get out of an overlay’s way, a floating support widget being the case it was added for: overlays render through a portal, so a host has no DOM signal of its own to read, and reading the library’s internal markers would couple it to something it does not own. Dropdowns and tooltips are deliberately not counted - they do not trap focus, and chrome does not need to move for them. _Key props:_ No arguments. Returns a boolean.
|
|
34
34
|
- **`SidePanelNavFooter`** — Keyboard-hint footer for SidePanel: up/down keycaps to step between records, optional left/right keycaps to switch tabs, and an esc-to-close hint, with an optional right-aligned actions slot.
|
|
35
35
|
|
|
@@ -76,7 +76,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
|
|
|
76
76
|
- **`DatePicker`** — Picks one day, or one instant with `precision="minute"` or `"second"`, from Figma's calendar in a popover. Day precision commits on click; a time precision adds hour/minute(/second) columns and holds a draft until Apply, which Escape or an outside click discards. `timeZone="utc"` draws the UTC calendar day and suffixes times with "UTC" whatever the browser's zone, as the logs pages need. Values are `Date`s; ISO strings are accepted (a string without an offset, such as `2025-01-20` or `2025-01-20T10:00`, is read in `timeZone`), and a `formControl` field seeded with a string is written back as an ISO string. `min`/`max` bound the instant (days and times outside are disabled, as are month arrows and keyboard paging that would leave them; a value clamped up to `min` rounds up to the precision, so on `min`'s own day a day-precision value is `min` itself) and `isDateDisabled` rules out single days. The grid is an ARIA grid with a roving tab stop: arrows move by day and week, PageUp/PageDown by month (Shift for a year), Home/End to the week's ends, Enter or Space picks; every day of a range is `aria-selected`, and a hidden live line asks for the end date once the start is picked. The trigger sits on the 28/32/42 control ladder with Dropdown's chrome; `clearable` adds a clear control reported as `onChange(null)`. Colours come from `text`, `accent` and `card`, so a rebrand repaints the picker; the derived states (hover, outside-month text, selected fill, today ring, range band, pressed opacity) can each be overridden through the `datePicker` theme group (`applyTheme({ colors: { datePicker: { selectedBackground } } })`). _Key props:_ `value`, `defaultValue`, `onChange`, `precision` (`day` | `minute` | `second`), `minuteStep`, `timeZone` (`local` | `utc`), `weekStartsOn`, `min`, `max`, `isDateDisabled`, `presets`, `clearable`, `tag` (`{ label, type }` status beside the value), `tone` (`default` | `chosen` | `pending`, paint only), `placeholder`, `size`, `fullWidth`, `width`, `label`, `description`, `hint`, `tooltip`, `helperText`, `required`, `requiredIndicator`, `formControl`, `error`, `disabled`, `loading`, `id`, `aria-label`, `aria-labelledby`.
|
|
77
77
|
- **`DateRangePicker`** — `DatePicker`'s range form, with the same props and a `{ start, end }` value. The second click completes a day range; a click before the start restarts it. The end always covers the whole of its last unit (`23:59:59.999` for a picked day, the last millisecond of the picked minute or second), so a filter on the range keeps its final minutes. In a `formControl` field a cleared range writes `null`. With a time precision a Start/End switch picks which end the time columns edit, end times before the start are not offered, and Apply waits for both ends. `presets` list beside the calendar and apply at once; pass a function (`value: () => ({ start, end })`) for a relative preset such as "Past 1 hour", so it is measured when clicked rather than when the page loaded. _Key props:_ `value` / `defaultValue` (`{ start, end }`), `onChange`, `presets` (`DateRangePreset[]`), plus every `DatePicker` prop.
|
|
78
78
|
- **`MultiSelect`** — Multi-select dropdown. `width` fixes the trigger, as `Dropdown` and `Search` take it, so a toolbar can put its controls on one width — and, as with those two, a container narrower than the value still wins; the menu fills the trigger and left-aligns under it, so that one prop sizes both; `minWidth` raises the 160px floor a narrow trigger falls back to. An option label too long for the menu ellipsises, and hovering it shows the full label — above the description in `hover` mode — as `Dropdown` does for its options. `requiredIndicator` follows the same three-way convention the single-select controls do, so a form choosing asterisks does not get "(Optional)" on one of its fields. _Key props:_ `MultiSelectOption[]`, `MultiSelectSize`, `width`, `minWidth`, `label`, `searchable`, `inlineSearch`, `chips`, `chipsRemovable`, `required`, `requiredIndicator`, `aria-label`, `aria-labelledby`, `id`.
|
|
79
|
-
- **`FilterSearch`** — One search field that filters across several categories. Clicking lists the filters, each with its description and an example; picking one lists its values behind a `Filters > Name` breadcrumb, and typing before picking searches the values of every filter at once, tagging each match with the filter it belongs to. Select All / Deselect All act on whatever the query matches. Each filter becomes a segmented chip, its name then its values (`Connector | Notion, Attio +2`), that reopens its values when clicked; an item `icon` is drawn in its menu row and in the chip, and `chipLabel: false` on a filter drops its name from the chip (`Configured only`); Backspace in an empty field removes the last one. `onQueryChange` reports the text in the field, for analytics or a server-side search. With `textFilter` (`{ value, label }`, under a `value` no filter uses) the typed text is itself the first row while searching (`Search "acme"`); committing it adds a `Search: acme` chip whose selection is `{ filter: textFilter.value, items: [text] }`, replacing any earlier text, so a free-text search can sit in the URL beside the filters, and clicking that chip puts the text back in the field. Controlled: `onChange` gets the next selection and the `changes` that produced it, an empty `items` meaning the filter was removed, so a URL-backed selection writes back only what moved. Chips keep the order filters were added in even when `value` comes back reordered, and keep their labels while `filters` reloads. `filtersButton` puts a Filters button, with the applied count, at the right end of the bar that opens
|
|
79
|
+
- **`FilterSearch`** — One search field that filters across several categories. Clicking lists the filters, each with its description and an example; picking one lists its values behind a `Filters > Name` breadcrumb, and typing before picking searches the values of every filter at once, tagging each match with the filter it belongs to. Select All / Deselect All act on whatever the query matches. Each filter becomes a segmented chip, its name then its values (`Connector | Notion, Attio +2`), that reopens its values when clicked; an item `icon` is drawn in its menu row and in the chip, and `chipLabel: false` on a filter drops its name from the chip (`Configured only`); Backspace in an empty field removes the last one. `onQueryChange` reports the text in the field, for analytics or a server-side search. With `textFilter` (`{ value, label }`, under a `value` no filter uses) the typed text is itself the first row while searching (`Search "acme"`); committing it adds a `Search: acme` chip whose selection is `{ filter: textFilter.value, items: [text] }`, replacing any earlier text, so a free-text search can sit in the URL beside the filters, and clicking that chip puts the text back in the field. Controlled: `onChange` gets the next selection and the `changes` that produced it, an empty `items` meaning the filter was removed, so a URL-backed selection writes back only what moved. Chips keep the order filters were added in even when `value` comes back reordered, and keep their labels while `filters` reloads. `filtersButton` puts a Filters button, with the applied count, at the right end of the bar that opens a Filters panel beneath it: every filter at once, each drawn by its `control` (`list`, the default, a checkbox per value with an optional `count` badge and a search box past 8 values; `toggle`, a switch for the filter's one value; `segmented`, All plus one segment per value), applied as they change and mirrored as chips in the bar, with Clear all leaving the typed text alone. The button and the filter chips are then the only way to filters: the field is a plain search box (`role="searchbox"`) that never opens a menu, reports what is typed through `onQueryChange`, keeps it on blur and while the panel is open, and pins it as the `textFilter` chip on Enter. _Key props:_ `filters` (`control`, item `count`), `value`, `onChange`, `onClear`, `onActiveFilterChange`, `onQueryChange`, `textFilter`, `filtersButton`, `placeholder`, `size`, `width`, `loading`, `disabled`, `clearable`, `maxVisibleChips`, `aria-label`, `aria-labelledby`, `id`.
|
|
80
80
|
- **`QueryInput`** — A textbox with inline syntax colouring and a suggestion menu anchored to the caret. It carries no grammar of its own: the consumer parses the value, hands back `tokens` to colour and `suggestions` to offer, so the vocabulary lives in the consuming app rather than here. _Key props:_ `value`, `onChange`, `tokens`, `suggestions`, `activeRange`, `onAccept`, `onQueryContextChange`, `onSubmit`, `placeholder`, `size`, `disabled`, `loading`, `emptyMessage`, `className`, `style`, `aria-label`, `aria-labelledby`.
|
|
81
81
|
- **`SettingRow`** — One setting: a labelled row with its control on the trailing edge, and the sentence that explains it underneath. `control` may be a render prop receiving the label’s id, so a control that no `<label htmlFor>` can reach — `Toggle` renders a `<button role="switch">` — still names itself via `aria-labelledby`. _Key props:_ `label`, `badge`, `description`, `control`, `className`.
|
|
82
82
|
|
|
@@ -87,7 +87,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
|
|
|
87
87
|
- **`DefinitionRow`** — Row showing an icon, label, optional tag and description — for definition/detail lists. _Key props:_ `icon`, `label`, `tag`, `description`.
|
|
88
88
|
- **`PreviewTree`** — Nested, indented tree for previewing hierarchical structure.
|
|
89
89
|
- **`PreviewTreeRow`** — A single labelled row within a PreviewTree. _Key props:_ `label`.
|
|
90
|
-
- **`Tabs`** — Tabbed navigation switching between content panels. `trailing` puts content on the same row, settled against its end — a count, a scope picker, the state the tabs are showing — inside the rule this component already draws. Without it a consumer had to redraw that rule to carry it past the tabs, and the tab list, which cannot wrap, would not yield any width to what sat beside it. The tabs hold their width and the trailing content gives ground; the `tablist` role stays on the tabs alone, so the extra content is not announced as one. Give an item `content` and each tab gets a `tabpanel` below the strip, wired with `aria-controls` and `aria-labelledby`: a panel mounts the first time its tab opens and then stays mounted, hidden, so a search, a filter or a scroll position survives a round trip and its data is not fetched again. `destroyInactivePanels` unmounts a panel when its tab is left instead. Panels have no overflow of their own, so a sticky toolbar inside one still pins to the page. Leave `content` off every item and the strip is all it renders. _Key props:_ `TabItem[]` (`key`, `label`, `disabled`, `content`), `activeKey`, `onChange`, `trailing`, `destroyInactivePanels`, `className`, `style`.
|
|
90
|
+
- **`Tabs`** — Tabbed navigation switching between content panels. ArrowLeft and ArrowRight on a focused tab move focus to the next enabled tab, wrapping at the ends, and Home and End to the first and last; Enter, Space or a click opens it, or `activation="automatic"` opens the tab an arrow reaches. ArrowUp, ArrowDown and any key with Alt, Ctrl or Cmd held are left to the page. `trailing` puts content on the same row, settled against its end — a count, a scope picker, the state the tabs are showing — inside the rule this component already draws. Without it a consumer had to redraw that rule to carry it past the tabs, and the tab list, which cannot wrap, would not yield any width to what sat beside it. The tabs hold their width and the trailing content gives ground; the `tablist` role stays on the tabs alone, so the extra content is not announced as one. Give an item `content` and each tab gets a `tabpanel` below the strip, wired with `aria-controls` and `aria-labelledby`: a panel mounts the first time its tab opens and then stays mounted, hidden, so a search, a filter or a scroll position survives a round trip and its data is not fetched again. `destroyInactivePanels` unmounts a panel when its tab is left instead. Panels have no overflow of their own, so a sticky toolbar inside one still pins to the page. Leave `content` off every item and the strip is all it renders. _Key props:_ `TabItem[]` (`key`, `label`, `disabled`, `content`), `activeKey`, `onChange`, `trailing`, `destroyInactivePanels`, `activation` (`manual` | `automatic`), `className`, `style`.
|
|
91
91
|
- **`Breadcrumbs`** — Breadcrumb trail with caret separators, an optional back button (shown only when there is more than one crumb AND the parent — the second-to-last — carries a `url` to target) and a right-aligned `actions` row. A lone crumb marked `isRoot` switches to title mode: plain emphasised text, no trail chrome, but the `actions` row still renders. Renders as a `nav`/`ol` with `aria-current="page"` on the last crumb. Pass `renderLink` to route crumbs through the app's own router instead of a plain `<a>`. Used by `PageLayout`, but standalone too. _Key props:_ `links[]` (`name`, `url`, `isRoot`), `actions[]`, `renderLink`, `className`, `style`.
|
|
92
92
|
- **`ActionMenu`** — Dropdown menu of actions (kebab/overflow style). The trigger is an icon-only `Button` by default, so `size` draws exactly the square a `Button` of that size draws beside it: `xsmall` is Figma's 20px "Button Element - Square (X-Small)", `small` the 28px rung above it. Both squares are fixed rather than read off the `controlHeights` tokens, so re-theming those does not resize the trigger. A supplied `triggerIcon` is held to the tier's glyph size — 11px at `xsmall`, 16px at `small`. At 20px the `xsmall` trigger meets WCAG 2.5.8 through the *Spacing* exception rather than the 24px minimum, so keep at least 4px between adjacent triggers. `showLabel` draws `label` beside the icon instead of leaving it to the accessible name — for a menu that is the point of its corner rather than an overflow for a row that already says what it acts on — and `variant` puts the trigger on any `Button` variant, so a menu handing work to the assistant can wear the assistant ground rather than the overflow-kebab outline. An item's `icon` leads its label: every caller's names the action itself — copy, open, delete — and an icon that is part of an item's identity belongs where the eye starts rather than right-aligned, where it reads as a status column. The menu is Figma's `Dropdown Component - Options List`: a fixed sized to its widest item between a 180px floor and the 280px Figma draws, by default under the trigger's right edge, 14px below it, flipping above or clamping sideways when the viewport has no room, rounding at the library's 12px and padding wider (8px) than the menu a `Dropdown` opens. Items read in the primary text colour, or the secondary one with `tone="muted"` (e.g. a sidebar's menus); destructive ones in red; `danger: 'hover'` keeps an item in its normal colour and turns it destructive (red text on a light red ground) only on hover or keyboard focus, for an action like signing out. A ceiling rather than a flat width: taken literally it gave a menu of four short verbs 130px of air and made every kebab in an app the same width whatever it held. `minWidth` only raises it above that ceiling, so it is the one way to go past 280px, and a label too long for the box truncates rather than wrapping. _Key props:_ `ActionMenuItem[]`, `size`, `label`, `triggerIcon`, `minWidth`, `showLabel`, `variant`, `tone` (`default` | `muted`), `trigger` (your own control in place of the kebab, cloned with the menu's ref and aria state), `highlightChoices`, `placement` (`bottom-end` default | `bottom-start` | `right-start` | `top-start` | `top-center`), `offset` (`small` 8px | `medium` 12px | `large` 14px; applies to every placement; without it the default `bottom-end` keeps the options menu's 14px and the others use 8px). An item's `tag` (e.g. an "Early access" `Tag`) follows its label in a lazily loaded shadow host of its own, since the menu renders into `document.body`, and joins its accessible name; `current: true` marks the item for the page the user is on (`aria-current="page"` and the selected row paint; a `danger` item keeps its red text). An item with an `href` is a link: Cmd/Ctrl-click or a middle click opens it in a new tab and closes the menu, while a plain click runs `onClick` in its place when one is given (so a router can navigate in-app); Enter and Space both activate it. `target: '_blank'` opens it in a new tab, adds `noopener noreferrer` and tells screen readers it opens a new tab. An item with `checked` is one of a set of choices: a `menuitemradio` with `aria-checked` and a trailing check while true; picking it still runs `onClick` and closes. Give the choices of one set the same `group` and, where they sit next to each other, they share a `role="group"` named by it, so a screen reader can tell where the set ends; choices with the same `group` split by another item form separate groups. `description` adds a quieter second line under the label, announced as the item's description rather than its name. `intent` colours the label and icon: `warning` (amber) for undoing choices already made, `accent` (green) for a way forward; a disabled item drops it, and `danger` or `current` wins over it. `highlightChoices` styles the menu as a picker: the checked choice of each `group` sits on a light green row (a Dropdown selected option's ground) with a green check (a danger, intent, disabled or current choice keeps its own colours), and a text row whose label is a set's `group` name sits a notch smaller, as its heading. An item with `type: 'text'` is context rather than an action (an account's email above its actions): secondary text the arrow keys skip. Opened from the keyboard, focus lands on the first item, or on the checked choice in a menu of choices; Up/Down/Home/End move through enabled items, Tab closes the menu and moves on as usual; Escape or a picked item returns focus to the trigger.
|
|
93
93
|
- **`NavItem`** — A row in an app's side navigation. Idle rows read secondary and take the list hover; the `active` row wears the accent tint and sets `aria-current="page"` on a link. `collapsed` shrinks it to a 36px icon tile whose label becomes the accessible name and a right-hand tooltip, with any `badge` pinned to the tile's corner. `variant="subitem"` indents a child row behind a dot instead of an icon; `disclosure` makes a group header button with `aria-expanded` and a rotating chevron, and `hasActiveChild` colours its text while a child is current. Renders an `<a>` with `href`, the element passed with `asChild` (a router `Link`), or a `<button>`, and forwards its ref and extra attributes so it can be a `Popover` or `ActionMenu` trigger. `disabled` keeps the row a tab stop with `aria-disabled`, drops its hover and pointer, and ignores clicks, Enter and Space; a `Popover` or `ActionMenu` it triggers stays shut on press, hover, focus and arrow keys, while other keys still reach a passed `onKeyDown` so arrow navigation through a list keeps working; a disabled `href` row renders as a button so it cannot be followed. `disabledReason` explains it in a right-hand tooltip on hover and focus and is the row's accessible description from the first focus. Not with `asChild`, whose child would still navigate. _Key props:_ `label`, `icon`, `active`, `hasActiveChild`, `collapsed`, `variant` (`item` | `subitem`), `danger`, `trailing`, `badge`, `disclosure` (`expanded` | `collapsed`), `tooltip`, `accessibleLabel` (overrides the accessible name; collapsed it defaults to the tooltip text plus `badgeLabel`), `href`, `target`, `rel`, `onClick`, `asChild` + `children`, `className`, `size` (`medium` | `small`, the tighter row for lists inside a popover), `tag` (beside the label, e.g. early access), `badgeLabel` (read in place of the badge and added to the collapsed name), `disabled`, `disabledReason`. A passed `aria-expanded` (e.g. from a `Popover`) wins over `disclosure`, and a button row forwards a passed `aria-current`.
|