@stackone/malachite 2.98.0 → 2.99.1

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 CHANGED
@@ -12,6 +12,7 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
12
12
  - **`SurfaceExpandableRow`** — A row that opens to reveal a body (used as `Surface.ExpandableRow`), for a line that carries its own controls. Not `Accordion`, which puts its header inside the toggle button, so a header holding a dropdown or a second button would be invalid: here the row surface takes the click and a cell opts out by wrapping its controls in `ExpandableRow.Controls`, while the arrow stays a real button so the keyboard reaches it. That opt-out is explicit rather than sniffing the event target for an interactive ancestor, because a control rendering into a shadow root retargets the event to its host. `sticky` pins the row while its body scrolls, offset by `stickyTopOffset` for whatever is already pinned above it; it only pins while open, since a closed row has nothing to scroll past. _Key props:_ `header`, `children`, `expanded`, `onToggle`, `sticky`, `stickyTopOffset`, `divider`, `tone`, `aria-label`, `className`, `style`.
13
13
  - **`DisclosureArrow`** — The expand/collapse triangle disclosure UI shares (`Accordion`, `Surface.ExpandableRow`). Owns its colour states so they never drift between usages: `text-primary` when expanded, `text-placeholder` otherwise, and dark on hover inside a `group` ancestor — put `group` on the clickable header or row so that hover state activates. _Key props:_ `expanded`, `size`, `className`.
14
14
  - **`Card`** — Generic content card. `title` heads it, with dimmed `subtitle` text beside it and `extra` actions at the right of the title row. `variant="framed"` draws the detached `Table`’s frame instead: the title row sits on a grey frame and the children in a bordered section inside it, so a card above a table, such as a chart over a log list, reads as part of the same set. `dimmed`, `border`, `size`, `glassFooter` and `headerConfig` do not apply to a framed card. _Key props:_ `variant` (`CardVariant`: `default` | `framed`), `title`, `subtitle`, `extra`, `padding`, `footer`.
15
+ - **`ResourceCard`** — A card pointing at a resource elsewhere, such as an SDK’s documentation: a muted icon tile, a title, a description clamped to two lines and a link that opens in a new tab. `ResourceCard.Header` is the icon, title and description on their own, all phrasing content, so a section that opens on them, such as an `Accordion` header, can use it inside its button. _Key props:_ `icon`, `title`, `description`, `href`, `linkLabel` (default `Documentation`), `titleAs` (`h3` | `h4`), `className`. `ResourceCard.Header`: `icon`, `title`, `description`; phrasing content only, so its title is never a heading.
15
16
  - **`SelectableCard`** — A card that is one option in a radio group — eyebrow, optional status tag, title, description, a count label and a top-right action slot. Use inside a `CardStrip`. Selection is controlled by the consumer: pass `selected`, which drives both the visual treatment and `aria-checked`. A selected card meets the sheet below the way a browser tab meets its toolbar — its bottom corners flare outward onto the strip’s rule — so its outline is one SVG path rather than borders, which would split into two lines at the tangent. `variant` picks the palette: `profile` (green), `library` (neutral) or `editing` (amber, for a profile with unsaved changes). `actions` stands in the card’s top-right corner, on the eyebrow row, and renders outside the control so a menu or icon button inside it stays clickable and keeps its own tab stop. Nothing else marks that corner: the flared outline, the tint and the green eyebrow already say which card is selected, so a radio there would only repeat them. `onDismiss` adds an x after `actions`, tinted like the eyebrow so it reads as part of the card — for discarding a draft card; `dismissDisabledReason` disables it and explains why in its tooltip. `isDefault` marks the card as the account default with a pin beside the title, named for assistive tech and tooltipped for everyone else — it belongs with the name it qualifies rather than among the actions, which read as things to press. `address` puts a one-line chip above the count for a copyable address such as a server URL: its `label` is cut short with an ellipsis, and its full `value` shows in a tooltip and is copied on click, without selecting the card. It takes the place of `description`, since the card has room for one or the other. For a row-shaped selectable use `Surface.Row` instead. _Key props:_ `value`, `title`, `titleIcon`, `isDefault`, `variant` (`profile` | `library` | `editing`), `eyebrow`, `status` (`label`, `type`, `tooltip`), `description`, `address` (`label`, `value`), `countLabel`, `actions`, `onDismiss` (`dismissLabel`, `dismissDisabledReason`), `selected`, `loading` (`loadingLabel`, `loadingHint`), `disabled`, `dimmed`, `onSelect`, `tabIndex`, `aria-label`, `className`, `style`.
16
17
  - **`CardStrip`** — Horizontally scrolling radio group of cards, with edge arrows that appear only when the content overflows, an edge fade, scroll-snap and arrow-key navigation matching `SegmentedControl`. Owns interaction only: it finds its options by looking for `role="radio"` descendants carrying `data-value`, so any such child works (`SelectableCard` emits both). Pass a non-selectable terminal tile as `CardStrip.AddTile` — it sits inside the group but outside the radio set, and must be a direct child or it scrolls with the cards. Use `leading` to pin a card that should not scroll away; the strip tells the cards which slot they are in, so a pinned `SelectableCard` drops the left rule the scrolling ones draw. A strip too narrow to show a card beside `leading` scrolls it with the cards rather than squeezing them, so the selected card always has its full width. Set `bleed` when the strip sits in a `PageLayout`: the strip stretches past the horizontal padding of the layout so its bottom rule runs the full width of the page card, while the cards stay aligned to the gutter. With no cards at all the strip degenerates to its pinned slots alone — no trough, no scroller and no arrows — with the add tile standing beside `leading` and taking `primary` emphasis automatically, since adding the first card is the only thing on offer. _Key props:_ `value`, `tone` (`profile` | `library` | `editing` — read off the selected card unless set), `onChange`, `children`, `leading`, `arrows`, `fadeEdges`, `snap`, `bleed`, `scrollSelectedIntoView`, `aria-label`, `aria-labelledby`, `className`, `style`. `CardStrip.AddTile`: `label`, `icon`, `onClick`, `disabled`, `emphasis` (`primary` | `secondary` — left to the strip unless set: `primary` while there are no cards, `secondary` once there are), `className`.
17
18
  - **`SplitScreenLayout`** — Two-pane full-screen layout (content + preview/aside) with an optional dismiss button.
@@ -53,30 +54,9 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
53
54
  - **`Confetti`** — Celebratory confetti burst for success moments. _Key props:_ `pieces`.
54
55
  - **`ConfirmationDialog`** — Asks the customer to confirm one consequential action — a preset over `Modal`, not a second dialog implementation. `variant` picks a whole coherent set at once (badge fill, tray tint, caption colour, badge icon and confirm-button variant), so `destructive` cannot end up with a non-destructive confirm button; `destructive` also renders as `role="alertdialog"`, and `description` is wired to the dialog through `aria-describedby`, so the consequence is announced and not just the title. `confirmPhrase` gates the confirm action on typing that exact phrase, for a consequence severe enough that one click should not be able to cause it — the typed value and the phrase are both trimmed, since copying a name picks up a trailing space and a saved name can carry padding that never renders, except that a phrase of only whitespace is matched exactly as given, so an empty field cannot confirm it; the match stays case-sensitive, and the field clears each time the dialog opens, being a per-decision gate rather than a value. Neither a destructive dialog nor one carrying a `confirmPhrase` dismisses on a scrim click, and `loading` suppresses the pointer routes — the scrim and the close button — as well as disabling the buttons. It never suppresses ESC: that is the only guaranteed keyboard exit from a focus trap, so it always reaches `onClose` and whether to abort is left to the caller. ESC reaches it whenever it is the topmost overlay, so it can be opened over a panel. `confirmDisabled` holds only the confirm action back, for a consequence still being worked out (a check the callout reports on, so pair it with a callout saying why); cancel and every dismissal route stay live. `callout` renders an `Alert` in a full-width band at the top of the body — it scrolls with the body rather than being pinned under the header, and with no `description`, `children` or `confirmPhrase` there is no body, so the band sits directly on the footer — and its `type` is chosen independently of `variant` — the frames pair a green badge with an amber callout. `titleAdornment` names the entity beside the title, `badgeIcon` overrides the variant’s glyph for an action-specific one, and `tip` is the `{ label?, message }` caption on the tray beneath the card, which `Modal` renders and describes. `children` is where extra body content goes. `onConfirm` does not close the dialog, so the caller can hold it open on `loading` while the request is in flight. `confirmPhraseLabel` also takes `{ prefix, suffix }`, which renders the phrase itself as a copyable token between the two — the gate is case-sensitive and space-exact inside the phrase, so a customer who has identified the right entity should not be locked out by a glyph they cannot tell apart. The copy control sits outside the element that names the field, so “Copy…” never lands in the field’s accessible name; `confirmPhraseCopyLabel` names it and `onPhraseCopied` reports a completed write with the phrase it copied. A rejected write says so in the field rather than failing silently, and the control is disabled where the Clipboard API is unavailable. A near miss is named rather than left to a disabled button: typing the phrase with the wrong case or the wrong spacing says which, once the whole phrase is there, and that message is the field’s `aria-describedby`. _Key props:_ `open`, `onClose`, `onConfirm`, `title`, `description`, `titleAdornment`, `badgeIcon`, `variant` (`default` | `warning` | `destructive` | `success`), `callout`, `confirmPhrase`, `confirmPhraseLabel`, `confirmPhraseCopyLabel`, `confirmPhrasePlaceholder`, `onPhraseCopied`, `confirmLabel`, `cancelLabel`, `loading`, `confirmDisabled`, `tip`, `size`, `aria-label`, `aria-labelledby`.
55
56
 
56
- ## Lists, rows & navigation
57
-
58
- - **`ButtonList`** — Vertical list of pill-style button/link rows with built-in hover/focus/active states. _Key props:_ `buttons[]` (`key`, `children`, `onClick`, `href`), `compact`.
59
- - **`Accordion`** — Expand/collapse section with a clickable header (disclosure arrow + title/header + trailing slot). Use `header` for rich content and `trailing` for an interactive control (e.g. a Checkbox) — trailing sits outside the toggle button, so a selectable+expandable row is just an Accordion. Controlled or uncontrolled. Pass `stickyHeader` (+ optional `stickyTopOffset`) to pin the header on an opaque ground, keeping its open highlight and hover, while the body scrolls; add `pinnedCorners` for a section at the top of a card on the page ground, so the pinned header takes the rounded top corners of its card (set the `--malachite-ctx-pinned-surround` context variable on an ancestor when the card sits on another ground) — needs a scroll ancestor that clips without trapping sticky (e.g. `<Surface overflow="clip">`; with `pinnedCorners`, keep the default tone and add `shadow={false}` so the header can round over the border). `animate={false}` opens instantly. `collapsible={false}` makes a section that never closes: the same header, open highlight, sticky pinning and corner caps, with no arrow, hover or toggle, so `title` is plain text and `header` may hold controls; the toggle props (`isExpanded`, `defaultExpanded`, `onToggle`, `arrowPosition`, `disabled`) are ignored while it is `false`, and `animate` still picks how the body is rendered, so flipping `collapsible` keeps the body mounted. _Key props:_ `title` or `header`, `leading` (before the title, outside the toggle, e.g. a group's tri-state Checkbox), `trailing`, `arrowPosition` (`start` | `end` | `gutter`; `gutter` puts the arrow before `leading` as its own mouse toggle, as a file tree keeps its caret in the gutter), `highlightExpanded` (default `true`; `false` leaves an open row on the card ground), `flashKey` (change it after mount to flash an outline around the section; clearing it to `undefined` does not flash, a key coming back does), a forwarded `ref` to the section for `scrollIntoView` (with `stickyHeader` it carries a scroll margin of `stickyTopOffset`), `bodyIndent` (`none` | `title`; `title` starts the body under the title, 16px short of it so a compact `Surface.Row` inside lands its checkbox there), `collapsible` (default `true`), `disabled`, `isExpanded`/`defaultExpanded`, `onToggle`, `stickyHeader`, `stickyTopOffset`, `pinnedCorners`, `animate`.
60
- - **`DefinitionRow`** — Row showing an icon, label, optional tag and description — for definition/detail lists. _Key props:_ `icon`, `label`, `tag`, `description`.
61
- - **`PreviewTree`** — Nested, indented tree for previewing hierarchical structure.
62
- - **`PreviewTreeRow`** — A single labelled row within a PreviewTree. _Key props:_ `label`.
63
- - **`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`.
64
- - **`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`.
65
- - **`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.
66
- - **`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`.
67
- - **`Sidebar`** — An app's left navigation shell, pinned to the viewport's left edge: 260px wide, 60px `collapsed`, on the sunken page background. Composed from `Sidebar.Header` (a 56px band for `Sidebar.Switcher`, the logo + workspace + parent trigger), `Sidebar.Body` (the part that scrolls), `Sidebar.Notices`, `Sidebar.Search`, `Sidebar.Section` (rows of `NavItem`s at the gutter), `Sidebar.Group` + `Sidebar.GroupItems` (a disclosure header and its sub-items), `Sidebar.Divider`, `Sidebar.Usage` (a `UsageCard` placed at the sidebar's gutter) and `Sidebar.Footer` holding `Sidebar.Account`. Popovers opened from it (with `padding="none"`) wrap their body in `Sidebar.Panel`, sized so the popover comes to `SIDEBAR_POPOVER_WIDTH_PX`, and build it from the `Popover` parts. `onToggleCollapse` adds the edge toggle, shown in CSS while the pointer is over the sidebar or a keyboard focus is inside it, and always on a touch screen, which has no hover to reveal it. A workspace, organization or account name cut off in the expanded sidebar shows in full on hover. Notices, the divider and the usage card hide while collapsed. Render it inside `<MalachiteContext layer="sidebar">`, or the page paints over the edge toggle. On a viewport narrower than `SIDEBAR_OVERLAY_BREAKPOINT_PX` (768px) pass `overlay`, collapse it on entering overlay mode, and keep the page at the collapsed offset. Collapsed, it is the plain rail and takes no focus. Expanded from that rail, it floats over the page as a modal drawer, behind a scrim, with Escape, a focus trap and scroll lock, and a click on the scrim or Escape collapses it through `onToggleCollapse`. Expanded on mount or across the breakpoint it stays a plain sidebar, so it never takes focus from the page, and expanded under an open dialog it becomes the drawer once that dialog closes. _Key props:_ `collapsed`, `onToggleCollapse`, `overlay`, `expandLabel`, `collapseLabel`, `aria-label`; `Sidebar.Switcher`: `logo`, `title`, `subtitle`, `titleTooltip`/`subtitleTooltip` (shown when the name is cut off, the name by default; pass a node to wrap it, e.g. to keep it out of session recordings) + button attributes; `Sidebar.Account`: `avatar` or `initials` (a small chip when there is no photo), `name`, `tooltip` (on the collapsed rail, and expanded when the name is cut off; `name` by default; pass a node to wrap it) + button attributes; `Sidebar.Usage`: the `UsageCard` props; `Sidebar.Notices`: `aria-label` (required); `Sidebar.Panel`: `width` (`SIDEBAR_POPOVER_WIDTH_PX` by default). `useSidebarCollapsed()` reads the state from inside; `SIDEBAR_WIDTH_PX` gives the page its offset beside the sidebar; `SIDEBAR_TOOLTIP_DELAY_S` is the 0.2s delay its name and rail tooltips use, for tooltips a consumer adds inside it.
68
- - **`SearchTrigger`** — A button drawn as a filled search field, for opening a command palette or search dialog from app chrome such as a sidebar. It is not an input — typing happens in what it opens. `shortcut` draws flat `<kbd>` chips at the end (not `Keycap`, whose raised shadow reads as a second button inside a filled field), kept out of the accessible name; `iconOnly` makes a 36px icon tile matching a collapsed `NavItem`, named by `label`. _Key props:_ `label` (default `Search`), `shortcut` (`ReactNode[]`), `iconOnly`, `aria-label`, `className`, plus native button attributes (`onClick`, `aria-haspopup`, `aria-expanded`, `aria-keyshortcuts`).
69
- - **`FooterNav`** — Footer navigation bar of links. _Key props:_ `FooterNavLink[]`.
70
- - **`FooterLinks`** — Inline list of footer links (e.g. terms, privacy, support).
71
- - **`StepList`** — A numbered, vertical list of setup steps: a marker per step joined by a line that turns solid once a step is complete, each step’s title and description, and an optional trailing action such as its button. Steps are `complete` (a tick on the accent fill), `open` (an accent ring) or `locked` (dimmed). The first open step carries `aria-current="step"`. `size="small"` is the compact list for a sidebar; `dividers` rules a line under each row for a list that fills its container. For a horizontal progress readout use `Stepper`; for a clickable step header use `StepTabs`. _Key props:_ `steps` (`key`, `title`, `description`, `status`, `action`), `size`, `dividers`, `aria-label`, `aria-labelledby`, `className`.
72
- - **`StepTabs`** — Header for a short, ordered flow — a two-step drawer or wizard panel. Each step is a button carrying `aria-current="step"`, not a tab: the body beneath is the step’s form, so it keeps the normal tab order instead of adopting a `tablist`’s arrow-key contract. States are current / complete (a check, still reachable so the user can go back) / upcoming. For a read-only progress readout use `Stepper`. _Key props:_ `items` (`key`, `label`, `hint`, `disabled`), `activeKey`, `completedKeys`, `onChange`, `aria-label`, `aria-labelledby`, `className`.
73
- - **`CommandPalette`** — Chrome for a command palette, over a headless library that keeps its own elements. `FieldRow`/`Field` take the query input, `List` the scrolling viewport (with a bottom fade for `hasMoreBelow`), `Group` + `Heading` a titled section, and `Row` one result — composing leading/label/tags/crumb/meta/status/hint so names start and statuses end on the same x down the list. `Message` covers empty and loading, `Legend` documents the scope sigils, `Footer` the key hints. Everything the library owns is taken through `asChild`, so its role, id, state and handlers are untouched.
74
- - **`Keycap`** — One key on a keyboard, drawn as a cap — `esc`, `⌘`, a caret, or a sigil a user types to scope a search. Renders a `<kbd>`, or a button as soon as either `onClick` or `disabled` is passed — `disabled={false}` included, since naming the prop at all is the statement that the cap is a control. `SidePanelNavFooter` is built on it.
75
- - **`CollapsibleSection`** — Collapsible sunken-card section (title - subtitle header, disclosure arrow right) for stacked detail sections in side panels and detail pages. A preset over `Accordion`’s `sunken` variant.
76
- - **`KeyValueList`** — Bordered card of label/value rows (`KeyValueList.Row`) for entity details: fixed-width secondary labels, free-form values, row dividers. `truncate` keeps a long value (an ID) to one line with an ellipsis at the cell width and a tooltip only when it is actually cut off — the value itself when it is text, else the row’s `tooltip` (`null` turns it off). For inline content only: a Tag or AppLogo is clipped without an ellipsis, so use its own truncate, as with `CodeText truncate`. `size="small"` tightens the rows for a list inside a dialog or panel. _Key props:_ `size` (`small` | `medium`), `label`, `truncate`, `tooltip`.
77
-
78
57
  ## Forms & inputs
79
58
 
59
+ - **`ChoiceGroup`** — A grid of tiles to choose one option from, such as expiry presets or an MCP client. The chosen tile takes the accent border, the selected tint and a corner tick; an unchosen option can carry its own corner `mark`, such as a star on a recommended preset. `mode="radio"` (the default) is a `radiogroup` with one tab stop, moved with the arrow keys, Home and End, skipping disabled options. `mode="toggle"` is a `group` of `aria-pressed` buttons, each its own tab stop, that reports every press, for presets beside a choice of their own: `custom`, toggle mode only, puts that control, such as a `DatePicker`, in a last cell named by its `label` and ticks it while `chosen`, when the cell is announced as chosen. In radio mode a press on the chosen tile changes nothing. Long labels end in an ellipsis and show in full in a tooltip on hover or focus. The chosen tint is mixed from the accent, so a rebrand repaints it. The tick overhangs the top-right tile, so leave room above and after the group. `size="small"` centres a label in a compact tile; `medium` leads with the option’s `icon`. For large cards with a description use `SelectableCard`; for a row of segments use `SegmentedControl`. _Key props:_ `options` (`value`, `label`, `icon`, `mark`, `aria-label`, `disabled`), `value`, `onChange`, `mode` (`radio` | `toggle`), `size` (`small` | `medium`), `columns` (1–6, counting the custom cell), `custom` (`control`, `label`, `chosen`; toggle mode), `disabled`, `aria-label`, `aria-labelledby`, `className`.
80
60
  - **`Form`** — Form container coordinating field layout and submission.
81
61
  - **`FormItem`** — Labelled form field wrapper (label, help text, error).
82
62
  - **`BaseFormComponent`** — Low-level base used by form controls; rarely used directly.
@@ -99,6 +79,28 @@ The catalog of components exported from `@stackone/malachite`. **Reach for one o
99
79
  - **`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`.
100
80
  - **`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`.
101
81
 
82
+ ## Lists, rows & navigation
83
+
84
+ - **`ButtonList`** — Vertical list of pill-style button/link rows with built-in hover/focus/active states. _Key props:_ `buttons[]` (`key`, `children`, `onClick`, `href`), `compact`.
85
+ - **`Accordion`** — Expand/collapse section with a clickable header (disclosure arrow + title/header + trailing slot). Use `header` for rich content and `trailing` for an interactive control (e.g. a Checkbox) — trailing sits outside the toggle button, so a selectable+expandable row is just an Accordion. Controlled or uncontrolled. Pass `stickyHeader` (+ optional `stickyTopOffset`) to pin the header on an opaque ground, keeping its open highlight and hover, while the body scrolls; add `pinnedCorners` for a section at the top of a card on the page ground, so the pinned header takes the rounded top corners of its card (set the `--malachite-ctx-pinned-surround` context variable on an ancestor when the card sits on another ground) — needs a scroll ancestor that clips without trapping sticky (e.g. `<Surface overflow="clip">`; with `pinnedCorners`, keep the default tone and add `shadow={false}` so the header can round over the border). `animate={false}` opens instantly. `collapsible={false}` makes a section that never closes: the same header, open highlight, sticky pinning and corner caps, with no arrow, hover or toggle, so `title` is plain text and `header` may hold controls; the toggle props (`isExpanded`, `defaultExpanded`, `onToggle`, `arrowPosition`, `disabled`) are ignored while it is `false`, and `animate` still picks how the body is rendered, so flipping `collapsible` keeps the body mounted. _Key props:_ `title` or `header`, `leading` (before the title, outside the toggle, e.g. a group's tri-state Checkbox), `trailing`, `arrowPosition` (`start` | `end` | `gutter`; `gutter` puts the arrow before `leading` as its own mouse toggle, as a file tree keeps its caret in the gutter), `highlightExpanded` (default `true`; `false` leaves an open row on the card ground), `flashKey` (change it after mount to flash an outline around the section; clearing it to `undefined` does not flash, a key coming back does), a forwarded `ref` to the section for `scrollIntoView` (with `stickyHeader` it carries a scroll margin of `stickyTopOffset`), `bodyIndent` (`none` | `title`; `title` starts the body under the title, 16px short of it so a compact `Surface.Row` inside lands its checkbox there), `collapsible` (default `true`), `disabled`, `isExpanded`/`defaultExpanded`, `onToggle`, `stickyHeader`, `stickyTopOffset`, `pinnedCorners`, `animate`.
86
+ - **`DefinitionRow`** — Row showing an icon, label, optional tag and description — for definition/detail lists. _Key props:_ `icon`, `label`, `tag`, `description`.
87
+ - **`PreviewTree`** — Nested, indented tree for previewing hierarchical structure.
88
+ - **`PreviewTreeRow`** — A single labelled row within a PreviewTree. _Key props:_ `label`.
89
+ - **`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
+ - **`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`.
91
+ - **`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.
92
+ - **`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`.
93
+ - **`Sidebar`** — An app's left navigation shell, pinned to the viewport's left edge: 260px wide, 60px `collapsed`, on the sunken page background. Composed from `Sidebar.Header` (a 56px band for `Sidebar.Switcher`, the logo + workspace + parent trigger), `Sidebar.Body` (the part that scrolls), `Sidebar.Notices`, `Sidebar.Search`, `Sidebar.Section` (rows of `NavItem`s at the gutter), `Sidebar.Group` + `Sidebar.GroupItems` (a disclosure header and its sub-items), `Sidebar.Divider`, `Sidebar.Usage` (a `UsageCard` placed at the sidebar's gutter) and `Sidebar.Footer` holding `Sidebar.Account`. Popovers opened from it (with `padding="none"`) wrap their body in `Sidebar.Panel`, sized so the popover comes to `SIDEBAR_POPOVER_WIDTH_PX`, and build it from the `Popover` parts. `onToggleCollapse` adds the edge toggle, shown in CSS while the pointer is over the sidebar or a keyboard focus is inside it, and always on a touch screen, which has no hover to reveal it. A workspace, organization or account name cut off in the expanded sidebar shows in full on hover. Notices, the divider and the usage card hide while collapsed. Render it inside `<MalachiteContext layer="sidebar">`, or the page paints over the edge toggle. On a viewport narrower than `SIDEBAR_OVERLAY_BREAKPOINT_PX` (768px) pass `overlay`, collapse it on entering overlay mode, and keep the page at the collapsed offset. Collapsed, it is the plain rail and takes no focus. Expanded from that rail, it floats over the page as a modal drawer, behind a scrim, with Escape, a focus trap and scroll lock, and a click on the scrim or Escape collapses it through `onToggleCollapse`. Expanded on mount or across the breakpoint it stays a plain sidebar, so it never takes focus from the page, and expanded under an open dialog it becomes the drawer once that dialog closes. _Key props:_ `collapsed`, `onToggleCollapse`, `overlay`, `expandLabel`, `collapseLabel`, `aria-label`; `Sidebar.Switcher`: `logo`, `title`, `subtitle`, `titleTooltip`/`subtitleTooltip` (shown when the name is cut off, the name by default; pass a node to wrap it, e.g. to keep it out of session recordings) + button attributes; `Sidebar.Account`: `avatar` or `initials` (a small chip when there is no photo), `name`, `tooltip` (on the collapsed rail, and expanded when the name is cut off; `name` by default; pass a node to wrap it) + button attributes; `Sidebar.Usage`: the `UsageCard` props; `Sidebar.Notices`: `aria-label` (required); `Sidebar.Panel`: `width` (`SIDEBAR_POPOVER_WIDTH_PX` by default). `useSidebarCollapsed()` reads the state from inside; `SIDEBAR_WIDTH_PX` gives the page its offset beside the sidebar; `SIDEBAR_TOOLTIP_DELAY_S` is the 0.2s delay its name and rail tooltips use, for tooltips a consumer adds inside it.
94
+ - **`SearchTrigger`** — A button drawn as a filled search field, for opening a command palette or search dialog from app chrome such as a sidebar. It is not an input — typing happens in what it opens. `shortcut` draws flat `<kbd>` chips at the end (not `Keycap`, whose raised shadow reads as a second button inside a filled field), kept out of the accessible name; `iconOnly` makes a 36px icon tile matching a collapsed `NavItem`, named by `label`. _Key props:_ `label` (default `Search`), `shortcut` (`ReactNode[]`), `iconOnly`, `aria-label`, `className`, plus native button attributes (`onClick`, `aria-haspopup`, `aria-expanded`, `aria-keyshortcuts`).
95
+ - **`FooterNav`** — Footer navigation bar of links. _Key props:_ `FooterNavLink[]`.
96
+ - **`FooterLinks`** — Inline list of footer links (e.g. terms, privacy, support).
97
+ - **`StepList`** — A numbered, vertical list of setup steps: a marker per step joined by a line that turns solid once a step is complete, each step’s title and description, and an optional trailing action such as its button. Steps are `complete` (a tick on the accent fill), `open` (an accent ring) or `locked` (dimmed). The first open step carries `aria-current="step"`. `size="small"` is the compact list for a sidebar; `dividers` rules a line under each row for a list that fills its container. `completeLabel` shows a dot and that label, such as "Completed", in the action column of a complete step with no `action`, hidden from assistive tech, which already hears the state. For a horizontal progress readout use `Stepper`; for a clickable step header use `StepTabs`. _Key props:_ `steps` (`key`, `title`, `description`, `status`, `action`), `size`, `dividers`, `completeLabel`, `aria-label`, `aria-labelledby`, `className`.
98
+ - **`StepTabs`** — Header for a short, ordered flow — a two-step drawer or wizard panel. Each step is a button carrying `aria-current="step"`, not a tab: the body beneath is the step’s form, so it keeps the normal tab order instead of adopting a `tablist`’s arrow-key contract. States are current / complete (a check, still reachable so the user can go back) / upcoming. For a read-only progress readout use `Stepper`. _Key props:_ `items` (`key`, `label`, `hint`, `disabled`), `activeKey`, `completedKeys`, `onChange`, `aria-label`, `aria-labelledby`, `className`.
99
+ - **`CommandPalette`** — Chrome for a command palette, over a headless library that keeps its own elements. `FieldRow`/`Field` take the query input, `List` the scrolling viewport (with a bottom fade for `hasMoreBelow`), `Group` + `Heading` a titled section, and `Row` one result — composing leading/label/tags/crumb/meta/status/hint so names start and statuses end on the same x down the list. `Message` covers empty and loading, `Legend` documents the scope sigils, `Footer` the key hints. Everything the library owns is taken through `asChild`, so its role, id, state and handlers are untouched.
100
+ - **`Keycap`** — One key on a keyboard, drawn as a cap — `esc`, `⌘`, a caret, or a sigil a user types to scope a search. Renders a `<kbd>`, or a button as soon as either `onClick` or `disabled` is passed — `disabled={false}` included, since naming the prop at all is the statement that the cap is a control. `SidePanelNavFooter` is built on it.
101
+ - **`CollapsibleSection`** — Collapsible sunken-card section (title - subtitle header, disclosure arrow right) for stacked detail sections in side panels and detail pages. A preset over `Accordion`’s `sunken` variant.
102
+ - **`KeyValueList`** — Bordered card of label/value rows (`KeyValueList.Row`) for entity details: fixed-width secondary labels, free-form values, row dividers. `truncate` keeps a long value (an ID) to one line with an ellipsis at the cell width and a tooltip only when it is actually cut off — the value itself when it is text, else the row’s `tooltip` (`null` turns it off). For inline content only: a Tag or AppLogo is clipped without an ellipsis, so use its own truncate, as with `CodeText truncate`. `size="small"` tightens the rows for a list inside a dialog or panel. _Key props:_ `size` (`small` | `medium`), `label`, `truncate`, `tooltip`.
103
+
102
104
  ## Buttons & actions
103
105
 
104
106
  - **`Button`** — Primary button. Variants: `filled`, `outline`, `surface` (outline's geometry on a ground of its own, for a control sitting on a tinted surface), `assistant` (the violet the assistant is named in — provenance, not a severity: it says who is being asked, not that anything is wrong), `destructive`, `success`, `warning`, `error`, `ghost`, `row-outline` (`ghost` until the `Surface.Row` whose `trailing` slot it sits in is hovered or holds focus, or its menu is open, then `outline`; always `outline` on a touch screen — a row control that stays quiet until its row is in play, in CSS alone), `quiet` (text only in the accent colour, for a secondary action such as Reset beside a primary one — accent, not success, because it is something to press rather than a status), `muted` (a recessed grey with secondary text, for a control whose subject is switched off, such as an account set to Not allowed; it stays clickable), `no-style`. Supports `flush` (pulls a borderless button out by its padding so its label lines up with the text around it), `iconOnly`, `loading`, `tooltip`. `leading` puts something that is not an icon, such as an avatar, before the label at its own size; `contentAlign="start"` starts the label at the leading edge and pins an end `icon` to the far edge, which with `flexGrow` makes a full-width switcher trigger — a project pill whose width comes from its container (e.g. a box `SIDEBAR_POPOVER_WIDTH_PX` wide, so it lines up with the `Sidebar.Panel` it opens). `type` is `button` unless set, so a Button in a form submits it only as `type="submit"`. _Key props:_ `variant`, `size`, `icon`, `iconPosition`, `leading`, `contentAlign` (`center` | `start`), `flexGrow` (fills the container), `width` (`auto` | `wide` — a 120px floor for a panel's or dialog's primary action), `iconOnly`, `loading`, `disabled`, `fill`, `tooltip`.