@keboola/design 11.3.0 → 11.4.0

package/AGENTS.md

@@ -497,6 +497,19 @@ Both router wirings (TanStack Router, and a custom named router) are in [`RECIPE
 />
 ```
 
+**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
+<MultiCombobox
+  allowCreate
+  value={packages}
+  onValueChange={save}
+  pinnedChipLabels={['Default packages']}
+/>
+```
+
+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.
+
 **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
@@ -535,6 +548,10 @@ Layer-0 colour usage splits into three buckets.
 
 A border **width** utility carries no colour of its own — a lone `tw:border` / `tw:border-t` / `tw:border-2` paints the element's _text_ colour, a near-black frame where a light-grey rule belongs. Pair every width with a colour: `tw:border tw:border-border` for chrome, `tw:border-input` on form controls. `pnpm test:stories` fails on any story that ships a width without one.
 
+An **opacity modifier composites over `transparent`, not over the element's own rest fill.** On a control that is opaque at rest (`tw:bg-card`, `tw:bg-background`) a `tw:hover:bg-<token>/NN` therefore _replaces_ that fill, and the control shows whatever it overlaps — a flow-canvas edge, an `Alert` tint. Mix the state fill into the control's rest token instead: `tw:hover:bg-[color-mix(in_oklab,rgb(var(--muted-foreground))_15%,rgb(var(--card)))]`. Use the raw `--*` triples — `--color-*` is `@theme inline`, build-time only, and an unresolved one invalidates the declaration into `transparent`. A control that is **transparent at rest** (menu item, ghost button, table row) is the case the modifier is for; leave those alone.
+
+A tint also cannot carry a **state change** on a light surface — a brand-primary tint stays within ~1.5:1 of the surface at any opacity that still reads as a tint. Step the border for that, and keep the roles apart: hover steps the chrome border (`border-input` → `border-muted-foreground`), `focus-visible` owns the brand border.
+
 **Status — themeable under argo, with AA-legible defaults.** The four semantic states — `success`, `warning`, `info`, and `destructive` (used for "error") — are brand-overridable tokens, not fixed scales. Alert `variant`, `HelpBlock` / field-error state, `ErrorState`, and `Stepper` status read them, so a brand recolours every status surface at once. **Rule:** consume the token as **tint + text/icon** — `tw:bg-<role>/10` for the surface, `tw:text-<role>` / `tw:border-<role>/25` for the mark. The default token values ship dark enough to be AA (≥4.5:1) as text/icon on their own tint, in light **and** dark mode — a brand overriding them should preserve that. Avoid solid fills with a white foreground (`tw:bg-<role>` + white): the token flips light in dark mode, so white-on-token fails there. A brand _can_ recolour "error" away from red — that is now allowed; the accessible-on-tint contract is what must hold, not the hue. **Legacy exception:** the themeable treatment is gated to argo (`data-[argo=true]:` / `group-data-[argo=true]/…:`). Under legacy chrome (`useArgoDesign()` → `false`) Alert and `ErrorState` keep their original fixed status scales (`blue-*`/`green-*`/`warning-*`/`error-*`), and the legacy brand retains its original status token hues — so legacy status colour is unchanged.
 
 **Decorative — stays fixed across brands.** The non-semantic palette that encodes category rather than state: `Badge` decorative colours (`purple`, `cyan`, `teal`, `blue`, …), chart colours, decorative tag palette. **Rule:** keep using primitive scales (`purple-500`, `cyan-500`, …). These are an identity/category contract with the consumer and do not re-skin.

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # @keboola/design
 
+## 11.4.0
+
+### Minor Changes
+
+- The AIKit layer for Kai's redesign (DES-20, DES-170).
+  - `ThemeScope` (new): a subtree pins its own colour scheme regardless of the app's —
+    Kai's panel stays light while its minimized widget is dark. `useThemeScopeContainer`
+    hands portalling components the scope element, and `Popover.Content` now takes a
+    `container` so a portal stays inside the scope that styles it.
+  - `ToolCallStatusHeader` joins AIKit — the tool-call panel header kbc-ui carried,
+    promoted with tests and stories.
+  - `MessageBubble` drops its avatar; a user turn is a plain bubble. `user` is still accepted
+    (deprecated, ignored) so call sites keep compiling.
+  - `Command` takes a `variant`, so a command in a small surface (a popover) can opt out
+    of the full-screen palette styling the theme would pick.
+  - No platform token changes: Kai scopes its own sidebar accent in kbc-ui.
+  - The root barrel grows ~1 KB with the new exports; the size budget moves 342→344 KB.
+
+- `CodeEditor` search matches literal text instead of a compiled pattern, and `findLiteralMatches` / `hasLiteralMatch` ship as utilities.
+
+  A search query is data, not a pattern. Compiling one meant escaping it first and living with V8's
+  ceiling on how large a pattern may be: a query of a few tens of kilobytes — what pasting a document
+  into a find box produces — threw `Regular expression too large` when the pattern was first executed.
+  `findMatches` now scans for the query literally, so escaping and that ceiling are both gone, and it
+  short-circuits before joining the document's rope when the query cannot fit in it.
+
+  `findLiteralMatches(text, query)` returns the start offsets of every case-insensitive occurrence and
+  `hasLiteralMatch(text, query)` answers whether there is one, stopping at the first. Both fold case
+  without changing the length of the string, so the offsets index the caller's own text.
+
+  Two behaviour notes for anyone matching the editor's counts elsewhere: `İ` (U+0130) now reads as a
+  plain `i` rather than matching only itself, and `SearchMatch` no longer carries the matched `text`,
+  which nothing read.
+
+- `Markdown` accepts `remarkPlugins` and `components`.
+  - `remarkPlugins` runs after the built-in GFM one rather than in place of it, so tables, autolinks and task lists keep working whatever a caller adds.
+  - `components` is merged over the built-in element renderers by key. An override replaces that element's renderer rather than wrapping it, so a `table` override loses the design `Table` and an `a` override loses the new-tab treatment for absolute links.
+  - Together they are the seam an app's own inline syntax arrives through — an annotation an agent writes beside a link, read back by a renderer for that element — which is app product knowledge and does not belong in this package.
+  - Both are meant to be held in module constants: `Markdown` re-parses its source on every render, so a caller memoises it, and a prop object built during render defeats that.
+
+- `MarkedText` highlights by literal scan instead of a compiled pattern, and `findLiteralMatches` takes an `isCaseSensitive` option.
+
+  The highlight query was escaped, split on spaces, and joined into one alternation regex — so a
+  space-free paste of a few tens of kilobytes (minified SQL, JSON, base64) exceeded V8's pattern
+  ceiling and threw `Regular expression too large` from a `useMemo`, taking the page down with it.
+  `createMarkedParts` now finds each space-separated term with `findLiteralMatches` and merges the
+  offsets, so no pattern is compiled at all.
+
+  One visible behaviour change: overlapping term matches now merge into one marked run — searching
+  `test testing` marks the whole `testing`, where the alternation used to mark only its `test` prefix
+  and leave `ing` plain. Adjacent matches merge the same way. Case-insensitive matching also folds
+  `İ` (U+0130) to a plain `i`, matching the editor search.
+
+  `escapeStringRegexp` is gone from the package's internals — nothing compiles user text as a pattern
+  anymore.
+
+- `MultiCombobox`: a render-only slot for pinned chips, chip callbacks see the real item type, and a created value stops haunting the list.
+
+  `pinnedChipLabels` renders chips the caller keeps rather than the user — a set of packages the
+  runtime already ships, a role every member has. They sit ahead of the values, outside `maxVisible`,
+  carry no remove button, and never enter `value`.
+
+  `itemToChipLabel` and `itemToChipColor` now receive `Value` instead of `unknown`, so a call site
+  stops narrowing by hand. Existing call sites keep compiling; their `String(...)` wrappers become
+  redundant.
+
+  Created values were kept in a list that never shrank, so a value the user created and then removed —
+  or cleared — stayed in the listbox as an option for the rest of the session, and skewed
+  `allowSelectAll`'s "everything is selected" arithmetic. The list now tracks the selection.
+
+- Add a `hint` slot to `Select` items, and let the top-level `Select` take `aria-label`.
+
+  `hint` renders a trailing muted note in the listbox row — "Default" beside the value the
+  platform falls back to. It sits outside Radix's `ItemText`, so the trigger keeps showing the
+  label alone once the option is picked; because Radix names an option from `ItemText` only
+  (`aria-labelledby`), the hint is wired into the item's `aria-describedby` instead, so a screen
+  reader still reads it.
+
+  `aria-label` was the one trigger a11y prop the convenience wrapper did not forward — it already
+  curated `aria-describedby`, `aria-invalid` and `aria-required`. Selects that stand without a
+  visible `Label` (a filter row, or several selects joined by "OR") need it.
+
+- `UsageStats`: the corner alert badge now accepts a severity.
+
+  `alert` takes `boolean | 'warning' | 'error'` instead of a bare boolean. `'warning'` renders the badge
+  amber for an approaching-limit state that isn't at-limit yet; `'error'` (or the existing bare `true`)
+  keeps the red at-limit color, so existing call sites keep compiling unchanged.
+
+### Patch Changes
+
+- `Button variant="outline"`: the hovered button stops dissolving into the surface behind it.
+
+  Both hover and pressed fills were tints of `transparent` (Tailwind's `bg-<token>/NN`), so hovering
+  replaced the variant's opaque rest fill and the button showed whatever it overlapped — an edge on a
+  flow canvas, the status tint inside an `Alert`. They now `color-mix` into the variant's own rest
+  token (`--card` under legacy chrome, `--background` under argo), which is the same colour on the
+  surface the variant assumes and stays opaque off it.
+
+  Argo compounded that by keeping `border-input` on hover while tinting the fill toward it, so the
+  button's edge contrast _dropped_ as the user reached it — measured 1.42:1 → 1.25:1 in light and
+  2.28:1 → 1.62:1 in dark, against its own fill on a `--muted` surface. Its hover now steps the
+  border to `--muted-foreground` (4.00:1 / 5.24:1), the treatment legacy already shipped. A tint
+  cannot carry that signal: brand primary stays within ~1.5:1 of a light surface at any opacity that
+  still reads as a tint. `--primary` stays reserved for `focus-visible`, so hover and focus remain
+  distinguishable.
+
+  Consumers overriding the hover fill per call site to work around the leak can drop those
+  overrides. `packages/design/AGENTS.md` records the underlying rule in the Layer-0 chrome contract.
+
+- Security patches for transitive dependencies: qs 6.16.0 in api-client, mermaid 11.17.2 and dompurify
+  3.4.14 in design.
+
+  No API or behaviour change in either package.
+
+- Every theme-aware subpath entry stops carrying `@keboola/brand-registry`.
+
+  `ThemeProvider/defaults.ts` imported two legacy brands for value, only to build a two-element array
+  of their ids — and that array had exactly one consumer, the `renderWithTheme` test helper. Because
+  `useThemeAttributes`, `useBrandState` and `useColorSchemeState` each read a constant from
+  `defaults.ts`, that one import put the whole registry in the graph of every entry that reads the
+  live theme.
+
+  The ids now live at the helper that uses them, so `defaults.ts` imports `Brand` as a type only. No
+  export moved and no behaviour changed — `keboolaLegacySidebar` / `keboolaLegacyTopnav` still resolve
+  from the root barrel for the consumers that render them.
+
+  What a consumer pays for a themed subpath, brotlied:
+
+  | Entry                             |     Before |      After |     Δ |
+  | --------------------------------- | ---------: | ---------: | ----: |
+  | `@keboola/design/vega`            |    61.9 kB |     0.9 kB | −98 % |
+  | `@keboola/design/editors`         |   312.5 kB |   252.0 kB | −19 % |
+  | `@keboola/design/flint`           |   439.7 kB |   380.2 kB | −14 % |
+  | `@keboola/design/rjsf`            |   490.2 kB |   430.6 kB | −12 % |
+  | `@keboola/design/markdown-editor` | 1 333.9 kB | 1 272.0 kB |  −5 % |
+  | `@keboola/design/mermaid`         | 1 200.4 kB | 1 140.1 kB |  −5 % |
+  | `{ useAppForm }` from the root    |   135.2 kB |    73.9 kB | −45 % |
+
+  The root barrel is unchanged — it re-exports the brands deliberately, so an app that renders one
+  still pays for it once. The per-entry `size-limit` budgets drop to match, so they now measure the
+  entry rather than a shared dependency.
+
+- `Modal.Footer` now lays its own actions out: right-aligned, 8px apart.
+
+  The footer owned only horizontal padding, so a bare `<Modal.Footer>` fell back to block flow — its
+  buttons sat left-aligned, separated by nothing but collapsed JSX whitespace. Nearly every footer in
+  this repo is bare, so that was the default look; a handful re-declared `tw:flex tw:justify-end
+tw:gap-2` at the call site. Consumers can drop those.
+
+  Overriding the arrangement still works through `className`, but `cn` runs tailwind-merge, which
+  displaces only within a conflict group: `tw:justify-between` replaces `justify-end`, while
+  `tw:flex-col` leaves `items-center` and the gap in place, so a stacked footer wants
+  `tw:items-stretch` alongside it. The footer imposes no width on its children, so one that should
+  fill the row carries `tw:w-full` itself (`Button block`, `ButtonGroup variant="block"`).
+
+  One footer in this repo wanted the stacked arrangement — `wr-google-sheets`' `SheetModal`, which
+  puts a saving message above its buttons — and is the only one still passing layout classes.
+
+  `@keboola/kbc-ui` and `@keboola/control-ui` are private — nothing to release for them; they are
+  listed because their call sites changed.
+
+- `PromptInput`: `autoFocus` no longer scrolls ancestors to reveal the textarea.
+
+  The prop was forwarded as the DOM attribute, and the browser's autofocus scrolls every scrollable
+  ancestor toward the element. A composer mounting inside a panel that is still sliding in — kbc-ui's
+  Kai rail opens this way — sits off-canvas at focus time, so the page scrolled sideways toward it,
+  shoving the whole content left until the slide finished and the overflow clamp snapped it back.
+  The focus is now applied imperatively on mount with `focus({ preventScroll: true })`: same focus,
+  same mount-only semantics, no ancestor scrolling.
+
 ## 11.3.0
 
 ### Minor Changes

package/COMPONENT-API.md

@@ -319,37 +319,38 @@ 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       | —       | Optional node rendered at the trailing edge of the label row (opposite the label) — e.g. a "Forgot password?" link beside a Password label. Presentational placement only; it is a sibling of the `<Label>`, not part of the field's accessible name. Provide an interactive element (`ButtonInline` / `Link`). |
-| `allowClear`         | `boolean`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `allowCreate`        | `boolean`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `allowSelectAll`     | `boolean`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `aria-describedby`   | `string`                                                                                                                                                                                                           | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `className`          | `string`                                                                                                                                                                                                           | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `empty`              | `ReactNode`                                                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                                                                                                                                                                               | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `groupToLabel`       | `((group: Group<string>) => ReactNode)`                                                                                                                                                                            | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `help`               | `ReactNode`                                                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `indicator`          | `Indicator`                                                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `inputClassName`     | `string`                                                                                                                                                                                                           | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `items`              | `readonly (string \| Group<string>)[]`                                                                                                                                                                             | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `itemToChipColor`    | `((item: unknown) => "gray" \| "gray-darker" \| "gray-inverse" \| "green" \| "green-darker" \| "green-inverse" \| "blue" \| "blue-inverse" \| "red" \| "orange" \| "orange-inverse" \| "amber" \| ... 9 more ...)` | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `itemToChipLabel`    | `((item: unknown) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `itemToDisabled`     | `((item: string) => boolean)`                                                                                                                                                                                      | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `itemToIcon`         | `((item: string) => ReactNode)`                                                                                                                                                                                    | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `itemToLabel`        | `((item: string) => ReactNode)`                                                                                                                                                                                    | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `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       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `queryToCreateLabel` | `((query: string) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `queryToCreateValue` | `((query: string) => string)`                                                                                                                                                                                      | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `required`           | `boolean`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `requiredMark`       | `RequiredMark`                                                                                                                                                                                                     | no       | —       | Which marker to show beside the label — gated by `required` so it never lies: `'required'` renders `*` only when the field is `required`; `'optional'` renders `(optional)` only when it is not; `'hidden'` renders neither. Defaults to `'required'`.                                                          |
-| `sizing`             | `"small" \| "medium" \| "default" \| null`                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `tooltip`            | `ReactNode`                                                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
-| `variant`            | `"primary" \| "secondary" \| null`                                                                                                                                                                                 | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| Prop                 | Type                                                                                                                                                                                                              | Required | Default | Description                                                                                                                                                                                                                                                                                                     |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `action`             | `ReactNode`                                                                                                                                                                                                       | no       | —       | Optional node rendered at the trailing edge of the label row (opposite the label) — e.g. a "Forgot password?" link beside a Password label. Presentational placement only; it is a sibling of the `<Label>`, not part of the field's accessible name. Provide an interactive element (`ButtonInline` / `Link`). |
+| `allowClear`         | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `allowCreate`        | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `allowSelectAll`     | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `aria-describedby`   | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `className`          | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `empty`              | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                                                                                                                                                                              | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `groupToLabel`       | `((group: Group<string>) => ReactNode)`                                                                                                                                                                           | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `help`               | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `indicator`          | `Indicator`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `inputClassName`     | `string`                                                                                                                                                                                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `items`              | `readonly (string \| Group<string>)[]`                                                                                                                                                                            | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `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) => ReactNode)`                                                                                                                                                                                   | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `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       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `pinnedChipLabels`   | `ReactNode[]`                                                                                                                                                                                                     | no       | —       | Labels for chips the control shows but the user does not own — a pinned set the caller keeps. - Each label gets a chip of its own, ahead of the values and outside the `maxVisible` slice. - No remove button, and no entry in `value` — there is nothing for a removal to report.                              |
+| `queryToCreateLabel` | `((query: string) => ReactNode)`                                                                                                                                                                                  | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `queryToCreateValue` | `((query: string) => string)`                                                                                                                                                                                     | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `required`           | `boolean`                                                                                                                                                                                                         | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `requiredMark`       | `RequiredMark`                                                                                                                                                                                                    | no       | —       | Which marker to show beside the label — gated by `required` so it never lies: `'required'` renders `*` only when the field is `required`; `'optional'` renders `(optional)` only when it is not; `'hidden'` renders neither. Defaults to `'required'`.                                                          |
+| `sizing`             | `"small" \| "medium" \| "default" \| null`                                                                                                                                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `tooltip`            | `ReactNode`                                                                                                                                                                                                       | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `variant`            | `"primary" \| "secondary" \| null`                                                                                                                                                                                | no       | —       |                                                                                                                                                                                                                                                                                                                 |
 
 ### `field.CheckboxField`