@keboola/design 11.3.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,58 @@ 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
+<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.
+
+**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
@@ -535,6 +738,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.