@keboola/design 13.2.0 → 14.0.0

package/AGENTS.md

@@ -79,6 +79,8 @@ This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-A
 
 **Never** use `Popover` for destructive confirmations (use `Popconfirm`) or hover-only previews (use `HoverCard`). **Never** hand-roll a confirmation from `Modal` + buttons — use `AlertModal`, which owns the confirm/cancel actions and the async loading state.
 
+**`Modal.Content` is centred by default.** Pass `align="top"` when the content changes height while in use (fields appear or drop as the user picks), so the modal stops re-centring and moving the field under the pointer. The legacy brand ignores it: its modals are always top-anchored.
+
 **Filters in a menu are menu items:** `DropdownMenu.RadioItem indicator="check"` for one value, `DropdownMenu.CheckboxItem indicator="checkbox"` for several, both `indicatorAlign="end"`. Never `RadioGroup` or `Checkbox` in a `DropdownMenu` or `Popover`.
 
 ### Inputs
@@ -743,10 +745,12 @@ takes the node, and the chip lets it have the keyboard.
 />
 ```
 
-- A query overrides folding: every match shows, and a group with none disappears — so the group's row always stands for something the user can see.
+- A query opens every group with a match, and a group with none disappears — so the group's row always stands for something the user can see. A fold made under a query lasts until the query changes.
 - `value` holds items only. The row reads checked / mixed from them and never becomes a chip, so `allowSelectAll` and `renderChips` count what they always count.
 - Without `selectableGroups` / `groupToValue` a press on the row folds the group; with them, the chevron and `ArrowRight` / `ArrowLeft` do.
 - Don't hand-roll it from a flat list and an `onValueChange` that expands a parent into its children — the control owns the fold, the query override and the mixed state.
+- An item the user picked elsewhere and can't remove here (a table another mapping uses) is `itemToLocked`, not `itemToDisabled`: a locked row looks disabled but still takes the highlight, so `renderAside` describes it and its group still folds; a disabled row takes neither.
+- `renderAside={(highlighted) => …}` adds an inspector beside the list about the last row the pointer or the arrow keys were on — `{ kind: 'item' }`, `{ kind: 'group' }` or `null` before any. A button in the popup hides it (`asideOpen` / `onAsideOpenChange` to persist that), and it stays hidden while the popup is under 40rem. Reach for it when a row needs more detail than fits on it.
 
 **Long lists** — a `Combobox` or `MultiCombobox` whose options can run into the hundreds (tables, configurations, users) takes `virtualized="auto"`: past 30 options, grouped or not, only the rows in view reach the DOM. It is opt-in because a test that clicks a far row needs every option rendered.
 

package/CHANGELOG.md

@@ -1,5 +1,166 @@
 # @keboola/design
 
+## 14.0.0
+
+### Major Changes
+
+- `ToolCallApproval` v2 — redesigned around what an agent chat's approval card needs. It had no consumers, so the old API is replaced outright.
+  - Removed: `enableShortcuts` (Enter approve / Escape reject) and the `actions` override; `toolName` is now optional.
+  - Actions: `approveLabel` / `rejectLabel`, `approveVariant` (`'primary' | 'danger'`), an optional `extraAction` (e.g. "Always allow"), `pendingAction` (that button spins, every action disables), `isDisabled`.
+  - Header: `eyebrow` slot, optional `toolName`, `title`.
+  - Terminal states: `approved`, `rejected`, `expired`, `timed-out`, `cancelled`, `unattended`, with `statusLabel` / `statusMessage`, `resolvedBy` / `resolvedAt`, and `density="record"` for a one-line resolved record.
+  - Body: `children`, `notices` (warning / destructive / info rows), `aside` (beside the detail, stacked in a narrow container), `error`.
+  - Keyboard: `shortcutKey` (`'enter' | 'mod-enter' | 'none'`) approves from anywhere and shows the key on the button; `isShortcutHintOnly` shows it for an app that owns the shortcut.
+  - Stable test ids: `tool-call-approval`, `tool-approve-button`, `tool-decline-button`, `tool-extra-action-button`.
+
+### Minor Changes
+
+- `AnswerSources` and `SourceChip`: the provenance row under an answer. Chips carry a `verified` / `unverified` / `neutral` verdict and render as a link, button or label; the row collapses past six chips, summarises unverified ones once, states when none were declared and takes a `footnote` slot.
+
+- `ChatNotice`: a transcript notice row over `Alert` with `tone` (`error` / `warn` / `info`), an `action` slot, collapsible "Technical details" and an optional `retryAfter` countdown.
+
+- AI Kit composer chips: `AttachmentChip` (uploading / ready / error file chip with remove), `ContextChip` (quoted excerpt with "Show all" and images), `ModeChip` (removable animated mode pill) and `JumpToLatest` (scroll-to-latest button that pulses while the agent is working).
+
+- `SuggestedPrompt` takes `description` (a secondary line under the label), `trailing` (content pinned to the row's end, e.g. a badge) and `aria-label`. Without them it renders as before.
+
+- `PlanApproval` and `AnswerSummary` take an `expired` state for a card closed with no decision.
+  - `PlanApproval`: `status="expired"` (orange `Expired` pill, no actions), plus `statusLabel` to rename the pill and `statusMessage` shown under the title.
+  - `AnswerSummary`: `variant="expired"` (header ends `Expired`), plus `statusLabel` and a `statusMessage` shown first once expanded.
+
+- `PromptInput` takes `allowSendWhileBusy`: with it, a non-empty box sends while the conversation is `streaming` or `submitted` instead of refusing the keystroke, and Stop moves to a control of its own so cancelling never means emptying the box first. Off by default, so every existing composer behaves exactly as before.
+
+  Kai's composer turns that on. A message typed while Kai is working is queued and shown waiting rather than silently dropped, and a message typed under an open question answers it.
+
+- `AnswerActions` takes opt-in `onDownComment` (+ `commentPlaceholder`), a one-line comment input after a thumbs-down, and `onRegenerate` (+ `regenerateLabel`), an "Ask again" button; both are off by default
+
+- `FileDownloadChip` takes opt-in `onPreview` (split chip) and `actions`; new `FileGallery` block for image thumbnails (lazy, host-owned URLs and loading, capped with "+N more"). The default chip renders as before
+
+- `MessageBubble` takes opt-in `timestamp="visible"`, `quote`, `status` + `onRetry`, `author`, `collapseAfterPx` and `avatar`; without them it renders as before
+
+- `Modal.Content` takes `align="top"`: a new-design modal pinned to the top instead of centred, for a form whose height changes while it is in use. The legacy modal is always top-anchored.
+
+- `MultiCombobox` takes `renderAside`, a pane beside the list that describes the highlighted row, a group's own row included.
+
+  A combobox row's label fills the row, so content inside it can align to the row's end.
+
+  `MultiCombobox` takes `groupAppearance="banded"`, which puts each group, its row and open items, on a white card over a grey list.
+
+  A selectable group row reads checked or mixed from its locked items that are already selected.
+
+  `MultiCombobox` takes `collapseSelectedGroups`: each time the popup opens, a group whose items are all selected starts folded. A disabled group row still folds from its chevron.
+
+  `MultiCombobox` takes `asideOpen` and `onAsideOpenChange`: a button with a tooltip in the popup's bottom-right corner hides and shows the `renderAside` inspector. It is a grid column going from `0fr` to `1fr`, so the list narrows beside it rather than being covered, it keeps describing the last highlighted row until the popup closes, and it stays hidden, button included, while the popup is under 40rem wide.
+
+  A collapsible group's items fade and slide in as it unfolds and out as it folds, except under reduced motion. Banded rows are square inside their card, the first and last taking its corners, and enabled rows show a pointer.
+
+  `MultiCombobox` takes `defaultOpen` and `onOpenChange`, for a picker shown on demand with its list already open.
+
+  `MultiCombobox` takes `anchor`: with it there is no field, and the popup opens against that element with its search at the top. A banded popup is grey throughout, inspector included, with 8px of real space between group cards.
+
+  `MultiCombobox` takes `query`: search text typed elsewhere. With `anchor`, the popup then has no search of its own, and the host forwards the list keys to its hidden combobox input.
+
+  `Breadcrumb.Dropdown` takes `panelClassName`, for a panel background its search row shares with the list; the search row carries `data-slot="breadcrumb-dropdown-search"`.
+
+  A collapsible group's chevron, in `Combobox` / `MultiCombobox` and in `Breadcrumb.Dropdown.Group`, has a tooltip, and Cmd-click (Ctrl elsewhere) expands or collapses every group at once.
+
+  When a combobox group folds or unfolds, including all at once, the groups under it slide to their new place, and a windowed list keeps each row's measured height across a fold.
+
+  A query opens every collapsible group with a match, in `Combobox` / `MultiCombobox` and `Breadcrumb.Dropdown.Group`; a group folded under it stays folded until the query changes.
+
+  `MultiCombobox` takes `itemToLocked`: a selected item the user cannot remove looks disabled but still takes the highlight, so `renderAside` describes it and its group still folds; a group of only locked items locks its row.
+
+  An open `Combobox` / `MultiCombobox` popup marks `<body>` with `data-combobox-open`, counted across popups, so an app can lift the tooltips of the rows it lists. Combobox row labels carry `data-slot="combobox-item-label"`.
+
+- `PromptInput` takes `canSubmitEmpty`, so a composer whose attachments are the message can send with no text. Off by default.
+
+- `PromptInput` takes `blurOnEscape`, an `onKeyDown` that runs after its own key handling, `onPasteFiles` for files on the clipboard, and `busy` to hold the composer read-only while keeping focus. All opt-in.
+
+- `PromptInput`'s `/` menu picks the highlighted command on Tab, and opens with an empty or loading row (`commandsLoading`, `commandsEmptyText`) when `commands` is an empty list. New opt-in `slashTrigger="typed"` opens it only for a `/` typed into an empty composer.
+
+- Interaction-state and surface-corner tokens, so a theme can tell a hovered item from a selected one and round cards, menus and dialogs apart from controls. Unset, every token resolves to the value it replaced, so nothing changes until a theme sets one.
+  - `tw:bg-hover` / `tw:text-hover-foreground` (`--hover`, `--hover-foreground`) paint hover and keyboard highlight in Select, Combobox, Command, Breadcrumb, RadioGroup, Toggle, Calendar, DiffView, FileUpload, the markdown toolbar and AIKit. Unset: `accent` / `accent-foreground`. Argo `DropdownMenu` items, `Table` rows and `SectionNav` follow `--hover` too and, unset, keep their own `primary` / `muted` tint.
+  - `tw:bg-selected` / `tw:text-selected-foreground` (`--selected`, `--selected-foreground`) paint selected, checked and current in Table, Pagination, a checked `FieldBox`, the Calendar range, the active Breadcrumb item, SectionNav and a checked Command item. Unset: `accent` / `accent-foreground`. A checked argo `DropdownMenu` item follows `--selected` and, unset, keeps its `primary` tint.
+  - `tw:bg-pressed` (`--pressed`) is available for a pressed wash; no component paints it yet. Unset: `accent` a step towards its foreground.
+  - `tw:bg-scrim` (`--scrim`) is the `Modal`, `AlertModal` and `Sheet` backdrop. Unset: black at 50%.
+  - `tw:opacity-disabled` (`--disabled-opacity`) replaces every disabled `opacity-50`, `FieldBox` labels and `InputGroup` included. Unset: `0.5`. Controls disabled at 30%, 40% or 60% keep their own value.
+  - `--radius-card` rounds `Card`, `DashboardHero` and `tw:rounded-card`; unset, `Card` keeps `--radius-lg` and `rounded-card` keeps 10px. `--radius-popover` (`tw:rounded-popover`) rounds argo menus, popovers, hover cards and tooltips (unset 1rem). `--radius-modal` (`tw:rounded-modal`) rounds argo `Modal` and `AlertModal` (unset 1.5rem). `--radius-sheet` (`tw:rounded-sheet`) rounds the inner edge of an argo `Sheet` and `--radius-toast` (`tw:rounded-toast`) a `Toast`; unset, both keep `--radius-lg`.
+  - `tw:bg-sidebar-hover` / `tw:bg-sidebar-selected` (+ `-foreground`) split the `Sidebar` and `Navbar` hover from the current page, which both painted `sidebar-accent`. Unset, both are `sidebar-accent`; a current item keeps its selected fill while hovered.
+  - `ThemeProvider` emits all of them from a brand's `colors` / `colorsDark`, `radii` and `opacity`, and `BrandEditor` edits them.
+
+- `InlineStepLabel` takes opt-in `meta`, and `detail` + `defaultExpanded` for a collapsible per-row detail; `InlineStepGroup` takes an opt-in `footer`. Both render as before without them
+
+- `Tooltip.Title` heads a rich tooltip, and every floating overlay carries its own layer.
+  - `Tooltip.Title` is a small uppercase heading in the tooltip's text colour.
+  - `Tooltip` content spaces a nested `hr` and drops the last paragraph's bottom margin; on the legacy chrome a link takes the tooltip's text colour.
+  - `Tooltip` sits above `Modal` and every popup (1060); `HoverCard` sits with `Modal` (1051); a `DropdownMenu` submenu sits with its menu (1055).
+  - `Combobox` leaves `<body>` untouched while its popup is open.
+
+- `Markdown` gains opt-in streaming and code features; every default renders as before:
+  - `splitSealedBlocks(text)` and `withholdOpenTail(text, { diagram, tableHead })` — pure helpers for streaming an answer through `Markdown.Root` / memoised `Markdown.Block`s.
+  - `highlight` — colours fenced SQL, Python, JS/TS, JSON, shell and YAML through a lazily loaded highlighter.
+  - `sortable` (also on `MarkdownTable`) — header presses sort rows, numeric-aware, with `aria-sort`.
+  - `diagramActions` and `diagramDownload` — extra diagram toolbar controls and a built-in "Download SVG" action; `DiagramBlock` forwards `renderActions`.
+  - `ChatInlineIcon` also draws Lucide names (`icon:info`, `icon:trash-2`, …).
+
+- `Markdown` takes an opt-in `allowSvgFences`: an `svg fence, or an `xml / ```html fence whose body is a single SVG document, renders as a responsive chart instead of code. The SVG is sanitized with DOMPurify's SVG profile and loses scripts, event handlers, `foreignObject`, SMIL animation, `<style>` elements and every non-`#` reference. Raw inline HTML stays escaped, and the default is unchanged.
+
+  `ZoomableSvg` takes an opt-in `allowUse` to keep `<use>` (matplotlib draws every glyph with it) for markup whose `href`s are already limited to `#` references.
+
+- `PromptInput` takes `history`: the prompts already sent, oldest first. ↑ with the caret at the start of the text recalls them, newest first; ↓ steps back to the draft. Open `/` and `@` menus keep the arrows.
+
+- `Question` takes what an agent chat's question card needs. Additive; existing callers are unchanged.
+  - `isSubmitDisabled` keeps the answer from being sent, by click or ⌘/Ctrl+Enter.
+  - `isSubmitting` spins Submit and disables Skip.
+  - `error` shows why the last send failed, above the footer.
+  - `customAnswerMaxLength` caps the "Other" answer.
+  - An option's `badge` (e.g. `Recommended`) follows its label.
+  - `skipTooltip` replaces the Skip button's `Space` hint; `null` drops it.
+
+- `Table.Header` puts its row on the card surface, and `Table.SkeletonRows` draws placeholder rows in a table's own columns while its rows load.
+  - The header is `bg-card` with an `h-11` row and a border under it; `withShadow` and `className` work as before.
+  - The surface sits on `thead`, so `className="tw:bg-table-header"` (the former default tint) or any other `bg-*` replaces it at rest and on hover.
+  - `Table.SkeletonRows` takes `columns`, `noun` and `rows` (5 by default); the first row announces `Loading {noun}` to screen readers.
+  - Each column takes the real cell's `className` and `colSpan` and draws a `text` line, a `name` (icon, name and description lines) or nothing (`empty`).
+  - A width class can be a list, cycled over the rows; the name line varies in width from row to row unless given one.
+
+- `MermaidDiagram` renders with Pele, a dependency-free Mermaid renderer, in place of `mermaid` and `beautiful-mermaid`.
+  - Every Mermaid 12.1 diagram type; each type's code loads on first use, after which a diagram renders synchronously.
+  - Colours and font come from the DS tokens for the active scheme and are written into the SVG, so an exported SVG or PNG keeps them.
+  - `lucide:<name>` icons draw from the bundled Lucide pack; other icon packs draw no icon.
+  - A diagram cut off mid-stream shows the skeleton, and its source after 2 s without more input; invalid syntax shows the source.
+  - Layout and look follow Pele, not Mermaid.
+
+- `Table` puts its body on the card surface, the same `bg-card` as `Table.Header`.
+  - The fill sits on `<table>`, so a caller's `bg-*` in `className` replaces it.
+  - Row hover and selection tints draw over it as before.
+
+- `RjsfSchemaEditor` draws a `format: 'checkbox'` array as a group of DS `Checkbox`es.
+  - Each option toggles its value in the array; `readOnly` and `options.enumDisabled` disable them.
+  - `options.inline` lays the options out in a wrapping row.
+
+- `RjsfSchemaEditor` renders an array of enum values (`uniqueItems` + `items.enum`, no `format: 'checkbox'`) as a `MultiCombobox`.
+  - The default `async-multi-select` widget offers the `items.enum` options, labelled by `items.options.enum_titles`, and writes the selection back as an array of the typed enum values.
+  - A stored value outside `items.enum` shows as a chip labelled by the value and survives an edit.
+  - `readOnly` and `ui:disabled` disable it; options in `ui:enumDisabled` cannot be picked.
+  - It does not load `async` options, create `tags` / `creatable` values or read `enumSource`; a host widget passed under `async-multi-select` replaces it for that.
+
+### Patch Changes
+
+- `MultiCombobox`: while nothing matches, the inspector and its button go at once and the list takes the whole width, so the inspector never describes a row the list no longer shows.
+
+- `MultiCombobox`: with the inspector hidden, the list ends above the inspector button, so the button never covers a row at any scroll position.
+
+- `Markdown`'s `allowSvgFences` keeps only an allowlist of paint and text declarations in a fenced chart's `style` attributes, so `image-set()` can no longer load a URL and `position: fixed` can no longer lay an overlay over the page.
+
+- `Markdown`'s `allowSvgFences` caps the nodes a fence's `<use>` elements clone (20,000), not their count, so a few `<use>` aimed at a large group can no longer multiply into millions of rendered nodes.
+
+- `Table.SkeletonRows` takes `gapClassName` on a `name` column, the gap between its icon and lines (`tw:gap-3.5` by default), so a table's placeholder name starts where its real name does.
+
+- `Command.Item`'s keyboard highlight is the only row fill: a `checked` row shows a trailing check (or its checkbox / radio indicator), and rows no longer cross-fade on ↑/↓. The project switcher and Kai's chat history mark the current row this way (UT-5894)
+
+- Updated dependencies:
+  - @keboola/brand-registry@2.1.0
+
 ## 13.2.0
 
 ### Minor Changes

package/COMPONENT-API.md

@@ -363,48 +363,58 @@ Source: `src/blocks/Form/connectors/MultiComboboxField.tsx`
 
 > Several values from a searchable list — state is `string[]`, never objects, so the form value stays what gets submitted. Project labels with `itemToLabel`; add `allowCreate` for an enum the user may extend. Imported by name from `@keboola/design`, composed inside `form.AppField` — NOT reachable as `field.MultiComboboxField`.
 
-| Prop                  | Type                                                                                                                                                                                                              | Required | Default | Description                                                                                                                                                                                                                                                                                    |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`              | `ReactNode`                                                                                                                                                                                                       | no       | —       | Trailing node on the label row (e.g. a `Link`); not part of the accessible name.                                                                                                                                                                                                               |
-| `allowClear`          | `boolean`                                                                                                                                                                                                         | no       | —       | Clear-all button, shown only while chips exist. Chips stay removable either way.                                                                                                                                                                                                               |
-| `allowCreate`         | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `allowSelectAll`      | `boolean`                                                                                                                                                                                                         | no       | —       | "Select All" row for the whole set; hidden while a query is active, clears when all are selected.                                                                                                                                                                                              |
-| `aria-describedby`    | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `canCreate`           | `((query: string) => boolean)`                                                                                                                                                                                    | no       | —       | Rejects a value `allowCreate` would mint; values naming an item or already selected skip it.                                                                                                                                                                                                   |
-| `className`           | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `collapsibleGroups`   | `boolean`                                                                                                                                                                                                         | no       | —       | A row per group that folds it. A query shows every match regardless; state is keyed by position.                                                                                                                                                                                               |
-| `createSeparator`     | `string \| RegExp \| null`                                                                                                                                                                                        | no       | —       | Splits one entry into several values (default `','`). A `RegExp` must not capture; `null` never splits.                                                                                                                                                                                        |
-| `empty`               | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `focusVariant`        | `"off" \| "on" \| "default" \| null`                                                                                                                                                                              | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `groupToLabel`        | `((group: Group<string>) => ReactNode)`                                                                                                                                                                           | no       | —       | Defaults to the group's `label`, as `Select` shows it.                                                                                                                                                                                                                                         |
-| `help`                | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `indicator`           | `Indicator`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `inputClassName`      | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `inputValueSanitizer` | `((input: string) => string)`                                                                                                                                                                                     | no       | —       | Rewrites typed text before filtering and creating. Sees the whole text per keystroke — don't `trim()`.                                                                                                                                                                                         |
-| `isItemEqualToValue`  | `((itemValue: string, value: string) => boolean)`                                                                                                                                                                 | no       | —       | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison.                                                                                 |
-| `isLoading`           | `boolean`                                                                                                                                                                                                         | no       | —       | Options still arriving; doesn't disable — pass `disabled` where the user must wait.                                                                                                                                                                                                            |
-| `items`               | `readonly (string \| Group<string>)[]`                                                                                                                                                                            | no       | —       | Read as immutable: pass a new array to change it; one mutated in place is not re-filtered.                                                                                                                                                                                                     |
-| `itemToChipColor`     | `((item: string) => "gray" \| "gray-darker" \| "gray-inverse" \| "green" \| "green-darker" \| "green-inverse" \| "blue" \| "blue-inverse" \| "red" \| "orange" \| "orange-inverse" \| "amber" \| ... 9 more ...)` | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `itemToChipLabel`     | `((item: string) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `itemToDisabled`      | `((item: string) => boolean)`                                                                                                                                                                                     | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `itemToIcon`          | `((item: string) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `itemToLabel`         | `((item: string, query: string) => ReactNode)`                                                                                                                                                                    | no       | —       | Row and chip content (unless `itemToChipLabel`), `itemToStringLabel` by default. - `query` is the search text, for `MarkedText`; a chip gets `''`.                                                                                                                                             |
-| `itemToStringLabel`   | `((itemValue: string) => string)`                                                                                                                                                                                 | no       | —       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
-| `itemToStringValue`   | `((itemValue: string) => string)`                                                                                                                                                                                 | no       | —       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.      |
-| `label`               | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `maxVisible`          | `number`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `onQueryChange`       | `((query: string) => void)`                                                                                                                                                                                       | no       | —       | Reports the sanitized query, on mount too. Notification only — the control owns the text.                                                                                                                                                                                                      |
-| `pinnedChipLabels`    | `ReactNode[]`                                                                                                                                                                                                     | no       | —       | Non-removable chips ahead of the values, outside `maxVisible` and absent from `value`.                                                                                                                                                                                                         |
-| `queryToCreateLabel`  | `((query: string) => ReactNode)`                                                                                                                                                                                  | no       | —       | Words the create row. Receives the values it adds, trimmed and re-joined — not the entry as typed.                                                                                                                                                                                             |
-| `queryToCreateValue`  | `((query: string) => string)`                                                                                                                                                                                     | no       | —       | Projects one entered value into an item. Called once per trimmed part of a split entry.                                                                                                                                                                                                        |
-| `renderChips`         | `((values: string[]) => ReactNode)`                                                                                                                                                                               | no       | —       | Replaces the default chips; the chip props, `maxVisible` included, are then ignored.                                                                                                                                                                                                           |
-| `required`            | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `requiredMark`        | `RequiredMark`                                                                                                                                                                                                    | no       | —       | Gated by `required`: `'required'` shows `*` only if required, `'optional'` shows `(optional)` only if not, `'hidden'` neither. Defaults to `'required'`.                                                                                                                                       |
-| `selectableGroups`    | `boolean`                                                                                                                                                                                                         | no       | —       | A group's row selects its matching enabled items. The row itself never enters `value`.                                                                                                                                                                                                         |
-| `sizing`              | `"small" \| "medium" \| "default" \| null`                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `tooltip`             | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `variant`             | `"primary" \| "secondary" \| null`                                                                                                                                                                                | no       | —       |                                                                                                                                                                                                                                                                                                |
-| `virtualized`         | `boolean \| "auto"`                                                                                                                                                                                               | no       | —       | Puts only the rows in view into the DOM: `'auto'` past 30 options, grouped or not; `true` always.                                                                                                                                                                                              |
+| Prop                     | Type                                                                                                                                                                                                              | Required | Default | Description                                                                                                                                                                                                                                                                                    |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`                 | `ReactNode`                                                                                                                                                                                                       | no       | —       | Trailing node on the label row (e.g. a `Link`); not part of the accessible name.                                                                                                                                                                                                               |
+| `allowClear`             | `boolean`                                                                                                                                                                                                         | no       | —       | Clear-all button, shown only while chips exist. Chips stay removable either way.                                                                                                                                                                                                               |
+| `allowCreate`            | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `allowSelectAll`         | `boolean`                                                                                                                                                                                                         | no       | —       | "Select All" row for the whole set; hidden while a query is active, clears when all are selected.                                                                                                                                                                                              |
+| `anchor`                 | `Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null`                                                                                                    | no       | —       | No field: the popup opens against this element, its search at the top. Pair with `defaultOpen`.                                                                                                                                                                                                |
+| `aria-describedby`       | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `asideOpen`              | `boolean`                                                                                                                                                                                                         | no       | —       | Whether the inspector shows; a button in the popup toggles it. Uncontrolled, it starts open.                                                                                                                                                                                                   |
+| `canCreate`              | `((query: string) => boolean)`                                                                                                                                                                                    | no       | —       | Rejects a value `allowCreate` would mint; values naming an item or already selected skip it.                                                                                                                                                                                                   |
+| `className`              | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `collapseSelectedGroups` | `boolean`                                                                                                                                                                                                         | no       | —       | Each time the popup opens, a group whose items are all selected starts folded.                                                                                                                                                                                                                 |
+| `collapsibleGroups`      | `boolean`                                                                                                                                                                                                         | no       | —       | A row per group that folds it. A query shows every match regardless; state is keyed by position.                                                                                                                                                                                               |
+| `createSeparator`        | `string \| RegExp \| null`                                                                                                                                                                                        | no       | —       | Splits one entry into several values (default `','`). A `RegExp` must not capture; `null` never splits.                                                                                                                                                                                        |
+| `defaultOpen`            | `boolean`                                                                                                                                                                                                         | no       | —       | The popup is open on mount, for a picker shown on demand.                                                                                                                                                                                                                                      |
+| `empty`                  | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `focusVariant`           | `"off" \| "on" \| "default" \| null`                                                                                                                                                                              | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `groupAppearance`        | `"plain" \| "banded"`                                                                                                                                                                                             | no       | —       | `banded`: each group, its row and open items, is a white card on a grey list.                                                                                                                                                                                                                  |
+| `groupToLabel`           | `((group: Group<string>) => ReactNode)`                                                                                                                                                                           | no       | —       | Defaults to the group's `label`, as `Select` shows it.                                                                                                                                                                                                                                         |
+| `help`                   | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `indicator`              | `Indicator`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `inputClassName`         | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `inputValueSanitizer`    | `((input: string) => string)`                                                                                                                                                                                     | no       | —       | Rewrites typed text before filtering and creating. Sees the whole text per keystroke — don't `trim()`.                                                                                                                                                                                         |
+| `isItemEqualToValue`     | `((itemValue: string, value: string) => boolean)`                                                                                                                                                                 | no       | —       | Custom comparison logic used to determine if a combobox item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison.                                                                                 |
+| `isLoading`              | `boolean`                                                                                                                                                                                                         | no       | —       | Options still arriving; doesn't disable — pass `disabled` where the user must wait.                                                                                                                                                                                                            |
+| `items`                  | `readonly (string \| Group<string>)[]`                                                                                                                                                                            | no       | —       | Read as immutable: pass a new array to change it; one mutated in place is not re-filtered.                                                                                                                                                                                                     |
+| `itemToChipColor`        | `((item: string) => "gray" \| "gray-darker" \| "gray-inverse" \| "green" \| "green-darker" \| "green-inverse" \| "blue" \| "blue-inverse" \| "red" \| "orange" \| "orange-inverse" \| "amber" \| ... 9 more ...)` | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `itemToChipLabel`        | `((item: string) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `itemToDisabled`         | `((item: string) => boolean)`                                                                                                                                                                                     | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `itemToIcon`             | `((item: string) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `itemToLabel`            | `((item: string, query: string) => ReactNode)`                                                                                                                                                                    | no       | —       | Row and chip content (unless `itemToChipLabel`), `itemToStringLabel` by default. - `query` is the search text, for `MarkedText`; a chip gets `''`.                                                                                                                                             |
+| `itemToLocked`           | `((item: string) => boolean)`                                                                                                                                                                                     | no       | —       | A selected item no press removes: looks disabled, still highlights for `renderAside`.                                                                                                                                                                                                          |
+| `itemToStringLabel`      | `((itemValue: string) => string)`                                                                                                                                                                                 | no       | —       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for display in the input. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. |
+| `itemToStringValue`      | `((itemValue: string) => string)`                                                                                                                                                                                 | no       | —       | When the item values are objects (`<Combobox.Item value={object}>`), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop.      |
+| `label`                  | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `maxVisible`             | `number`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `onAsideOpenChange`      | `((open: boolean) => void)`                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `onOpenChange`           | `((open: boolean) => void)`                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `onQueryChange`          | `((query: string) => void)`                                                                                                                                                                                       | no       | —       | Reports the sanitized query, on mount too. Notification only — the control owns the text.                                                                                                                                                                                                      |
+| `pinnedChipLabels`       | `ReactNode[]`                                                                                                                                                                                                     | no       | —       | Non-removable chips ahead of the values, outside `maxVisible` and absent from `value`.                                                                                                                                                                                                         |
+| `query`                  | `string`                                                                                                                                                                                                          | no       | —       | The search text, typed elsewhere (a chat composer): with `anchor`, the popup has no search. The host forwards ArrowUp, ArrowDown, Enter and Escape to the `combobox` input it renders.                                                                                                         |
+| `queryToCreateLabel`     | `((query: string) => ReactNode)`                                                                                                                                                                                  | no       | —       | Words the create row. Receives the values it adds, trimmed and re-joined — not the entry as typed.                                                                                                                                                                                             |
+| `queryToCreateValue`     | `((query: string) => string)`                                                                                                                                                                                     | no       | —       | Projects one entered value into an item. Called once per trimmed part of a split entry.                                                                                                                                                                                                        |
+| `renderAside`            | `((highlighted: MultiComboboxHighlighted<string, Group<string>>) => ReactNode)`                                                                                                                                   | no       | —       | An inspector beside the list about the last highlighted row; `null` before any. Hidden while the popup is under 40rem wide.                                                                                                                                                                    |
+| `renderChips`            | `((values: string[]) => ReactNode)`                                                                                                                                                                               | no       | —       | Replaces the default chips; the chip props, `maxVisible` included, are then ignored.                                                                                                                                                                                                           |
+| `required`               | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `requiredMark`           | `RequiredMark`                                                                                                                                                                                                    | no       | —       | Gated by `required`: `'required'` shows `*` only if required, `'optional'` shows `(optional)` only if not, `'hidden'` neither. Defaults to `'required'`.                                                                                                                                       |
+| `selectableGroups`       | `boolean`                                                                                                                                                                                                         | no       | —       | A group's row selects its matching enabled items. The row itself never enters `value`.                                                                                                                                                                                                         |
+| `sizing`                 | `"small" \| "medium" \| "default" \| null`                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `tooltip`                | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `variant`                | `"primary" \| "secondary" \| null`                                                                                                                                                                                | no       | —       |                                                                                                                                                                                                                                                                                                |
+| `virtualized`            | `boolean \| "auto"`                                                                                                                                                                                               | no       | —       | Puts only the rows in view into the DOM: `'auto'` past 30 options, grouped or not; `true` always.                                                                                                                                                                                              |
 
 ### `field.CheckboxField`