@keboola/design 11.4.0 → 11.5.0

package/AGENTS.md

@@ -93,8 +93,12 @@ This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-A
 
 **Never** build custom label + input combinations — compose `Label` + `FormGroup.TextInput` + `FormGroup.Help` inside `FormGroup`.
 
+**`Select` and `Select.Trigger` will not compile without an accessible name** — one of `aria-label`, `aria-labelledby`, or an `id` is required (the JSDoc on the prop says why). Pass `id` and point a `<Label htmlFor>` at it where the field has a visible label, `aria-labelledby` where that label is some other node, and `aria-label` for a bare control — a toolbar filter, a repeated row. `field.SelectField` needs none of the three: `FieldItem` owns the label and hands the control its `id`.
+
 `FileUpload` composes `FileUpload.DropZone` (the dashed box, owning the drag / error visuals) with `FileUpload.FileList` (selected files; `invalid` tints the rows). It deliberately ships **no** rejection copy — the wording is product copy, so read the current rejections with `useFileUploadRejections()` inside `FileUpload` and write the sentence yourself. Reach for `useFileDropTarget` only when there is no box to render: it returns `getRootProps()` / `isDragActive` for an affordance you style, and `noClick` / `noKeyboard` keep an already-interactive subtree (a composer, a form) from opening the file dialog on every click.
 
+**`InputGroup.Addon` (`align="inline-start"` / `"inline-end"`) keeps its own content width** — it no longer gives up space to the input, so a badge or a rendered selection stays fully visible instead of being squeezed to an ellipsis. Bound long, caller-controlled content yourself (a `max-w-[…] overflow-hidden` on the addon) if it isn't a fixed-size icon or button. `InputGroup`'s padding/sizing rules reach any descendant `input`/`textarea`, not just a direct child, so a consumer that wraps the input in its own layout (chips, an overlay) picks up that padding automatically — cancel it with `!px-0`/`!py-0` where the wrapping layout already owns its own edge padding (see `MultiCombobox`).
+
 ### Status surfaces
 
 | Use                           | When                                                  |
@@ -176,6 +180,7 @@ The config holds resolved `rgb(…)` strings, not `var()` references — vega do
 | Tailwind classes | All ad-hoc layout: `tw:flex tw:flex-col tw:gap-4`, `tw:grid …`, `tw:p-6`                                                     |
 | `AppShell`       | App-root shell that follows the active brand (sidebar vs top-nav)                                                            |
 | `PageLayout`     | Top-level page shape: header, tabs, toolbar, content, footer                                                                 |
+| `AuthLayout`     | Signed-out page frame: sign-in, sign-up, password reset, MFA, project picker                                                 |
 | `PageToolbar`    | Index-page toolbar: search + filters / sort / actions / view + chips row                                                     |
 | `Card`           | Semantic content surface with `Card.Header` / `Card.Title` / `Card.Content` slots                                            |
 | `Sidebar`        | App-shell left navigation rail (host inside `AppShell.Sidebar`)                                                              |
@@ -248,7 +253,153 @@ The `label` prop implies `orientation="horizontal"` — labels are not rendered
 | `CodeEditor`      | Generic code editing (JSON, YAML, shell)                      |
 | `SqlEditor`       | SQL editing (syntax + autocomplete)                           |
 
-`Select` is wrong above ~10 items — use `Combobox`. `CodeEditor`/`SqlEditor` load the full CodeMirror bundle and ship from the `@keboola/design/editors` subpath (not the root); reserve for real code editing.
+`Select` is wrong above ~10 items — use `Combobox`. How richly the **selected** value has to render decides nothing here: both controls carry a rich selection (see below), so a short enum whose selection is a badge is still a `Select`. `CodeEditor`/`SqlEditor` load the full CodeMirror bundle and ship from the `@keboola/design/editors` subpath (not the root); reserve for real code editing.
+
+#### Clear affordance
+
+| Control                      | Clear affordance                                          |
+| ---------------------------- | --------------------------------------------------------- |
+| `Combobox` / `MultiCombobox` | Default on; `allowClear={false}` to withhold it           |
+| `Select`                     | None — add an explicit "None" / "All" item to the `items` |
+
+Withhold it where clearing must not be one click away: a required single-value field, or a control
+whose empty state the surrounding form cannot represent. The button only mounts once there is a
+value, so an empty control renders identically either way. A **required multi** field keeps
+clear-all — the chips are individually removable, so the empty state is reachable regardless and
+withholding the button removes convenience without preventing anything. That is why the schema-driven
+`SelectWidget` derives `allowClear={!required}` while `MultiComboboxField` does not.
+
+#### Chip content in a `MultiCombobox`
+
+| Use                             | When                                                                     |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| `itemToChipLabel`               | Anything one chip contains — plain text, a link, an action of its own    |
+| `itemToChipColor`               | A `Badge` colour per value (deleted, linked, stale)                      |
+| `pinnedChipLabels`              | A chip the control shows but the user does not own — nothing in `value`  |
+| `renderChips` + `Combobox.Chip` | One node standing for the whole selection, or a chip count ≠ value count |
+
+`itemToChipLabel` returns a `ReactNode`, and a chip yields Enter and Space to interactive content
+inside it — so a link or a button in a chip is not a reason to reach for `renderChips`. Reach for
+the slot only when no per-value accessor can express the area: it replaces the whole thing, so
+`maxVisible` and its `+N` chip become the caller's job too.
+
+#### One creatable entry, several values
+
+A `MultiCombobox` with `allowCreate` splits a created entry on `createSeparator`, so a pasted list
+becomes one chip per value. It is **on by default** (`','`) — the paste is the reason a multi
+control is creatable at all, and a chip literally named `id1, id2, id3` is never what the user
+meant.
+
+| Use                                                   | When                                                                         |
+| ----------------------------------------------------- | ---------------------------------------------------------------------------- |
+| the default (`','`)                                   | Values that arrive as a list — tags, column names, primary keys, ids, emails |
+| `createSeparator={';'}`, `createSeparator={/[\s,]+/}` | Another convention — an Outlook address list, whitespace-separated ids       |
+| `createSeparator={null}`                              | A value can itself contain the separator — free text, a sentence, a name     |
+
+Each value is trimmed and the empty ones dropped, and repeats within one entry collapse. **The row
+is offered whenever the entry adds anything to the selection, and names exactly those values** — a
+value naming an existing item counts, because committing selects that item rather than minting a
+twin of it. It withholds itself only when the selection already holds every value in the entry, or
+when a single value names an item — that item's own row is the affordance there.
+
+`queryToCreateLabel` is handed those values, re-joined with the entry's own separator, so the row
+can neither name a value it drops nor stay silent about one it selects. `queryToCreateValue` is
+called once per value, which is where a per-value projection or normalisation belongs, and
+`canCreate` gates each value rather than the whole entry — so a pasted list keeps the values whose
+format passes and drops the rest, and a value naming an existing item never reaches the gate
+because committing selects that item instead of minting one. `Combobox` has no counterpart: one
+entry there can only be one value.
+
+#### How richly the selected value renders
+
+| Use                                | When                                                                                |
+| ---------------------------------- | ----------------------------------------------------------------------------------- |
+| `Select` — `label`                 | The trigger shows the item's `label` node as-is, Radix mirrors it from the row      |
+| `Select` — `icon` / `hint`         | The **row** carries more than the trigger should — both sit outside the mirror      |
+| `Combobox` — `itemToStringLabel`   | The selection is plain text, which is also the input's value and the search subject |
+| `Combobox` — `itemToSelectedLabel` | The closed control needs a badge, an icon or a secondary line                       |
+
+The three `Combobox` label accessors answer three different questions and are free to disagree:
+`itemToLabel` styles the open list's rows (and takes the query, for `MarkedText`),
+`itemToStringLabel` is the input's text, and `itemToSelectedLabel` is what the closed control shows.
+The last one is decoration in front of the input, not a replacement for it — the input keeps the
+string label as its value, so the control still reports its selection to a screen reader, and a
+query dissolves the node and hands the row back to the search. Drawing the selection yourself in
+`prefix` with `value` pinned to `null` gets the same picture and costs exactly that accessible value.
+
+#### Who owns the typed query
+
+The control owns its input text, always — a selection snaps it back to that item's label, and
+creating or clearing a value rewrites it. Neither combobox takes a controlled `inputValue`, because
+a parent holding it would have to reproduce all three of those writers. Two hooks cover what a call
+site actually needs from the query:
+
+| Use                   | When                                                                          |
+| --------------------- | ----------------------------------------------------------------------------- |
+| `inputValueSanitizer` | The typed text has a character set — a bucket, table or column identifier     |
+| `onQueryChange`       | The owner needs the query itself — a server-side search, an option order      |
+| `canCreate`           | The value has a **format** the user must get right; the gate is not a rewrite |
+| `queryToCreateValue`  | Only the created item needs shaping, not the text the user sees while typing  |
+
+The last two are about the **value**, not the text: reach for them when the query is fine as typed
+and only what it becomes needs gating or shaping.
+
+#### Search semantics — `filter`
+
+`Combobox` and `MultiCombobox` match the typed query as **one substring** of the item's label, so
+`frankfurt europe` finds nothing in a list holding `Europe (Frankfurt)`. Any multi-word label wants
+one of these instead:
+
+| Use                                             | When                                                                 |
+| ----------------------------------------------- | -------------------------------------------------------------------- |
+| `filter={filterByWords}`                        | The searchable text **is** the label — every multi-word label        |
+| `filter={(item, q) => matchByWords([a, b], q)}` | Something the label omits is searchable too (an email behind a name) |
+
+#### Blank values — `''` and `' '`
+
+Some predicates are about blankness itself: "this Storage column equals the empty string" versus
+"equals a single space". Whether a control can carry those depends on the primitive under it.
+
+| Control         | `''` / `' '` as a value                                                                                                                                                                  |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MultiCombobox` | **Genuine values** — the selection shows as chips, so a blank one is nameable                                                                                                            |
+| `Combobox`      | Genuine values; add `itemToSelectedLabel={namedLabel}` to name a blank selection in the closed control                                                                                   |
+| `Select`        | **Impossible** — Radix reads an empty root value as "nothing selected", so an item carrying it renders a blank trigger. Use a named sentinel item (`'none'`) and map it at the call site |
+
+`withBlankValues` offers both blanks ahead of a value list and collapses duplicates — a column's
+distinct values can already hold a blank, and two `Object.is`-equal rows both report `aria-selected`
+and toggle each other.
+
+```tsx
+import { MultiCombobox, withBlankValues } from '@keboola/design';
+
+<MultiCombobox
+  allowCreate
+  items={withBlankValues(columnValues)}
+  value={values}
+  onValueChange={setValues}
+  placeholder="Add a value"
+/>;
+```
+
+**Rows and chips name a blank; the input does not.** A row or a chip rendering as nothing is
+indistinguishable from an empty control, so the display accessors name blanks `[empty string]`,
+`[space character]`, and `[whitespace]` for anything else whose text is all whitespace — only the
+first two read distinctly. `itemToStringLabel` is left alone on purpose: it is the item's string
+identity, the default search text **and** the input's accessible value (see `toLabel`). Two
+consequences at the call site:
+
+- Typing never reaches a blank row, whatever `allowCreate` says, because the search text is the raw
+  value. Clear the query to pick one. `allowCreate` cannot create a blank either — it trims the
+  query — so fixed rows are the only way in.
+- Naming a blank selection in a closed `Combobox` is `itemToSelectedLabel`'s job, **not**
+  `itemToStringLabel`'s: the slot renders a node in front of the input and leaves identity, search
+  and the accessible value intact.
+
+Overriding a display accessor — `itemToLabel`, `itemToChipLabel`, `itemToSelectedLabel`, or the
+`renderChips` slot, which replaces the chip area wholesale — composes `namedLabel` rather than
+retyping the labels. `allowSelectAll` needs nothing: it commits the whole item set, blanks along
+with it.
 
 ## Composition recipes
 
@@ -497,6 +648,20 @@ Both router wirings (TanStack Router, and a custom named router) are in [`RECIPE
 />
 ```
 
+**Action picker `Select`** — a `Select` whose options are actions ("convert all names to UPPERCASE") rather than a value the form holds. Pin `value` to `''`: the trigger keeps showing its `placeholder`, and every pick fires, including the same one twice running.
+
+```tsx
+<Select
+  aria-label="Convert all column names"
+  placeholder="Convert All Names To"
+  value=""
+  items={CONVERSIONS}
+  onValueChange={renameEveryColumn}
+/>
+```
+
+Radix routes the root value through `useControllableState`, which calls `onValueChange` only when the picked value differs from the current one — on the uncontrolled path (no `value` at all) it compares against the previous internal state, so leaving `value` off does **not** help. Storing the last action and feeding it back makes re-picking it a silent no-op, which matters whenever the action is still worth repeating: the user edited one of the renamed columns by hand and wants the bulk rename applied again.
+
 **Pinned chip in a `MultiCombobox`** — a chip the control shows but the user does not own (a set of packages the runtime already ships, a role every member has). `pinnedChipLabels` is a render-only slot, so nothing enters `value`: there is no sentinel to strip on save and the control's own counting never sees a non-item.
 
 ```tsx
@@ -510,6 +675,31 @@ Both router wirings (TanStack Router, and a custom named router) are in [`RECIPE
 
 Don't fake one by prepending a sentinel to `value` — that costs the caller a strip on every change plus a label branch, and leaks the sentinel into the primitive's counting.
 
+**Selection summarised in a `MultiCombobox`** — `renderChips` renders the chip area from the
+selected values, for the shape no per-value accessor can express: one node standing for the whole
+selection. `Combobox.Chip` builds a removable chip for the values that still get one, and Base UI
+removes the chip at an index, so render one per entry of `value`, in order.
+
+```tsx
+<MultiCombobox
+  items={tables}
+  value={selected}
+  onValueChange={save}
+  renderChips={(values) =>
+    values.length === 1 ? (
+      <Combobox.Chip>{labelOf(values[0])}</Combobox.Chip>
+    ) : (
+      <Badge color="blue">{values.length} tables selected</Badge>
+    )
+  }
+/>
+```
+
+A chip that merely holds a link or an action of its own does not need this — `itemToChipLabel`
+takes the node, and the chip lets it have the keyboard.
+
+**Select All in a `MultiCombobox`** — `allowSelectAll` means the **whole item set**, never the filtered one, so the row hides itself as soon as a query narrows the list. Don't reach for it to mean "select the matches" — a filtered bulk select needs its own labelled affordance stating the count, not a row whose meaning changes with the input.
+
 **Sheet** — use `Sheet.Header title="…" description="…"` for a styled title + close icon; do **not** hand-roll with the raw `Sheet.Title`, which renders an unstyled `<h2>`. `Sheet.Body` provides horizontal padding only (`tw:px-4`) — add your own vertical rhythm/gap:
 
 ```tsx

package/CHANGELOG.md

@@ -1,5 +1,363 @@
 # @keboola/design
 
+## 11.5.0
+
+### Minor Changes
+
+- `Markdown` draws a fenced `flint` block as a chart, the way it already draws `mermaid` as a diagram. `flint-chart` is admitted as an alias. `DIAGRAM_LANGUAGES` is exported for callers that stream an answer in and have to leave a fence that is still open as plain code. A spec is refused before anything compiles it if it carries a key that would fetch or evaluate — `url`, `expr`, `signal`, `signals`, `params`, or any `*Expr` property — and the reader is shown the source instead of a chart. Where flint keys a map by column name — `data.values` rows, `semantic_types`, `field_display_names` — the key is the column's, not the spec's, so a chart of landing-page URLs still draws.
+
+- `clampPercentage` and `formatPercentage` are exported from `AIKit`, so a usage percentage is clamped and formatted in one place. `clampPercentage` normalizes non-finite input to 0, which the app copies it replaces did not — a `NaN` percentage no longer reaches a `Progress` value, whose indicator is unclamped.
+
+- `AuthLayout` floors the form column in the split geometry, and takes `asideCollapse`; `BrandLogo` takes `label`
+  - The split's form track is now `minmax(<column + gutters>, 1fr)` instead of `1fr`, so between `lg` and 1536px (`width="form"`) or 1824px (`width="wide"`) it stops handing the column less than `width` asks for — a two-field row there measured ~180px per field.
+  - The form column no longer carries `min-h-svh` of its own in the split geometry: the grid root has it and the rows stretch, so `asideCollapse="stack"` no longer reserves a whole empty screen under a short card.
+  - `asideCollapse="stack"` keeps the `aside` below `lg`, in its `asideSide` order, for a page whose pitch has to survive a phone. The default stays `hide`.
+  - `BrandLogo label` names the logo for a screen reader instead of the brand's registry `name` — a link around the mark otherwise announces the picker's disambiguating suffix (`Keboola (V2)`).
+
+- `Combobox` and `MultiCombobox` are now clearable by default — `allowClear` defaults to `true`.
+
+  Consumer-visible behaviour change. The clear button only mounts once there is something to clear
+  (single: a selection; multi: at least one chip), so an empty control renders exactly as before and
+  individual chips stay removable regardless. 16 existing call sites across `kbc-ui`,
+  `developer-portal` and `theme-generator` gain the affordance; the 10 that already pass `allowClear`
+  are unaffected, as are the 4 adder-pattern comboboxes pinned to `value={null}` (nothing is ever
+  selected, so the button never mounts).
+  - Pass `allowClear={false}` where clearing must not be one click away — a required field, or a
+    control whose empty state the surrounding form cannot represent.
+  - `RjsfSchemaEditor`'s `SelectWidget` and `DynamicSelectWidget` now both derive it from the schema
+    (`allowClear={!required}`), so a schema-required field stays non-clearable. `DynamicSelectWidget`
+    passed no `allowClear` before, so its non-required fields gain the button as intended.
+  - `MultiComboboxField` deliberately does **not** derive it: a required multi field's chips are
+    individually removable, so withholding clear-all prevents nothing.
+  - Radix `Select` still has no clear affordance; model "no selection" as an explicit item there.
+
+  `allowSelectAll` is unchanged (still `false`) — see UT-5422.
+
+- `Combobox` and `MultiCombobox` take `inputValueSanitizer` and `onQueryChange`
+  - `inputValueSanitizer` rewrites what the user types before the control adopts it, so an identifier field (a bucket, table or column name) can keep the query to its own character set. It runs on typing only, never on the selection's label.
+  - `onQueryChange` reports the query the list filters by, sanitizer already applied — for an owner driving a server-side search, an option order, or the name a create form opens with. It goes empty once the input shows the selection's label, and reports from the mount render on, so a search driven by it needs no first fetch of its own.
+  - Neither hands the text over: the control keeps owning it, so there is still no controlled `inputValue`.
+
+- `Combobox` takes `itemToSelectedLabel` — how the selection renders once the popup closes.
+
+  Additive. Left unset the closed control shows `itemToStringLabel`'s text, exactly as before.
+  - The node renders ahead of the input and the input's own text turns transparent behind it, so the
+    selection reads once. Typing dissolves it and hands the row back to the query.
+  - The input keeps the string label as its **value**, so the control still reports its selection to a
+    screen reader. That is the reason to reach for this over drawing the selection into `prefix` with
+    `value` pinned to `null` — same picture, and the input has no accessible value.
+  - The three label accessors stay independent: `itemToLabel` styles the open list's rows (and takes
+    the query, for `MarkedText`), `itemToStringLabel` is the input's text and the search subject.
+
+  `Combobox` also now tracks an uncontrolled selection (`defaultValue`, or no `value` at all) the same
+  way it tracks a controlled one. Beyond feeding the new accessor, that fixes the list collapsing to
+  the selected item after an uncontrolled pick: as with a controlled combobox, reopening now browses
+  the whole list instead of filtering by the selection's own label.
+
+  Radix `Select` needs nothing here — its trigger already mirrors the item's `label` node, and `icon`
+  / `hint` sit outside that mirror for a row that carries more than the trigger should.
+
+- Add `AuthLayout` — the signed-out page frame (sign-in, sign-up, password reset, MFA, project picker).
+
+  Compound: `AuthLayout.Header` (the active brand's mark beside the `productName` it is given, or your own lockup as children; takes `actions`), `AuthLayout.Content`, `AuthLayout.Footer`. `width` picks the column (`form` 28rem | `wide` 34rem); passing `aside` switches the page to the split geometry, with `asideSide` choosing the panel's side.
+
+- `Select` requires an accessible name — `aria-label`, `aria-labelledby`, or an `id` — and forwards
+  `aria-labelledby` to the trigger, which it previously dropped.
+
+  ```tsx
+  // A visible label — point it at the control.
+  <Label htmlFor="stage">Stage</Label>
+  <Select id="stage" items={STAGES} value={stage} onValueChange={setStage} />
+
+  // A bare control (toolbar filter, repeated row) — name it directly.
+  <Select aria-label="Rows per page" items={ROWS_PER_PAGE} value={rows} onValueChange={setRows} />
+  ```
+
+  The trigger is a `role="combobox"` button, which is not a name-from-content role: neither the
+  selected item's label nor the `placeholder` names it, so a `Select` with none of the three reached
+  a screen reader as an unnamed control.
+  - The requirement sits on `Select.Trigger` as well, so the compound route is covered too. Passing
+    more than one route is still allowed — an `id` for the `<Label htmlFor>` plus an `aria-label`
+    that overrides it is a legitimate pairing.
+  - An `id` alone still names nothing: it counts only when a `<label for>` points at it, and no type
+    can check that pair.
+  - `field.SelectField` needs none of the three — `FieldItem` owns the label and hands the control
+    its `id`. It no longer accepts `aria-label` / `aria-labelledby`, which nothing passed: a name
+    from the call site could only disagree with the label the field already renders.
+
+- `MultiCombobox` takes `canCreate`, the gate `Combobox` already had. It runs on the typed query once
+  that query matches no item and nothing already selected, and returning `false` hides the create row
+  so the empty state shows instead of an "Add …" row the caller would only reject afterwards.
+
+  The case it is for is a free-form value with a format the caller can state — a column name a
+  JSON-Schema `pattern` constrains, an email address. Without it a multi creatable control had no way
+  to say no before the value was in the selection.
+
+  The Select All row no longer leaks into the chips. Base UI holds it in `value` like any other item,
+  so a complete selection grew a third chip and handed the row's own entry to the caller's
+  `itemToChipLabel` / `itemToLabel` as if it were a value — a control that projects its items (an id
+  to a label) then rendered that object as a child and React threw. The chip area now filters the
+  control's internal entries out before anything reaches a caller callback. The row is also gone
+  entirely when there is nothing to select all of, where `0 === 0` had read as "everything is
+  selected".
+
+  `itemToLabel` defaults to `itemToStringLabel` rather than to the built-in label reader, so a control
+  whose items are ids with the label beside them states the projection once instead of passing the
+  same function twice. Passing both still works, and is what a row richer than the input's own text
+  wants.
+
+- `MultiCombobox` takes `renderChips` — a slot that renders the chip area from the selected values, for the shape no per-value accessor can express: one node standing for the whole selection, or a chip count that is not the value count. `Combobox.Chip` is exposed as the removable-chip building block a custom render composes from.
+
+  A chip now also yields Enter and Space to interactive content inside it, so `itemToChipLabel` can return a link or an action and have it activate from the keyboard.
+
+- `MultiCombobox` accepts `isItemEqualToValue` and forwards it to Base UI, as `Combobox` already did.
+  Without it Base UI matches the selection against `items` by reference, so a control fed object items
+  lost its selection the moment the store handed back structurally equal items with fresh references —
+  the workaround being a caller-side `string[]` of ids plus an id→label projection.
+
+  Both controls now build the comparer from one shared factory, with two consequences. An injected
+  "Select All" or create row equals only a sentinel of the same marker, so a caller item whose `value`
+  is the literal `__select_all__` is a plain item rather than the Select All row. And the comparer
+  keeps its identity between renders, where an unmemoized one re-rendered every option row on each
+  render of the control.
+
+- `MultiCombobox` with `allowCreate` splits a created entry into one value per comma, and takes
+  `createSeparator` to change or switch off the split.
+
+  Consumer-visible behaviour change, on by default. Pasting `id1, id2, id3` into a creatable multi
+  control added one chip literally named `id1, id2, id3`; it now adds three. The paste is the reason a
+  multi control is creatable at all — tags, column lists, primary keys, allowed component ids, email
+  lists — so the split is the default rather than a prop each site has to remember. `Combobox` is
+  unchanged: one entry there can only be one value.
+  - `createSeparator` takes a string or a `RegExp` for another convention (`';'` for an Outlook
+    address list, `/[\s,]+/` where a value can never contain a space), and `null` where a value can
+    itself contain the separator and one entry must stay one chip.
+  - Whitespace is deliberately not part of the default — tags and column names contain spaces, and
+    every value is trimmed anyway, so `id1, id2` needs nothing but the comma.
+  - `queryToCreateValue` is called once per value, each already trimmed, so a per-value projection or
+    normalisation needs no change. This is also where the legacy wrapper's `trimMultiCreatedValues`
+    lands.
+  - `canCreate` gates each value rather than the whole entry, so a pasted list keeps the values whose
+    format passes and drops the rest instead of being rejected wholesale. A value naming an existing
+    item never reaches the gate — committing selects that item rather than minting one.
+  - A value repeated inside one entry, or one the selection already holds, is added once. A value
+    naming an existing item selects that item rather than minting a twin standing for the same thing.
+  - The row is offered whenever the entry adds anything to the selection, and withholds itself only
+    when the selection already holds every value, or when a single value names an item (that item's
+    own row is the affordance). That is why an entry naming only existing items keeps the row: the
+    substring filter matches no item for a multi-value entry, so the row is the only thing that can
+    act on such a paste.
+  - `queryToCreateLabel` now receives the values committing the row will add, re-joined with the
+    entry's own separator, rather than the entry as typed — so the row can neither name a value it
+    drops nor stay silent about one it selects. For a single-value entry that string is the entry
+    itself, so an existing label reads exactly as before.
+
+- Add `AnswerActions` to the AI Kit: the copy-and-vote row for a finished agent answer.
+  - Always rendered rather than revealed on hover, so it exists for a reader without a pointer.
+  - `aria-pressed` says which vote is recorded, and both buttons stay focusable — a vote can be
+    changed but not withdrawn.
+  - No copy button when `copyText` is empty: a turn that produced only tool calls has nothing to
+    take away.
+  - The recorded vote and the write stay with the caller; the two chats vote against different
+    endpoints.
+
+- `useSidebar(side)` now exposes `setFill(fill: boolean)` alongside `toggleFill()`.
+
+  `toggleFill` requires the caller to know the current value, so two callers in one commit read the
+  same stale flag and undo each other, and a caller whose view of the layout disagrees with the flag
+  skips the change entirely. `setFill` states the value it wants, so it is idempotent. `toggleFill`
+  is unchanged and still the right call for a user-facing toggle control.
+
+- `UsageStats` accepts `open` / `onOpenChange`, so a caller can hold the hover card open past a pointer leave — needed when the card contains a popover of its own.
+
+### Patch Changes
+
+- `PlanApproval`, `CollapsibleStepHeader` and `UsageStatsRing` follow the active colour scheme and
+  brand. All three pinned fixed grey and white values, so the plan-approval card rendered as a light
+  card with near-black text on a dark page, and ignored a customer brand's own surface tokens in
+  either scheme. They now consume the semantic tokens throughout: the card's shell is the recessed
+  `background` tier, its plan body, action bar and change-request form lift off it on `card`, and each
+  tier paints its own foreground so no surface inherits ink from whatever rendered it. Step counts
+  read as `muted-foreground`, dividers as `border`, and the usage ring's track as a muted mark.
+
+  A dismissed step's icon takes its colour from the step's own variant rather than a pinned grey, so
+  it now matches the muted label beside it; a failed step keeps the destructive tone. The card's inner
+  dividers are a touch more visible in light mode, since one shared border token now draws them and
+  the frame alike.
+
+- AIKit collapsibles move instead of popping: `PlanApproval`'s plan body and `AnswerSummary`'s answers ease open and closed on `grid-template-rows`, `AnswerSummary` reports a manual toggle through `onExpandToggle`, and `ToolCallStatusHeader` turns one chevron rather than swapping the up and down glyphs.
+
+- `AnswerSummary` collapses flush against its header: the spacing before the answers lives inside the collapsible body, so the closed state no longer keeps a 16px gap under the header.
+
+- `Combobox` / `MultiCombobox` hold `''` and `' '` as genuine values: `withBlankValues`, `namedLabel`.
+
+  "This column equals the empty string" and "equals a single space" are real filter predicates against
+  Storage data. Base UI keys "is something selected" off `value != null` rather than truthiness, so a
+  blank string already round-trips through `onValueChange` verbatim and keeps its clear affordance —
+  no sentinel option and no mapping on save. What was missing was the display half: a blank row and a
+  blank chip render as nothing, indistinguishable from an empty control.
+  - `withBlankValues(values)` offers both blanks ahead of a value list and collapses duplicates. A
+    column's distinct values can already hold one, and two `Object.is`-equal rows both report
+    `aria-selected` and toggle each other.
+  - **Rows and chips** name a blank — `[empty string]`, `[space character]`, and `[whitespace]` for
+    anything else whose text is all whitespace. `namedLabel` exposes the rule so an `itemToLabel` /
+    `itemToChipLabel` / `renderChips` override can keep it.
+  - **`itemToStringLabel` is deliberately not named.** It is the item's string identity, the default
+    search text and the input's accessible value, and Base UI counts `''` as a selection — naming it
+    would paint text over the placeholder wherever "nothing selected" is spelled `''`. Typing
+    therefore never reaches a blank row, and naming a blank selection in a closed `Combobox` is
+    `itemToSelectedLabel`'s job.
+  - `allowCreate` cannot create a blank: it trims the typed query, so fixed rows are the only way in.
+  - Radix `Select` is unaffected and still cannot carry a blank — it reserves `''` for its own empty
+    state. The split is documented in `AGENTS.md`.
+
+- `Combobox` and `MultiCombobox` popups register in Radix's dismissable-layer stack, so Escape closes
+  the popup and leaves the surrounding surface alone. Base UI portals the popup out of the DOM, so a
+  `Modal`, `Sheet` or `Popover` around it still counted itself as topmost and took the keystroke — a
+  combobox in a modal form lost the whole half-filled form on the key that was meant to dismiss its
+  own list. The popup now sits above that surface as a layer of its own; Base UI still owns the
+  dismissal itself, and Escape on a closed popup reaches the surface as before.
+
+- `Combobox`'s `itemToSelectedLabel` node now paints over the input's own content box instead of
+  sitting beside it as a flex sibling. Previously the two boxes shared one row, so the caret and text
+  selection lived roughly a badge-width past where the visible label ended.
+
+- `Combobox` stores the text the user typed rather than the text it displays, and derives the input's
+  value, the search query and the rich selected label from that one piece of state.
+
+  The two meanings did not fit in one variable, so the difference was reconstructed around it: an
+  effect snapping the input back to the controlled value's label, a counter re-triggering that effect
+  when `value` stayed put, a string comparison standing in for "this is a selection, not a query", and
+  a ref reconstructing why the popup had closed. `typedText: string | null` says it directly, with
+  `null` for "nothing typed, showing the selection".
+  - Only Base UI's `input-change` reason writes to it. Every other reason it reports — an item press,
+    a clear, the label it syncs back on unmount — means "show the selection", which `null` already
+    says. Its sync-back is a write to ignore rather than adopt: it stringifies Base UI's own selected
+    value, which for a created item is the internal sentinel and not the value the owner holds.
+  - The state resets the moment the popup starts closing, so a control the user has walked away from
+    shows what its value says. Base UI's own sync-back cannot carry that: it skips the write whenever
+    the input's text already matches the label, which a query edited back to the label reaches.
+  - Whitespace alone is never adopted as a query. Base UI gates opening the popup on the trimmed
+    text, so a control that took it would sit closed showing text its value does not say, with no
+    close to discard it.
+  - "Showing the selection" is the input's text matching the selection's label, not merely nothing
+    having been typed. A query edited back to the label lands on the same screen as never having
+    typed: the rich `itemToSelectedLabel` node returns and the list stays browsable rather than
+    narrowing to the item already chosen. Base UI's own `shouldBypassFiltering` covers only a fresh
+    open — its `queryChangedAfterOpen` flips on the first keystroke and clears on close, never when
+    the text returns to the label.
+
+  One behaviour change: a `value` arriving from elsewhere while the user is mid-query no longer yanks
+  the text away on the keystroke. The query stands until it is committed or discarded, and the new
+  label shows when the popup closes.
+
+- `Combobox` / `MultiCombobox` get a shared word-by-word `filter`: `filterByWords` and `matchByWords`.
+
+  Both controls match the typed query as one substring of the label, so `frankfurt europe` finds
+  nothing in a list holding `Europe (Frankfurt)`. `filter={filterByWords}` requires every word of the
+  query to occur somewhere in the label, in any order, ignoring case, matching by containment;
+  `matchByWords([a, b], query)` applies the same rule to texts the label does not show — an email
+  behind a name, a table id behind a display name.
+  - `filterByWords` searches **only** what the control displays, so a filter cannot match an id the
+    user cannot see. Extra fields are named explicitly through `matchByWords`.
+  - Comparison is a lowercased `includes`, not Base UI's `Intl.Collator` `contains`, so passing
+    either helper trades diacritic-insensitive matching (`Muller` finds `Müller`) for word order.
+  - Defaults are unchanged — both are opt-in per call site.
+
+- `Badge.Button` shows a focus ring. The `focus-visible` block sat on `BadgeRoot`, a `div` that never
+  takes focus, so every clickable badge was keyboard-focusable with no visible focus. The ring is
+  inset, because a badge root clips its overflow.
+
+- `MarkdownEditor`'s plugins, `RjsfSchemaEditor` and `Popconfirm` read their callback props through
+  `useStableCallback` instead of a ref assigned in the component body. Each of those assignments wrote
+  to shared memory during render, where a render React discards can still leave the ref carrying a
+  value that never committed. Two refs in `RjsfSchemaEditor` are gone rather than converted — one
+  wrapped a `useState` setter and one a `useMemo` with no dependencies, both already stable, and the
+  ref only hid that from the dependency list. `ImagePastePlugin` now decides whether to claim paste
+  and drop from a boolean derived from `onImageUpload`, so an editor that gains or loses an uploader
+  re-registers its Lexical commands instead of keeping the first answer forever.
+
+- `RjsfSchemaEditor`'s enum fields have an accessible name: `SelectWidget` and `DynamicSelectWidget`
+  forward rjsf's `id` to their `Combobox`, which is where `FieldTemplate`'s `<Label htmlFor>` points.
+  They were the only built-in widgets dropping it, so a screen reader reported every enum field in a
+  component configuration as an unnamed combobox and clicking the visible label focused nothing. No
+  visual change.
+
+  Still unnamed, and not addressed here: `RadioWidget` and `CodeEditorWidget` forward the `id` to a
+  `div`, which no `<Label htmlFor>` can name — naming those needs `aria-labelledby` from the template
+  and a route into the editor's own textarea.
+
+- Smoother sidebar motion, and a composer a host can refocus.
+  - The sidebar settles instead of sliding linearly: its geometry transitions run
+    `cubic-bezier(0.32, 0.72, 0, 1)` over 420ms, the off-canvas slide is composited, and
+    all of it drops out under `prefers-reduced-motion`.
+  - `Sidebar` takes `mountAfterEnter`: a heavy panel holds its content back until the slide
+    has finished, rather than mounting into the same commit and blocking every frame of it.
+    Ignored under reduced motion, where there is no transition end to wait for.
+  - `Workbench` marks its two boxes `data-workbench-slot="bar"` / `"panel"`, so a floating
+    surface can measure the space the dock leaves. The root's own rect is the bar alone
+    whatever the state, because the panel is absolutely positioned.
+  - `PromptInput` takes `textareaRef`, publishing its textarea so a host that keeps one
+    composer across layout changes can put the caret back. Published from the ref callback,
+    so it still points at the live element after a host layout restructure recreates it.
+
+- `InputGroup.Addon` keeps its own content width instead of giving up space to the input. The input
+  was `w-full`, so as a flex item its basis was the whole row — flexbox then shrank a sibling addon in
+  proportion to that basis, squeezing even a short badge-plus-label selection to an ellipsis well
+  before the field was full. The input is now `flex-1 min-w-0` and `inline-start` / `inline-end`
+  addons ship `shrink-0`; behaviour is unchanged where there is no addon, and every existing addon
+  holds small non-shrinking content (icons, buttons) so this is a no-op for them. `Combobox`'s rich
+  selected-value addon drops the `max-w-[70%] shrink-0` workaround this replaces, keeping only the
+  `max-w-[70%]` bound needed for an arbitrarily long selection.
+
+  `InputGroup`'s padding and sizing rules now target any descendant `input` / `textarea` instead of
+  only a direct child, so a consumer that wraps the input in its own layout keeps its padding without
+  re-implementing the sizing table by hand. `MultiCombobox` drops the manual `px-4 py-1.5` this
+  replaces, and instead cancels the group's rule on its own nested input (`!px-0 !py-0`) since that
+  input shares a row with chips rather than sitting at the group's own edge.
+
+- `Kbd variant="primary"` and `Kbd.Separator` follow the tooltip chrome they render on. `primary`
+  pinned `bg-white/20` + `text-white`, which is only legible on the legacy dark tooltip. Argo's tooltip
+  is a light popover, so every shortcut hint on it — Kai's "New chat", the SQL editor's panel toggles,
+  flow undo/redo, the sidebar nav — painted white keys on white and vanished, leaving the keys'
+  layout width behind as apparent trailing whitespace.
+
+  Both now consume the muted chrome tokens by default and invert to white only under
+  `[data-tooltip-content="true"]`, the attribute the legacy dark tooltip already marks itself with. The
+  legacy rendering is unchanged. Call sites no longer need the `tw:[&>span]:text-white/70` override
+  that forced the separator white — `Kbd.Separator` handles it.
+
+- `MultiCombobox`'s `allowSelectAll` row now hides itself while a query narrows the list. It always
+  selected the whole item set, but stayed visible during filtering — type `prod`, see three matches,
+  click Select All, end up with all two hundred selected, with nothing on screen saying so. Select All
+  keeps meaning "everything"; the reading it can be confused with is no longer on offer. This matches
+  the legacy `react/common/Select` wrapper, which hid its own Select-All row while searching.
+
+- `PageHeader.Detail`'s documented breadcrumb contract now matches how it's actually used: the
+  `breadcrumbs` chain ends at the entity's parent list/hierarchy and never repeats the entity's own
+  name as a final, non-link crumb — it's already the `title` right below. The prop doc, `AGENTS.md`
+  rules and the `Detail` Storybook examples (Bucket, Table, Workspace, Job, Data App, Shared Code, Add
+  Component, Flow) are updated to the same shape.
+
+- A chart or diagram inside a `ThemeScope` now follows the scope's scheme, and a chart in dark mode
+  keeps readable labels.
+
+  `ThemeScope` re-points the colour tokens for its subtree, but a canvas that bakes colours into
+  markup resolved them from `<html>`: `useThemeAttributes` read the root's `data-theme`, and the
+  token resolvers read `getComputedStyle(document.documentElement)`. A chart in a dark-scoped panel
+  therefore drew a white plot with black labels on a dark surface.
+  - `ThemeScope` publishes its resolved scheme and a container carrying its tokens; `useThemeAttributes`
+    prefers both and folds the container into `cacheKey`, so a palette built before the scope answered
+    is not served afterwards.
+  - `createChannelResolver` / `createTokenResolver` (and the vega, flint and mermaid palettes built on
+    them) take the element to read live `--*` values off, defaulting to `<html>` as before.
+  - The flint palette now fills `ink.text` and `ink.structure` from the tokens. Flint's own defaults
+    assume a light canvas, so axis labels and gridlines were near-black in **any** dark context — not
+    only inside a scope.
+  - The root barrel grows ~70 B with the scope context; the size budget moves 344→345 KB.
+
+- `Timeline` draws its connector line, `Navbar` its accent hairline, and the default `Switch` its keyboard focus ring. All three wrote a pseudo-element variant before another variant — `before:group-data-[variant=solid]/timeline:bg-border`, `before:data-[accent=blue]:bg-sidebar-primary`, `before:focus-visible:ring-4` — which Tailwind compiles to a rule that matches nothing, so none of them had ever rendered for any consumer. Twenty rules were dead. Nothing else changes — no markup, no props. A consumer that already renders these components gains the paint it asked for. `check:css` now fails the build on any class that places a variant after a pseudo-element one, `hover:` and `active:` excepted.
+
 ## 11.4.0
 
 ### Minor Changes