@keboola/design 11.6.0 → 11.9.0

package/AGENTS.md

@@ -97,7 +97,7 @@ This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-A
 
 `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`).
+**`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. The exception is `TextInput`'s `rightSuffixVariant="addon"` suffix, which shrinks and ellipsizes inline content instead. `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
 
@@ -107,9 +107,16 @@ This file answers **which** component to use; [`COMPONENT-API.md`](./COMPONENT-A
 | `Toaster`                     | Mount once at app root                                |
 | `Alert`                       | Persistent contextual message in page layout          |
 | `FormGroup state="error"`     | Field-level validation errors inline below input      |
+| `StatusDot`                   | One entity's state as a coloured dot beside its name  |
 
 **Never** use `Alert` for ephemeral success (use `toast()`) or `toast()` for blocking errors (use `Alert`).
 
+**Never** paint a state with a hue of your own — no `tw:bg-amber-400` span, no `color` prop taking a
+hue. `StatusDot`'s `status` (`success` / `warning` / `info` / `destructive` / `neutral`) is its whole
+colour API, so it reads the themeable status tokens and a customer brand recolours every dot at once.
+Colour never carries the meaning alone: pair the dot with the text, or give it a `label` so a screen
+reader gets the state too.
+
 ### Loading
 
 | Use                 | When                                                                                               |
@@ -230,6 +237,8 @@ Vertical rhythm: prefer `tw:gap-*` on a flex column parent over `tw:mt-*` on chi
 
 **`SectionNav` is not `Sidebar`.** `Sidebar` is the app's left rail — global, one per shell, outside `PageLayout`, with `SidebarProvider` state and icon-collapse. `SectionNav` is scoped to a single page's sections, lives in `PageLayout.Content nav`, and holds nothing but an open/closed flag per group. Reach for `SectionNav` when a page has more sections than a tab row can hold, or sections that group; `Tabs` when they don't.
 
+**`Sidebar` can become a `Sheet` under 768px — opt in per side.** `SidebarProvider` takes `leftMobileSheet` / `rightMobileSheet`; both default to off, because a `Sidebar` is also the shape of a container rail nested in a modal or a builder canvas, where a full-screen phone sheet means nothing. A side that opts in occupies no grid column below the breakpoint — the page takes the full width — and the rail opens as a sheet, with the focus trap, the Escape handling and the overlay that come with one. An app that opts in owes the sheet a way in: put a `Sidebar.Trigger` in the header and let it be the only one, since the provider swaps what `toggle` does and the same control collapses the column above the breakpoint and opens the sheet below it. Choosing a destination dismisses the sheet; a button that opens a popup or that is itself a `Sidebar.Trigger` does not. Read `isMobile` off `useSidebar(side)` only for a call site whose whole purpose is the collapse axis (a mode picker) — everything else composes unchanged, and a call site's own `mode` prop is never written. `keepMounted` and `mountAfterEnter` describe the column's transition and do not apply to a side that is a sheet — its content mounts on open and unmounts on close, so state worth surviving a close lives above the panel.
+
 ### Separators
 
 | Use                        | When                                                                  |
@@ -250,10 +259,16 @@ The `label` prop implies `orientation="horizontal"` — labels are not rendered
 | `ColorInput`      | Design-token-driven brand color picker                        |
 | `Combobox`        | Single selection from a searchable list                       |
 | `MultiCombobox`   | Multiple selections from a searchable list                    |
+| `ChipEditor`      | Several free-text values the user types — there is no list    |
 | `Select`          | Single selection from a short enum (≤ ~10 options, no search) |
 | `CodeEditor`      | Generic code editing (JSON, YAML, shell)                      |
 | `SqlEditor`       | SQL editing (syntax + autocomplete)                           |
 
+`ChipEditor` is the chip row without the popup — tags, feature flags, permitted email domains, any
+list of strings the user writes rather than picks. A `MultiCombobox` with `allowCreate` is still the
+right call the moment there is a list worth searching, even an open-ended one; **never** hand-roll an
+input-plus-chips row from `InputGroup` + `Badge`.
+
 `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

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # @keboola/design
 
+## 11.9.0
+
+### Minor Changes
+
+- `InlineStepGroup` joins the AI Kit: the collapsible frame an assistant turn draws a run of steps in — header, animated collapse, and the connector rule the step icons mask themselves against. It takes the rows as children, so a product supplies its own vocabulary and its own step components; `surface` names the colour the icons mask against, for a transcript that does not sit on the page background.
+
+  A closed group is `inert` and `aria-hidden`: `grid-template-rows: 0fr` is layout only, so without them a screen reader reads out steps nobody can see and Tab lands inside a closed run. `CollapsibleStepHeader` carries its outcome as `data-variant` too — the outcome is otherwise carried by the icon's shape and ink alone, which no test and no E2E selector reads. The same outcome joins the header's accessible name as a short sr-only phrase, so a closed group announces how the run came out and not only what it was called.
+
+  The frame carries `role="group"` rather than the `<section>`'s own landmark semantics: a transcript draws one group per run of steps, so a long conversation would hand a screen reader a landmark list of dozens of identically named regions. A named `group` still announces its name, and it is the role the grounding panel already gives its repeated named answer sections.
+
+- `Markdown` draws inline `icon:<name>` tokens, and `ChatInlineIcon` ships the name→Lucide registry behind them.
+
+  A Kai prompt teaches the model the `@keboola/agent-vocabulary` icon names, so any chat rendering its answers has to draw them — until now only kbc-ui could, from a fork of the map. The base `code` renderer turns an inline token into the icon it names and leaves every other inline code alone, and `getChatInlineIconName` + `ChatInlineIcon` are the seam for a caller that overrides `code` itself. Producing the token stays the app's: the remark plugin that finds bare `icon:…` text lives in `@keboola/kai-chat`. The glyph is `aria-hidden`: it replaces the token's text and carries no label of its own, so exposing it would announce an unnamed graphic ahead of every phrase it decorates. `icon:spinner` spins, which `MAINTAINING.md` makes part of the mapping rather than the caller's job — a still `Loader2` is an arc, and reads as a damaged ring rather than as waiting. A name the registry cannot draw is not a token: `getChatInlineIconName` answers `undefined` for it, so the code the author typed survives. A name that is only the start of one it can draw is the other state: an answer streams `icon:t`, `icon:ta`, `icon:tab` before `icon:table` lands, so that half-name draws nothing rather than flashing as a code chip that reflows the line. `Markdown` renders more than agent answers — vendor component descriptions, dashboard text widgets — and `icon:` is an ordinary way to name a property there.
+
+- `SidebarProvider`'s `leftMobileSheet` / `rightMobileSheet` now take a width as well as a flag.
+  - `boolean` keeps the shared 768px breakpoint; a number names the width under which that side is a sheet.
+  - Per side, because the width at which a rail stops fitting is the rail's own — a 320px context panel beside a capped reading column runs out of room long before a navigation rail does.
+
+## 11.8.1
+
+### Patch Changes
+
+- Keep a long `Modal.Header` description inside the modal frame
+
+  `ModalDescription` now breaks anywhere, like `ModalTitle` already did. The slot routinely carries an identifier — a Storage table id, a fully-qualified name — which offers no break opportunity and paints outside the frame at narrow viewports.
+
+## 11.8.0
+
+### Minor Changes
+
+- `AnswerActions` takes a `split` layout and an `actions` slot, so a chat can put the verdict under
+  the left edge of an answer and its own controls under the right.
+
+  It also takes `size`, `labels` and `confirmation`: a roomier row for a panel a reader sits in, the
+  noun the surface rates ("response" or "answer"), and a word back once the vote lands.
+
+- `Sidebar` can become a `Sheet` under 768px, so a phone gets the page's full width.
+  - Opt-in per side on `SidebarProvider`: `leftMobileSheet` / `rightMobileSheet`, both off by default. A `Sidebar` is also the shape of a container rail nested in a modal or a builder canvas, where a full-screen phone sheet means nothing — so no existing call site changes until it asks.
+  - An opted-in side renders no grid column below the breakpoint — `calcEffectiveWidths` reports zero, and the shell's sidebar slot collapses. The rail opens as a `Sheet`, which brings the focus trap, the Escape handling and the overlay. Closing it returns focus to whatever opened it.
+  - `Sidebar.Trigger` opens and closes that sheet instead of toggling the collapse axis, so a header trigger is one control rather than a mobile fork. Choosing a destination closes the sheet; a menu button that opens a popup (`aria-haspopup` / `aria-expanded`) or that is wrapped in a `Sidebar.Trigger` does not.
+  - Above the breakpoint the rail behaves exactly as before: `mode`, `collapsible` and `variant` are untouched. Two things do change for every call site — `Sidebar.Trigger` now states `aria-expanded` on both axes (the sheet's open state on a phone, the column's mode above it), so a trigger child must not supply its own; and `mergeRefs` passes a callback ref's cleanup through instead of dropping it, which is what lets a merged ref release its element on React 19. On a rail that is currently a sheet the collapse axis has nothing to act on, so `setMode` is inert — a stored desktop preference survives the trip through a narrow viewport.
+  - New on the `useSidebar(side)` value: `isMobile`, `isMobileOpen`, `setMobileOpen`. New on `Sidebar`: `mobileTitle`, the sheet's accessible name (defaults to `Navigation` / `Side panel`).
+
+- `PromptCommand` loses its `icon`: the `/` menu has not drawn one since its rows became label-and-description only, so the field was dead weight on every caller.
+
+- `PromptInput` gains an `attachments` slot: images and chips already attached to a message, drawn in
+  rows above the text rather than crowded onto its first line. Both variants are columns now, and only
+  the line itself differs — `inline` keeps the prefix beside the text, `default` stacks the text over
+  its toolbar.
+
+  `PromptInput.MenuTrigger` is the composer's "add to message" button: a plus that rotates into a cross
+  while its menu is open, with `aria-expanded` following.
+
+  The `/` command popup opens below the composer when there is no room above it, is capped in width,
+  sentence-cased, and carries a close button. `DropdownMenu.SubTrigger` and `DropdownMenu.CheckboxItem`
+  accept an `icon` drawn through the same slot as `DropdownMenu.Item`, so a mixed menu keeps one icon
+  column and one icon colour.
+
+### Patch Changes
+
+- `AnswerActions`: the recorded vote is green for thumbs up and red for thumbs down, instead of the same blue for both.
+
+- Addon-variant `rightSuffix` now shrinks instead of forcing the row to overflow, truncating inline content with an ellipsis when the group is narrower than its content.
+
+- `UsageStats`' ring is a `<button>`: it opens a card, so it takes a pointer and a focus ring, and it
+  answers the hover it has always responded to. Hosts that wrapped it in a control of their own would
+  now nest two — none in this repo does.
+
+## 11.7.0
+
+### Minor Changes
+
+- `Tooltip` gains a `hintUnderline` prop that marks its trigger with the shared "this text has a tooltip" affordance — a dashed `neutral-300` underline at `underline-offset-2` with `cursor-help`. It works in both trigger modes, and leaves the trigger's own text colour alone so a coloured label keeps its colour. The same classes are exported as `HINT_UNDERLINE_CLASS_NAME` for triggers that are not a `Tooltip`.
+
+### Patch Changes
+
+- `AnswerActions` takes an `onCopy` callback, so a host can record that a reader took an answer away.
+
+- `MultiCombobox` renders the value itself when `itemToStringLabel` has no label for it, instead of throwing. The projection is typed to return a string but can still come up empty at runtime: Base UI reports the outgoing selection for the render after `items` and `itemToStringLabel` change together, so a chip is asked for a label the incoming projection cannot produce. That threw a `TypeError` out of `namedLabel` and took the surrounding page down with it.
+
+- `InputGroup` can shrink below its content's intrinsic width instead of overflowing its row. A flex item's default `min-width: auto` floored the group at the width of its input plus its addons, so several side by side — a custom timeout's days/hours/minutes row — pushed past their container rather than sharing it. The group already clips its own content, and the input inside already carried `min-w-0`.
+
+- Add `UsageBar` to the AI kit — a budget as a labelled row over a `Progress`, filling with what is spent and reading out what is left. `variant` is the host's to pass, so a surface whose product rules forbid a warning meter draws an untoned one.
+
+- `UsageStats`' ring keeps its size in a flex row. It is a fixed `size-8` with no content to give, so a sibling carrying `shrink-0` — every `Button` — used to squash it first.
+
+## 11.6.1
+
+### Patch Changes
+
+- `Tooltip` and `Badge` state their casing rule the way `Button` already did: standard case is the default, and only the legacy brands (`keboola-legacy-*`) uppercase the chrome. Read the other way round — an uppercase base with one opt-out per modern brand — the rule said nothing about a brand nobody had added yet, so a customer brand drew uppercase tooltips and badges over standard-case buttons.
+
 ## 11.6.0
 
 ### Minor Changes

package/COMPONENT-API.md

@@ -73,24 +73,24 @@ Source: `src/blocks/TextInput/TextInput.tsx`
 
 > Bare input. Plus all native `<input>` attributes.
 
-| Prop                 | Type                                                            | Required | Default   | Description                                                                               |
-| -------------------- | --------------------------------------------------------------- | -------- | --------- | ----------------------------------------------------------------------------------------- |
-| `allowClear`         | `boolean`                                                       | no       | `false`   |                                                                                           |
-| `defaultValue`       | `string \| null`                                                | no       | —         |                                                                                           |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | `default` |                                                                                           |
-| `leftSuffix`         | `ReactNode`                                                     | no       | `null`    |                                                                                           |
-| `onClear`            | `(() => void)`                                                  | no       | —         |                                                                                           |
-| `onValueBlur`        | `((value: string) => void)`                                     | no       | —         | Called with the unwrapped string value on blur. For the raw event use `onBlur`.           |
-| `onValueChange`      | `((value: string) => void)`                                     | no       | —         | Called with the unwrapped string value on every change. For the raw event use `onChange`. |
-| `prefix`             | `ReactNode`                                                     | no       | `null`    |                                                                                           |
-| `rightSuffix`        | `ReactNode`                                                     | no       | `null`    |                                                                                           |
-| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | `default` |                                                                                           |
-| `sizing`             | `"small" \| "medium" \| "default" \| null`                      | no       | `default` |                                                                                           |
-| `state`              | `"warning" \| "error" \| "default" \| null`                     | no       | `default` |                                                                                           |
-| `testId`             | `string`                                                        | no       | —         |                                                                                           |
-| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | `text`    |                                                                                           |
-| `value`              | `string \| null`                                                | no       | —         |                                                                                           |
-| `variant`            | `"primary" \| "secondary" \| null`                              | no       | —         |                                                                                           |
+| Prop                 | Type                                                            | Required | Default   | Description                                                                                                                                                                                                                       |
+| -------------------- | --------------------------------------------------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowClear`         | `boolean`                                                       | no       | `false`   |                                                                                                                                                                                                                                   |
+| `defaultValue`       | `string \| null`                                                | no       | —         |                                                                                                                                                                                                                                   |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | `default` |                                                                                                                                                                                                                                   |
+| `leftSuffix`         | `ReactNode`                                                     | no       | `null`    |                                                                                                                                                                                                                                   |
+| `onClear`            | `(() => void)`                                                  | no       | —         |                                                                                                                                                                                                                                   |
+| `onValueBlur`        | `((value: string) => void)`                                     | no       | —         | Called with the unwrapped string value on blur. For the raw event use `onBlur`.                                                                                                                                                   |
+| `onValueChange`      | `((value: string) => void)`                                     | no       | —         | Called with the unwrapped string value on every change. For the raw event use `onChange`.                                                                                                                                         |
+| `prefix`             | `ReactNode`                                                     | no       | `null`    |                                                                                                                                                                                                                                   |
+| `rightSuffix`        | `ReactNode`                                                     | no       | `null`    | Content after the input. - `rightSuffixVariant="addon"` truncates it with an ellipsis when the group is narrower than its content. - The ellipsis only renders for inline content — pass text or a `<span>`, not a block element. |
+| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | `default` |                                                                                                                                                                                                                                   |
+| `sizing`             | `"small" \| "medium" \| "default" \| null`                      | no       | `default` |                                                                                                                                                                                                                                   |
+| `state`              | `"warning" \| "error" \| "default" \| null`                     | no       | `default` |                                                                                                                                                                                                                                   |
+| `testId`             | `string`                                                        | no       | —         |                                                                                                                                                                                                                                   |
+| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | `text`    |                                                                                                                                                                                                                                   |
+| `value`              | `string \| null`                                                | no       | —         |                                                                                                                                                                                                                                   |
+| `variant`            | `"primary" \| "secondary" \| null`                              | no       | —         |                                                                                                                                                                                                                                   |
 
 ### `PasswordInput`
 
@@ -148,23 +148,23 @@ Source: `src/blocks/FormGroup/FormGroupTextInput.tsx`
 
 > NO `error` prop — error styling comes from the parent `FormGroup state="error"` via context. `state` is omitted from the surface for the same reason. Plus native `<input>` attributes.
 
-| Prop                 | Type                                                            | Required | Default | Description                                                                               |
-| -------------------- | --------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
-| `allowClear`         | `boolean`                                                       | no       | —       |                                                                                           |
-| `defaultValue`       | `string \| null`                                                | no       | —       |                                                                                           |
-| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | —       |                                                                                           |
-| `leftSuffix`         | `ReactNode`                                                     | no       | —       |                                                                                           |
-| `onClear`            | `(() => void)`                                                  | no       | —       |                                                                                           |
-| `onValueBlur`        | `((value: string) => void)`                                     | no       | —       | Called with the unwrapped string value on blur. For the raw event use `onBlur`.           |
-| `onValueChange`      | `((value: string) => void)`                                     | no       | —       | Called with the unwrapped string value on every change. For the raw event use `onChange`. |
-| `prefix`             | `ReactNode`                                                     | no       | —       |                                                                                           |
-| `rightSuffix`        | `ReactNode`                                                     | no       | —       |                                                                                           |
-| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | —       |                                                                                           |
-| `sizing`             | `"small" \| "medium" \| "default" \| null`                      | no       | —       |                                                                                           |
-| `testId`             | `string`                                                        | no       | —       |                                                                                           |
-| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                           |
-| `value`              | `string \| null`                                                | no       | —       |                                                                                           |
-| `variant`            | `"primary" \| "secondary" \| null`                              | no       | —       |                                                                                           |
+| Prop                 | Type                                                            | Required | Default | Description                                                                                                                                                                                                                       |
+| -------------------- | --------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowClear`         | `boolean`                                                       | no       | —       |                                                                                                                                                                                                                                   |
+| `defaultValue`       | `string \| null`                                                | no       | —       |                                                                                                                                                                                                                                   |
+| `focusVariant`       | `"off" \| "on" \| "default" \| null`                            | no       | —       |                                                                                                                                                                                                                                   |
+| `leftSuffix`         | `ReactNode`                                                     | no       | —       |                                                                                                                                                                                                                                   |
+| `onClear`            | `(() => void)`                                                  | no       | —       |                                                                                                                                                                                                                                   |
+| `onValueBlur`        | `((value: string) => void)`                                     | no       | —       | Called with the unwrapped string value on blur. For the raw event use `onBlur`.                                                                                                                                                   |
+| `onValueChange`      | `((value: string) => void)`                                     | no       | —       | Called with the unwrapped string value on every change. For the raw event use `onChange`.                                                                                                                                         |
+| `prefix`             | `ReactNode`                                                     | no       | —       |                                                                                                                                                                                                                                   |
+| `rightSuffix`        | `ReactNode`                                                     | no       | —       | Content after the input. - `rightSuffixVariant="addon"` truncates it with an ellipsis when the group is narrower than its content. - The ellipsis only renders for inline content — pass text or a `<span>`, not a block element. |
+| `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | —       |                                                                                                                                                                                                                                   |
+| `sizing`             | `"small" \| "medium" \| "default" \| null`                      | no       | —       |                                                                                                                                                                                                                                   |
+| `testId`             | `string`                                                        | no       | —       |                                                                                                                                                                                                                                   |
+| `type`               | `"text" \| "email" \| "date" \| "password" \| "datetime-local"` | no       | —       |                                                                                                                                                                                                                                   |
+| `value`              | `string \| null`                                                | no       | —       |                                                                                                                                                                                                                                   |
+| `variant`            | `"primary" \| "secondary" \| null`                              | no       | —       |                                                                                                                                                                                                                                   |
 
 ### `FormGroup.Help`
 
@@ -207,7 +207,7 @@ Source: `src/blocks/Form/connectors/TextField.tsx`
 | `prefix`             | `ReactNode`                                                     | 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'`.                                                          |
-| `rightSuffix`        | `ReactNode`                                                     | no       | —       |                                                                                                                                                                                                                                                                                                                 |
+| `rightSuffix`        | `ReactNode`                                                     | no       | —       | Content after the input. - `rightSuffixVariant="addon"` truncates it with an ellipsis when the group is narrower than its content. - The ellipsis only renders for inline content — pass text or a `<span>`, not a block element.                                                                               |
 | `rightSuffixVariant` | `"default" \| "addon"`                                          | no       | —       |                                                                                                                                                                                                                                                                                                                 |
 | `sizing`             | `"small" \| "medium" \| "default" \| null`                      | no       | —       |                                                                                                                                                                                                                                                                                                                 |
 | `testId`             | `string`                                                        | no       | —       |                                                                                                                                                                                                                                                                                                                 |
@@ -564,16 +564,17 @@ Source: `src/components/Sidebar/Sidebar.tsx`
 
 > App-shell left navigation rail (host inside `AppShell.Sidebar`). Compound: `Sidebar.Header`, `Sidebar.Content`, `Sidebar.Footer`, `Sidebar.Menu`, `Sidebar.Group`, `Sidebar.SearchInput` (concrete `<input>`, no `asChild`).
 
-| Prop              | Type            | Required | Default | Description                                                     |
-| ----------------- | --------------- | -------- | ------- | --------------------------------------------------------------- |
-| `className`       | `string`        | no       | —       |                                                                 |
-| `container`       | `boolean`       | no       | `false` |                                                                 |
-| `id`              | `string`        | no       | —       |                                                                 |
-| `keepMounted`     | `boolean`       | no       | —       |                                                                 |
-| `mountAfterEnter` | `boolean`       | no       | —       | Hold the panel's content back until it has finished sliding in. |
-| `resizable`       | `boolean`       | no       | `false` |                                                                 |
-| `side`            | `SidebarSide`   | no       | `left`  |                                                                 |
-| `style`           | `CSSProperties` | no       | —       |                                                                 |
+| Prop              | Type            | Required | Default | Description                                                                                                                                                                                                                                                                  |
+| ----------------- | --------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `className`       | `string`        | no       | —       |                                                                                                                                                                                                                                                                              |
+| `container`       | `boolean`       | no       | `false` |                                                                                                                                                                                                                                                                              |
+| `id`              | `string`        | no       | —       |                                                                                                                                                                                                                                                                              |
+| `keepMounted`     | `boolean`       | no       | —       |                                                                                                                                                                                                                                                                              |
+| `mobileTitle`     | `string`        | no       | —       | Accessible name for the sheet the rail becomes under the mobile breakpoint. - Defaults to `Navigation` on the left and `Side panel` on the right. - Rendered visually hidden — the sheet is a dialog and needs a name, but the rail's own header is already the visible one. |
+| `mountAfterEnter` | `boolean`       | no       | —       | Hold the panel's content back until it has finished sliding in.                                                                                                                                                                                                              |
+| `resizable`       | `boolean`       | no       | `false` |                                                                                                                                                                                                                                                                              |
+| `side`            | `SidebarSide`   | no       | `left`  |                                                                                                                                                                                                                                                                              |
+| `style`           | `CSSProperties` | no       | —       |                                                                                                                                                                                                                                                                              |
 
 ### `SectionNav`
 

package/README.md

@@ -120,7 +120,7 @@ Worked examples: `src/components/Button/Button.stories.tsx` (click + disabled),
 
 **Timing-sensitive:** `HoverCard` is the only test driven by a real `userEvent.hover` past a 200 ms open delay (its `findByText` carries a raised timeout). It passes headlessly today, but it's the most likely flake if CI is slow — `Tooltip` deliberately opens via keyboard focus to avoid this. Watch it when wiring CI.
 
-**Runs in CI per-PR (non-blocking).** The `.github/workflows/storybook-component-tests.yml` workflow runs the full suite, wired into `branch.yml` (the `story-tests` job) and gated on the same `detect-affected` design signal as the Storybook deploy — so it only runs when this package (or something it depends on) changes. It is non-blocking: a red run surfaces in the PR Checks tab but doesn't gate the merge. Browser mode isolates per file by default (~35 s/file on a 2-core runner, ~60 min for all 104), so `vitest.config.ts` sets `isolate: false` + `fileParallelism: false` + `maxWorkers: 1` to reuse one browser context across files, and the workflow caches Vite's optimized deps to skip the ~27 s dep pre-bundling on warm runs — bringing the run down to a few minutes. If the suite ever exceeds ~5-6 min, the documented fallback is sharding across a job matrix (and/or full-suite nightly + changed-stories-only on PR). Tracked in UT-4191. Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
+**Runs in CI per-PR and gates the merge (UT-4864).** The `.github/workflows/storybook-component-tests.yml` workflow runs the full suite, wired into `branch.yml` (the `story-tests` job) and gated on the same `detect-affected` design signal as the Storybook deploy — so it only runs when this package (or something it depends on) changes. The required status check is `Storybook story gate`, not the job itself: a reusable-workflow job publishes its check under a different name depending on whether it ran, so the gate job is what reports on every PR (`scripts/storybookStoryGate.mjs`). Browser mode isolates per file by default (~35 s/file on a 2-core runner — over an hour for the current 157 story files), so `vitest.config.ts` sets `isolate: false` + `fileParallelism: false` + `maxWorkers: 1` to reuse one browser context across files, and the workflow caches Vite's optimized deps to skip the ~27 s dep pre-bundling on warm runs — bringing the run down to a few minutes. If the suite ever exceeds ~5-6 min, the documented fallback is sharding across a job matrix (and/or full-suite nightly + changed-stories-only on PR). Measured over 526 executed runs in the week to 2026-09-17: job wall-clock p50 146 s / p90 161 s, of which the test step itself is 61 s — the rest is runner setup, so the suite has room to roughly quadruple before the budget bites. Sharding is not a free lever, though: `isolate: false` makes the run order-dependent, and resharding changes it. Before touching either, prove the suite still passes shuffled (`vitest run --config vitest.config.ts --sequence.shuffle=true`). Adding `@storybook/addon-a11y` for per-story accessibility checks is a separate follow-up.
 
 #### Story-test coverage (UT-4189)