@keboola/design 11.9.0 → 12.0.0

package/AGENTS.md

@@ -93,7 +93,7 @@ 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`.
+**Every select-shaped control needs an accessible name, and it goes on the control itself** — 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. A name set on a surrounding wrapper (an `InputGroup`, a `<div>`) reaches nothing: the role is on the trigger or the input. `Select` and `Select.Trigger` **will not compile** without one of the three (the JSDoc on the prop says why); `Combobox` and `MultiCombobox` will, and then fall back to their `placeholder`, which the name calculation reaches only as a last resort. The `field.*` connectors need none of it: `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.
 
@@ -127,6 +127,10 @@ reader gets the state too.
 | `DotsLoader`        | Indeterminate background work without a layout slot (small inline progress signal)                 |
 | `ThinkingIndicator` | An agent turn that is in flight with nothing to show yet — every Keboola chat says it the same way |
 
+A `Combobox` or `MultiCombobox` whose options come from a request takes **`isLoading`**, never an
+`empty` whose text switches to "Loading…". It does not disable the control — pass `disabled` too
+only where the user must wait. `Select` has no counterpart: it is for a short, known enum.
+
 **Never** build a new "Loader" / "BoxLoader" / "ActionLoader" wrapper component. Compose `Skeleton` directly into the slot the real content will occupy.
 
 ### Tooltips
@@ -283,7 +287,7 @@ whose empty state the surrounding form cannot represent. The button only mounts
 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.
+`SelectWidget` and `ComboboxField` derive `allowClear={!required}` while `MultiComboboxField` does not.
 
 #### Chip content in a `MultiCombobox`
 
@@ -376,11 +380,12 @@ one of these instead:
 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 |
+| 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                                                                                                    |
+| `ComboboxField` | **`''` is no selection**, `' '` a genuine value — the form value maps `''` to an empty control, so a `withBlankValues` `[empty string]` row cannot be picked. Use a named sentinel item, as with `Select` |
+| `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`
@@ -716,6 +721,27 @@ 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.
 
+**Collapsible, selectable groups** — a two-level list where the parent is picked as well as its children (a bucket and its tables). `collapsibleGroups` turns each group's label into a row with a chevron that folds the group; `selectableGroups` (`MultiCombobox`) makes a press on that row select the group's items the query matches, and `groupToValue` (`Combobox`) makes the row a value of its own.
+
+```tsx
+<MultiCombobox
+  items={buckets} // [{ id, items: tableIds }]
+  value={tableIds}
+  onValueChange={setTableIds}
+  groupToLabel={(bucket) => bucket.id}
+  collapsibleGroups
+  selectableGroups
+  virtualized="auto"
+/>
+```
+
+- A query overrides folding: every match shows, and a group with none disappears — so the group's row always stands for something the user can see.
+- `value` holds items only. The row reads checked / mixed from them and never becomes a chip, so `allowSelectAll` and `renderChips` count what they always count.
+- Without `selectableGroups` / `groupToValue` a press on the row folds the group; with them, the chevron and `ArrowRight` / `ArrowLeft` do.
+- Don't hand-roll it from a flat list and an `onValueChange` that expands a parent into its children — the control owns the fold, the query override and the mixed state.
+
+**Long lists** — a `Combobox` or `MultiCombobox` whose options can run into the hundreds (tables, configurations, users) takes `virtualized="auto"`: past 30 options, grouped or not, only the rows in view reach the DOM. It is opt-in because a test that clicks a far row needs every option rendered.
+
 **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
@@ -740,7 +766,7 @@ import { ChevronDown, Keboola, Loader2 } from '@keboola/design/icons';
 ```
 
 - **One import surface**: Lucide icons and Keboola-custom icons (e.g. `Keboola`) both export from `@keboola/design/icons` and share the `LucideIcon` type, so they're interchangeable in any API typed `icon: LucideIcon` (Button, etc.).
-- **Vendor marks** also ship from `@keboola/design/icons` — `Aws`, `Azure`, `ChatGpt`, `Claude`, `Cursor`, `Devin`, `Gcp`, `Google`, `Keboola`, `Make`, `Microsoft` — in their own brand colours by default; pass **`mono`** to render one in `currentColor` instead. The `Eu` / `Us` flags are colour-only.
+- **Vendor marks** also ship from `@keboola/design/icons` — `Auth0`, `Aws`, `Azure`, `ChatGpt`, `Claude`, `Cursor`, `Devin`, `Gcp`, `GitHub`, `GitLab`, `Google`, `Keboola`, `Make`, `Microsoft`, `Okta` — in their own brand colours by default; pass **`mono`** to render one in `currentColor` instead. The `Eu` / `Us` flags are colour-only.
 - **Sizing**: prefixed Tailwind `tw:size-*` utility — `tw:size-4` = 16px (default for inline icons), `tw:size-5` = 20px, `tw:size-6` = 24px.
 - **Spinner animation**: explicit via `tw:animate-spin`.
 

package/CHANGELOG.md

@@ -1,5 +1,160 @@
 # @keboola/design
 
+## 12.0.0
+
+### Major Changes
+
+- Remove the `break-anywhere` custom utility from `@keboola/design/theme`
+
+  Tailwind v4.1 shipped `wrap-anywhere` as a core utility emitting the same `overflow-wrap: anywhere`, and the repo compiles against v4.3. A custom utility that duplicates a core one only adds a second name for the same declaration.
+
+  Replace `tw:break-anywhere` with `tw:wrap-anywhere`. No other change — the emitted CSS is identical.
+
+### Minor Changes
+
+- `Combobox` and `MultiCombobox` give a group a row of its own that folds it and can select it.
+  - `collapsibleGroups` folds a group from its row's chevron, or with `ArrowRight` / `ArrowLeft` on the highlighted row. A query shows every match whatever is folded.
+  - `MultiCombobox` `selectableGroups` makes the row select the group's items the query matches, and reads checked, mixed or empty. `value` only ever holds items.
+  - `Combobox` `groupToValue` makes the row a value of its own, so a group is picked whole beside its items.
+
+- `ComboboxField`: a `useAppForm` connector for the single `Combobox`, holding a `string` (`''` for no selection), imported by name and composed inside `form.AppField`. `Combobox` takes `name`, `onBlur`, `aria-invalid` and `aria-required` and forwards them to its input, and the rjsf `SelectWidget` / `DynamicSelectWidget` mark a field with errors through `aria-invalid` and revalidate on blur, so a fixed value clears its error.
+
+- `MultiCombobox` takes `virtualized` like `Combobox`, and in both it now windows grouped lists too.
+  - `'auto'` windows a list of more than 30 options, grouped or not, collapsible and selectable groups included; `true` always does. The default stays `false`.
+  - A windowed option carries `aria-setsize` / `aria-posinset`, so the list's length stays known with most rows out of the DOM.
+  - A grouped `MultiCombobox` with `allowSelectAll` filters by the query; it used to show no match.
+
+- `Combobox` and `MultiCombobox` take `isLoading` for options that are still arriving.
+  - The open button's chevron turns into a spinner, and the input reports `aria-busy`.
+  - The popup says "Loading…" where it would otherwise show `empty`, so a fetch no longer reads as an empty list.
+  - Items already present stay listed and selectable, and the control stays typeable and creatable — pass `disabled` as well where the user has to wait.
+
+- `FileDownloadChip` offers a file an agent wrote, inside the answer that names it.
+
+  An agent that has just built a spreadsheet can otherwise only name it in prose, leaving the reader a filename and no way to reach it. The chip is the answer's own answer to "where did my report go": the file name, its size when the caller knows it, and a download, drawn where the sentence mentions the file. The whole chip is the control rather than an icon at the end of it — it sits in a transcript column, where a small target beside a truncating filename is the hardest thing on the page to hit — and it is named `Download <file>` rather than by the file alone, because a reader hearing only `revenue.csv` has no way to know that activating it takes the file. The path goes on `title`, which is what tells two `report.pdf`s in different folders apart, and stays a hover affordance rather than the accessible name. It neither fetches nor saves: the transport is the host's, which is what lets one chip serve two apps whose markdown stacks and auth pipelines are separate, and `isPending` is the only thing it says about a download in flight.
+
+- `Auth0`, `GitHub`, `GitLab` and `Okta` join the vendor marks in `@keboola/design/icons`, so a sign-in or identity-provider picker can show each vendor by its own mark.
+
+  `Auth0` and `GitLab` render in their brand colours, and `mono` flattens them to `currentColor` like every vendor mark. `GitHub` and `Okta` draw in `currentColor` always: both vendors ship their marks in black and white only, so the text colour is the brand colour and keeps them visible on light and dark surfaces. Each comes from the vendor's own brand or press source — the Okta Aura lifted out of the lockup on okta.com — and is recorded with its restriction in `icons/vendors/README.md`.
+
+- `Button` gains a `kai` variant: Kai's gradient with three light pools drifting behind the label, for Kai's own actions.
+
+- The reading rhythm of an answer is one definition
+  - `tw:prose`'s `--tw-prose-*` slots point at theme tokens, so prose follows the colour scheme and the brand without a call site reaching for `prose-invert`. The `[data-theme='dark'] .tw:prose → prose-invert` patch is gone with them. This is not additive: every `.tw:prose` surface takes the new palette, tooltips and docs included.
+  - `tw:prose-answer` is the new measure, heading scale, heading margins and paragraph/list rhythm a Keboola answer reads on. `AIKit/Markdown` wears it, so every chat gets the same one.
+  - `Markdown` takes a `rhythm` prop: `answer` (the default) is the new rhythm, `chrome` is `tw:prose` on the dense `tw:prose-sm` scale for content a model did not write — a dashboard text widget, a vendor's app description.
+  - `tw:prose-code-chip` paints inline code as a chip on the `--muted` / `--foreground` pair, and both rhythms wear it. It is its own utility because it is palette, not rhythm: without it a surface keeps Typography's pinned `#c7254e`, which measures 3.36:1 on the dark page.
+  - `Markdown.Root` / `Markdown.Block` split one prose surface from the N blocks a streaming renderer paints into it — the rhythm then resolves `:first-child` / `:last-child` across the whole reply.
+  - `tw:prose-answer`'s wider values apply inside an `@container/messages` at 640px and up; where no consumer declares that container it keeps its narrow ones.
+
+- Add `Popover.Anchor` to position a controlled popover against an element that is not its trigger.
+
+- `PromptInput`: a `PromptCommand` may carry `onSelect` and act instead of inserting its value, and a `panel` takes the popup's place for a small form opened from such a row — Escape and the × close it. `commandsGroupAction` puts a control on a `/` group's heading line, for whatever that group's rows come from. A `PromptCommand` may also carry an `icon`, for a list whose rows are things rather than commands.
+
+- `PromptInput`'s `/` menu is about the leading token, not the whole message: it opens while the caret is on a `/token` at the head of the text even when a message follows, and a pick replaces only that token. `findSlashToken` is exported for a host that needs the same reading.
+
+- `PromptInput` takes `mentions` and `onMentionSelect`: an `@` typed anywhere in the message opens a
+  command popup filtered by the word after it. Picking an item removes the token and hands the pick to
+  the host, which attaches whatever it stands for — nothing is inserted as text. `findMentionToken` is
+  exported for a host that needs to reopen the menu at the caret.
+
+- A status dot and a chip editor, so nobody paints a state or a chip row by hand
+
+  `StatusDot` is one entity's state as a coloured dot. `status` — `success`, `warning`, `info`,
+  `destructive`, `neutral` — is its whole colour API: there is no `color` prop taking a hue, so the
+  dot reads the themeable status tokens and a customer brand recolours every dot on the platform at
+  once. `pulse` says the work is still moving, and `label` names the dot for a screen reader where the
+  text beside it does not.
+
+  `ChipEditor` is the chip row without the popup — tags, feature flags, permitted email domains, any
+  list of strings the user writes rather than picks. Enter, the separator and blur each commit what is
+  typed; Backspace in an empty field removes the last chip. It shares `MultiCombobox`'s vocabulary, so
+  a pasted list becomes one chip per value (`separator`, `null` for a value that contains one) and
+  `canAdd` gates each value's format, keeping the ones that pass and leaving the rest in the field to
+  fix. Values are compared case-insensitively, so one already held is never added twice.
+
+  Reach for `MultiCombobox` the moment there is a list worth searching, even an open-ended one.
+
+### Patch Changes
+
+- Refresh AIKit Markdown visual baselines for the answer rhythm.
+
+- Refresh AIKit PromptInput visual baselines for the compact composer.
+
+- Make legacy Alert tints scheme-aware so dark mode uses legible semantic status tokens.
+
+- Add two brands to the registry: `agnes` (the "paper" light theme shipped by the Agnes AI-analyst harness, with the emerald/navy dark palette such an instance actually renders) and `harbor` (a fictional consulting/advisory showcase brand, navy + steel blue + gold, clean against AA in both palettes). Both are re-exported from `@keboola/design`, offered in the Storybook brand toolbar, and available as theme-generator presets.
+
+  Also mark the frozen `brands` array `@__PURE__`. Without the annotation a bundler reads the top-level `Object.freeze(...)` as a side effect and keeps every brand — logo SVGs included — in any bundle that imports a single one; `@keboola/design/testing` shrinks from 88.27 kB to 86.31 kB as a result. Its budget moves 88 kB -> 92 KB so the next brand does not land on the limit again.
+
+- `Button` honours an explicit `aria-disabled` instead of overwriting it.
+
+  The attribute was written from the `disabled` prop after the caller's own props were spread, so a button passing `aria-disabled` alone reported `aria-disabled="false"` — the opposite of what it asked for, and silently. That shape is the one a focus-preserving pending state needs: `disabled` removes the control from the tab order, so a reader who tabs to a button and activates it loses their place on the page for as long as the action runs. Passing `aria-disabled` and ignoring activation in the handler keeps the control focusable and still says it is unavailable. `disabled` alone behaves exactly as before.
+
+- Card's border follows the theme in every brand, not only argo
+
+- Seed ChipEditor and StatusDot visual baselines.
+
+- `Combobox` and `MultiCombobox` forward `aria-label` and `aria-labelledby` to the input.
+
+  Both accepted the props and dropped them, so a control with no visible label had no accessible name — its `placeholder` was all a screen reader had to go on, and only as the last resort of the name calculation. The `combobox` role is on the input itself, so nothing set on the surrounding `InputGroup` would have reached assistive tech either. `Combobox` also forwards `name` and `aria-describedby`, which `MultiCombobox` already did. UT-5474.
+
+- - `Combobox` rows show `itemToStringLabel`'s text, a blank one named, where no `itemToLabel` is passed — as `MultiCombobox` rows do. An item without a `label` field needs only `itemToStringLabel`.
+  - `MultiCombobox` without `value` holds its own selection: `defaultValue` seeds it, and `onValueChange` reports each change.
+  - In a grouped `Combobox` or `MultiCombobox` with `allowCreate`, `groupToLabel` receives only the groups in `items`. The created values sit in a group of their own with no label.
+  - `MultiCombobox`'s `itemToLabel` receives the typed query as its second argument, as `Combobox`'s does, so a row can mark the match with `MarkedText`. A chip receives `''`.
+  - `Combobox` and `MultiCombobox` label each group from its `label` field where no `groupToLabel` is passed, as `Select` does. A `label` that is not a string, a number or an element reads as none.
+
+- `Combobox` shows an empty input for a selected item whose `label` and `value` are both `''`.
+  - Such an item reads as `''` for the input text, the default search text and the accessible value, like the string item `''`.
+  - Its row is still named `[empty string]`.
+
+- `Combobox` with `allowCreate` lists a created value only while it is the selection and `items` does not hold it, so an adder pinned to `null`, a later pick, or an owner that adds the value to `items` leaves no extra created row.
+
+- A collapsible group row in `Combobox` and `MultiCombobox` states its fold as the accessible description `Expanded` / `Collapsed`. It carries no `aria-expanded`, which `role="option"` does not allow.
+
+- Add linux visual baselines for the Combobox and MultiCombobox loading and collapsible-group stories and the PromptInput attachments story.
+
+- `Combobox` and `MultiCombobox` key the rows of a fully rendered list, so opening one logs no React "unique key" warning.
+
+- `Combobox` and `MultiCombobox` without group rows (`collapsibleGroups`, `groupToValue`, `selectableGroups`) re-filter their list only when `items`, `filter`, a label accessor or, for `MultiCombobox`'s default filter, `value` changes. A caller that keeps those stable no longer re-filters on an unrelated re-render; a list with group rows still re-filters on every render.
+
+- `FileDownloadChip` spins while a download is in flight.
+
+  It only greyed out before, so a slow or large file gave the reader nothing to watch and no way to tell a working download from a dead control. `Button` already owns the in-flight contract — `isLoading` draws the spinner and disables the control — so the chip passes it rather than inventing a second convention. Its own file and download glyphs are suppressed for that moment: `Button` renders the spinner _beside_ its children rather than in place of them, so leaving them in would stack three icons in a row barely wider than the filename.
+
+- `FileDownloadChip` names the file by its path in the accessible name.
+
+  `aria-label` replaces a button's descendant text and `title` plays no part in the accessible name, so the label was the only thing a screen reader announced — and it carried the bare filename. Two files named `report.pdf` from different folders were announced identically, leaving no way to tell which download was about to be activated. The label now carries `filePath` when there is one, falling back to `fileName`. The visible chip is unchanged: it still shows the name alone, since the path is what truncates badly in a transcript column.
+
+- Dark mode: text selection is a translucent primary wash instead of the browser's solid fill.
+
+- InputGroup, Select/overlay triggers and base h1 use theme tokens so text and secondary controls stay readable in dark mode
+
+- `MultiCombobox` works on React 19.3: a press beside the chips focuses the input and opens the list, and the chip row takes the toolbar role once it holds chips.
+
+- A narrow `MultiCombobox` keeps its clear and open buttons inside its border.
+  - The input row wraps below the chips when there is less than 120px of room for the input beside them.
+  - On a row of its own it shrinks to the control's width, so a value field in a three-column filter row keeps both buttons reachable.
+
+- `PromptInput` eases its height as attachments are added or removed.
+
+- `PromptInput`'s `inline` row folds into the stacked layout below 480px of the container a host names with `PROMPT_INPUT_CONTAINER`, so a composer beside a panel that narrows it keeps its text on a line of its own instead of squeezing.
+
+- `Question` renders its footer only when something would be in it, and drops the step widget on a one-question card. A single step showed "1 of 1" over a full progress bar with both chevrons dead, and a card with no Skip and no submit action was left with a bordered strip containing nothing — which reads as a control that failed to render.
+
+- -
+
+- Bound the SQL editor's active-query highlight to the document it highlights, so a splitter whose fragments do not re-join to the input can no longer crash the editor with `RangeError: Invalid position N in document of length M`.
+
+- `Tooltip` renders the argo chrome when its trigger sits inside `Navbar` or `Sidebar` DOM, even under a legacy brand — those components exist only in the new design, so a black legacy tooltip inside them was the anomaly. The rule is keyed on the trigger's DOM ancestry, so an overlay a nav item portals out of the nav (a dialog, a menu) keeps following the brand. `chrome="argo" | "legacy"` forces one explicitly.
+
+- `Tooltip` casing follows the chrome, not the brand: the legacy dark pill keeps its uppercase label, the argo popover reads standard case. `Kbd` renders its key uppercase by default; `casing="as-written"` keeps a layout-printed label as it is.
+
+- Updated dependencies:
+  - @keboola/brand-registry@1.10.0
+  - @keboola/tailwind-config@1.2.0
+
 ## 11.9.0
 
 ### Minor Changes