@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/ai/components/radio-group.md

@@ -302,6 +302,7 @@ Hovering an unselected, enabled option darkens its ring (`text-muted`) with the
 - Pressed (an option held down): its ring border turns `text`; not while disabled or read-only.
 - Disabled: ring border `surface-sunken`, background `surface-muted`; option label `text-disabled`, description `text-muted`.
 - Read-only: ring background `surface-muted`, no hover, default cursor.
+- Motion: the dot grows in and shrinks out over 150 ms on `ease-md` (a fade only under reduced motion); an error message fades in (`animate-message-in`).
 - Legend: `text-muted`. Error text: `danger`. Focus ring: `ring`.
 
 The legend, the options and the error text sit 6 px apart; each ring sits 10 px from its label.
@@ -374,6 +375,11 @@ Focuses the checked radio, else the first enabled one; Signal Forms calls it fro
 
 ## Migration notes
 
+### 0.5.0
+
+The selected option's dot grows in and the previous one shrinks away (150 ms on `ease-md`);
+under reduced motion they only fade. An error message fades in when it appears.
+
 ### 0.3.0
 
 New exported `BfRadioGroupOrientation` (`'vertical' | 'horizontal'`), the type of `orientation`

package/ai/components/segmented.md

@@ -104,6 +104,8 @@ export class SegmentedBasicExampleComponent {
 `value` is `null` while no segment is selected; the first enabled segment then owns the tab stop.
 `(changed)` emits the chosen value after a user change.
 
+The selected pill slides to the newly chosen segment, changing width as it goes (200 ms, `--bf-duration-layout`); it lands in place at once on the first render and after a resize, and always under `prefers-reduced-motion`.
+
 ## Typed values
 
 The control is generic over the option value: numbers, ids and objects bind directly.
@@ -330,7 +332,7 @@ Hovering an inactive segment darkens its label to `text`, and the active one tak
 ## Theming
 
 - Track: `surface-sunken`.
-- Active segment: `surface` / `text` with the `shadow-segment` elevation and a 1.5 px inset `primary-strong` outline (≥ 3:1 on `surface` and the track, so the selection does not rest on the fill), hover `surface-muted` (under `forced-colors`, `Highlight` / `HighlightText` with a `CanvasText` outline). Inactive: `text-muted`, hover `text`. Pressed (editable only): `surface-pressed` with `text` (the selected segment keeps `Highlight` under `forced-colors`).
+- Active segment: `surface` / `text` with the `shadow-segment` elevation and a 1.5 px inset `primary-strong` outline (≥ 3:1 on `surface` and the track, so the selection does not rest on the fill), hover `surface-muted` (under `forced-colors`, `Highlight` / `HighlightText` with a `CanvasText` outline). Inactive: `text-muted`, hover `text`. Pressed (editable only): `surface-pressed` with `text` (the selected segment keeps `Highlight` under `forced-colors`). The pill slides over `--bf-duration-layout` with the `ease-md` curve.
 - Read-only: track `surface-muted`, no hover, default cursor. Error: the track gets a 1.5 px `danger-border` ring and the message below is `danger`.
 - Focus ring: `ring`, drawn past a 2 px `surface` offset so it sits on `surface` (≥ 3:1) rather than on the track. Disabled segments: `text-disabled` with `cursor-not-allowed`; an unselected one takes the `surface-sunken` fill, the selected one keeps its `surface` pill without the shadow, outlined in `text-disabled` (never opacity).
 - Shape (track and segments): `rounded-control` (`--radius-control`, `9999px` by default).
@@ -339,7 +341,7 @@ Segments are at least 24/32/40 px tall inside the track's 4 px padding. Under a
 
 ## Accessibility
 
-`role="radiogroup"` with `aria-label` from `label` (else `ariaLabel`, or `aria-labelledby` from `ariaLabelledby`); each segment is a `<button role="radio">` with `aria-checked` mirroring selection. Only the selected (or first enabled) segment sits in the tab order — the rest carry `tabindex="-1"` — and ArrowRight/Down, ArrowLeft/Up, Home and End move the selection and focus like a native radio group, matching platform expectations. `disabled` segments are skipped by keyboard navigation and get the native attribute. The group carries `aria-required`, and once touched and invalid `aria-invalid="true"` with `aria-describedby` and `aria-errormessage` pointing at the error text. Read-only: `aria-readonly="true"` on the group; the tab stop stays focusable and selection by pointer or keyboard is ignored. `focus()` focuses the tab-stop segment; Signal Forms calls it from `focusBoundControl()`. Under forced colours (Windows High Contrast) the selected segment opts out of the adjustment (`forced-color-adjust: none`) and paints `Highlight`/`HighlightText` itself with a `CanvasText` selected outline, focus outline and focus ring (on a `Canvas` offset) and no shadow, so it paints system colours only and so no text backplate hides its label; a disabled selected segment's outline is `GrayText` instead; the others repaint in `ButtonText`.
+`role="radiogroup"` with `aria-label` from `label` (else `ariaLabel`, or `aria-labelledby` from `ariaLabelledby`); each segment is a `<button role="radio">` with `aria-checked` mirroring selection. Only the selected (or first enabled) segment sits in the tab order — the rest carry `tabindex="-1"` — and ArrowRight/Down, ArrowLeft/Up, Home and End move the selection and focus like a native radio group, matching platform expectations. `disabled` segments are skipped by keyboard navigation and get the native attribute. The group carries `aria-required`, and once touched and invalid `aria-invalid="true"` with `aria-describedby` and `aria-errormessage` pointing at the error text. Read-only: `aria-readonly="true"` on the group; the tab stop stays focusable and selection by pointer or keyboard is ignored. The sliding pill is one decorative `aria-hidden` element of the track. `focus()` focuses the tab-stop segment; Signal Forms calls it from `focusBoundControl()`. Under forced colours (Windows High Contrast) the selected segment opts out of the adjustment (`forced-color-adjust: none`) and paints `Highlight`/`HighlightText` itself with a `CanvasText` selected outline, focus outline and focus ring (on a `Canvas` offset) and no shadow, so it paints system colours only and so no text backplate hides its label; a disabled selected segment's outline is `GrayText` instead; the others repaint in `ButtonText`.
 
 ### Keyboard
 
@@ -422,6 +424,16 @@ missing, or it is already selected.
 
 ## Migration notes
 
+### 0.5.0
+
+The selected segment's pill (surface fill, `shadow-segment`, `primary-strong` outline,
+`Highlight` under forced colours) is now one indicator element of the track that slides to the
+newly chosen segment, changing width as it goes (`--bf-duration-layout`, `ease-md`). The first
+placement and a resize land at once, and so does everything under `prefers-reduced-motion`. The
+selected segment's hover and pressed fills move with it. Until it has been measured (jsdom,
+server render, a hidden control) the segment keeps painting its own pill. `bf-theme-switch`
+slides the same way. The indicator is `aria-hidden`; roles, keyboard and focus are unchanged.
+
 ### 0.3.0
 
 **Breaking:** typed values. `BfSegmentedComponent<T = string>` is generic over the option value

package/ai/components/select.md

@@ -1,14 +1,15 @@
 # bf-select
 
-Native single-choice dropdown styled like the text field, with Signal Forms binding
+Single-choice dropdown with a styled list, native under touch, with Signal Forms binding
 
-`BfSelectComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+`BfSelectComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.1.0
 
 ## Example
 
 ```ts
 import { Component, computed, signal } from '@angular/core';
-import { BfButtonComponent, BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * The bf-select overview.
@@ -91,11 +92,16 @@ export class SelectOverviewExampleComponent {
 
 ## Overview
 
-Native single-choice dropdown styled like the text field, with a placeholder option and
-Signal Forms binding. Generic over the option value (a string by default); `null` means nothing
-is selected.
+Single-choice dropdown styled like the text field, with a placeholder and Signal Forms binding.
+Under a mouse it opens a styled list (the combobox's) that follows the select-only combobox
+pattern: the arrow keys, `Home`, `End`, `PageUp`/`PageDown` and typeahead move through it,
+`Enter`, `Space` or `Tab` pick. Under a coarse pointer (touch) it renders the platform's native
+select instead. Generic over the option value (a string by default); `null` means nothing is
+selected. Moved from `@bitforgehq/ui` to `@bitforgehq/ui/overlay` in 0.5.0.
 
-A single-choice dropdown built on the native `<select>`, so it opens the platform picker on phones and stays keyboard-accessible everywhere. Styled like the text field with a CSS chevron.
+A single-choice dropdown styled like the text field, with a CSS chevron. Under a mouse it opens a styled list, the same panel as [bf-combobox](https://bitforge-ui.web.app/components/combobox) without the search: rounded, floating, with a check mark on the chosen option, exactly as wide as the field. Under a coarse pointer (`matchMedia('(pointer: coarse)')`, a phone or a Capacitor app) it renders the native `<select>` with the same label, help and error text instead, so a phone opens its own picker. Closed, both look the same.
+
+Import `BfSelectComponent` from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the list: `bun add @angular/cdk rxjs`). The list opens in the CDK overlay container, so it is never clipped by a scrolling parent and works inside a `BfDialogService` dialog. `BfSelectOption` is exported from both `@bitforgehq/ui` and `@bitforgehq/ui/overlay`. Before 0.5.0 the select lived in `@bitforgehq/ui`; see [Migration notes](#migration-notes).
 
 ## When to use
 
@@ -105,7 +111,7 @@ Use `bf-select` to choose one value from a list too long to show at once: a coun
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** A select of projects with a placeholder until one is picked. */
 @Component({
@@ -143,7 +149,7 @@ string conversion. `BfSelectOption` defaults to `string`; type it for anything e
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** A select of numeric team ids: the bound value is a `number | null`. */
 @Component({
@@ -171,7 +177,7 @@ instance (reloaded from a server), pass `compareWith`:
 ```ts
 import { Component, signal } from '@angular/core';
 import { FormField, form } from '@angular/forms/signals';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 interface Team {
   id: number;
@@ -202,10 +208,12 @@ export class SelectCompareWithExampleComponent {
 }
 ```
 
-`compareWith` is called as `compareWith(optionValue, value)`. A string, number or boolean option
-value is also the native `<option value>` (`"42"` for `42`), so a native form post and browser
-tests (`selectOption('42')`) see it; an object option's native value is its index. A choice is
-mapped back by position, so the model always gets the option's real value. An option whose value is `null` is not supported: `null` means nothing is selected, so such an
+`compareWith` is called as `compareWith(optionValue, value)`. With `name` set, a form post carries
+the chosen option's key: a string, number or boolean option value as text (`"42"` for `42`), an
+object option's index. Under a mouse a hidden input carries it; under touch it is the native
+`<option value>`. A choice is mapped back by position, so the model always gets the option's real
+value. In tests, pick options by label with `BfSelectHarness` from `@bitforgehq/ui/testing`, which
+drives both modes. An option whose value is `null` is not supported: `null` means nothing is selected, so such an
 option never shows as selected.
 
 Migrating from 0.2: "nothing selected" is `null` (it was `''`). Type bound signals and fields
@@ -217,7 +225,7 @@ Migrating from 0.2: "nothing selected" is `null` (it was `''`). Type bound signa
 ```ts
 import { Component, signal } from '@angular/core';
 import { FormField, form } from '@angular/forms/signals';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** A select bound to a Signal Forms field. */
 @Component({
@@ -240,15 +248,14 @@ Reactive Forms, bind a `FormControl<T | null>` through `[formControl]` or `formC
 
 ## Read-only
 
-`readonly` shows the chosen option on the muted surface and blocks changes. A mouse press focuses
-the select without opening the picker, and the picker keys (arrows, Alt+Arrow, Enter, Space, F4,
-type-ahead) do nothing. On touch screens the platform picker can still open, because the browser
-gives no press to cancel; a choice made there snaps back to the bound value, so the value never
-changes. The select stays in the tab order. Signal Forms binds it from `readonly()` rules.
+`readonly` shows the chosen option on the muted surface and blocks changes. The field stays in the
+tab order, but a click or a key never opens the list. Under touch, the platform picker can still
+open, because the browser gives no press to cancel; a choice made there snaps back to the bound
+value, so the value never changes. Signal Forms binds it from `readonly()` rules.
 
 ```ts
 import { Component } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** A read-only select. */
 @Component({
@@ -273,7 +280,7 @@ of the two. Both are ignored while `label` is set.
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** A small toolbar select named by `ariaLabel`. */
 @Component({
@@ -298,7 +305,7 @@ export class SelectUnlabelledExampleComponent {
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /** The sm, md and lg select sizes. */
 @Component({
@@ -329,7 +336,8 @@ Once the control is touched it shows the first error as text: the error's own `m
 ```ts
 import { Component, signal } from '@angular/core';
 import { FormField, FormRoot, form, required } from '@angular/forms/signals';
-import { BfButtonComponent, BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * A required select with the default message.
@@ -367,36 +375,61 @@ export class SelectValidationExampleComponent {
 }
 ```
 
+## In a table
+
+A stacked `bf-table` with sortable columns shows a "Sort by" select above its rows. Add `provideBfSelect()` from `@bitforgehq/ui/overlay` to the app's providers (`ApplicationConfig.providers`) so that select is the styled `bf-select` too; without it, the table, which lives in the cdk-free `@bitforgehq/ui`, falls back to the native one. `provideBfSelect()` imports `bf-select` (and the CDK overlay it uses) into the bundle that holds the app config, usually the initial one; when the stacked tables sit behind lazy routes, add it to the `providers` of a route in a lazily loaded routes file instead, or provide `{ provide: BF_TABLE_SORT_SELECT, useValue: BfSelectComponent }` on the component that holds the table, as this site's stacked table example does.
+
+## Migration notes
+
+### 0.5.0
+
+- `bf-select` moved from `@bitforgehq/ui` to `@bitforgehq/ui/overlay`: change `import { BfSelectComponent } from '@bitforgehq/ui'` to `import { BfSelectComponent } from '@bitforgehq/ui/overlay'`. The selector, inputs, outputs and Signal Forms binding are unchanged.
+- The overlay entry needs `@angular/cdk` (and `rxjs`): `bun add @angular/cdk rxjs`.
+- `BfSelectOption` stays importable from `@bitforgehq/ui`, and is also exported from `@bitforgehq/ui/overlay`.
+- Add `provideBfSelect()` to the app's providers so a stacked `bf-table`'s "Sort by" control is the styled select (see [In a table](#in-a-table)); without it, that control stays native.
+- Under a mouse the control is no longer a `<select>`: `checkValidity()` and the browser's own "required" popup are not part of the styled mode. Enforce `required` through Signal Forms (`required()`) or your own check; `aria-required` still announces it. A form post keeps working through a hidden input when `name` is set.
+- Tests that set a `<select>`'s value directly break under a mouse; pick by label with `BfSelectHarness` (`selectOption()`, `getValueLabel()`, the new `isOpen()`), which drives both modes alike: `getOptionLabels()` reads a read-only or disabled select's options too, and `selectOption()` on a read-only select changes nothing.
+
 ## Desktop
 
-Hover darkens the border (`text-muted`, `danger` in the error state) with the pointer cursor; a read-only select keeps the default cursor. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The `primary` border and the focus ring show on every focus, as on the text fields. The picker is the browser's own list, so it matches the operating system. Fields default to `md` (40 px); `provideBfDefaults({ fieldSize: 'sm' })` gives 32 px selects for toolbars and filter bars ([density guide](https://bitforge-ui.web.app/density)).
+Hover darkens the border (`text-muted`, `danger` in the error state) with the pointer cursor; a read-only select keeps the default cursor. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The `primary` border and the focus ring show on every focus, as on the text fields. A click on the field opens the list below it (above it when there is no room below), with the chosen option active; the list follows the field while it is open, and a click outside closes it. The pointer moving over an option makes it the active one. Options are 32, 36 or 44 px tall with the field's size. Fields default to `md` (40 px); `provideBfDefaults({ fieldSize: 'sm' })` gives 32 px selects for toolbars and filter bars ([density guide](https://bitforge-ui.web.app/density)).
 
 ## Theming
 
 - Border: `border-strong` (the control boundary, ≥ 3:1), switching to `danger-border` on error; focus: `primary` border with a `ring` ring.
 - Hover (pointer cursor): border `text-muted`, or `danger` in the error state.
 - Disabled: `surface-sunken` border, `surface-muted` background, `text-disabled` text. Read-only: `surface-muted` background, default cursor. Placeholder text: `text-muted` (≥ 4.5:1). Chevron: `text-subtle`.
+- List: `bg-surface`, a 1 px `border-border`, `rounded-card`, `shadow-floating`; the active option `surface-muted`, the chosen option `primary-text` with a check mark, a disabled one `text-disabled`. In forced colours the active option takes the system highlight.
 - Label, help and error text come from the `bf-field` wrapper (see its Theming section).
 
 ## Accessibility
 
-Native `<select>`, so it opens the platform's own picker on phones and stays fully keyboard-operable. `bf-field` renders the `<label for>`; the select itself wires `aria-describedby` to the help paragraph and the error paragraph under it (both while shown, help first) and, while it is invalid, `aria-errormessage` to the error paragraph; `aria-invalid` is set once touched and invalid (an explicit `errorMessage` shows immediately). The `placeholder`, when set, is a disabled option so it can be shown but never chosen. `aria-label` and `aria-labelledby` carry `ariaLabel` and `ariaLabelledby` only while there is no visible `label`. Read-only: `aria-readonly="true"`, the select stays focusable, a mouse press focuses it without opening the picker, the picker keys (arrows, Alt+Arrow, Enter, Space, F4, type-ahead) are blocked, and a change that still gets through (the platform picker on touch screens) is reverted, so the value never changes. `focus()` focuses the native select; Signal Forms calls it from `focusBoundControl()`.
+Under a mouse the field follows the [select-only combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/) pattern: it is a focusable `role="combobox"` with `aria-haspopup="listbox"`, `aria-expanded`, and while open `aria-controls` (the listbox) and `aria-activedescendant` (the active option). Focus never leaves the field. The list is a `listbox` named like the field, its options `role="option"` with `aria-selected` and `aria-disabled`. `required` is announced with `aria-required`.
+
+Under touch it is a native `<select>`, so it opens the platform's own picker and stays fully keyboard-operable. The `placeholder`, when set, is a disabled option so it can be shown but never chosen.
+
+In both modes `bf-field` renders the label; the control wires `aria-describedby` to the help paragraph and the error paragraph under it (both while shown, help first) and, while it is invalid, `aria-errormessage` to the error paragraph; `aria-invalid` is set once touched and invalid (an explicit `errorMessage` shows immediately). With a visible `label` the label names the control alone: the native select through its `<label for>`, the styled field (a div, which a `<label for>` cannot name) through `aria-labelledby` pointing at the label's id, as in the APG example. `ariaLabel` and `ariaLabelledby` become `aria-label` and `aria-labelledby` only while there is no visible `label`. A hidden input carrying `name` posts nothing while the select is disabled. Read-only: `aria-readonly="true"`, the control stays focusable and the value never changes. Disabled: `aria-disabled="true"` (the native `disabled` under touch) and out of the tab order. `focus()` focuses the field, or the native select under touch; Signal Forms calls it from `focusBoundControl()`.
+
+Motion (styled mode): the list grows out of the field as it opens (a fade, a slight scale and a 4 px slide, 180 ms) and fades back as it closes (130 ms). The field's state changes at once and the closing list is inert. Under `prefers-reduced-motion` the list only fades.
 
 ### Keyboard
 
-The select is a native `<select>`, so these are the browser's keys and differ slightly between operating systems. While `readonly`, the picker and type-ahead keys are blocked; <kbd>Tab</kbd> and <kbd>Escape</kbd> still work.
+Under a mouse (the styled list). While `readonly`, no key opens the list or changes the value; <kbd>Tab</kbd> still moves on.
 
-| Key                                                  | Action                                                                                                                                                                   |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>     | Moves focus to and from the select; a `readonly` one stays in the tab order                                                                                              |
-| <kbd>Space</kbd>                                     | Opens the picker                                                                                                                                                         |
-| <kbd>Alt</kbd>+<kbd>ArrowDown</kbd> / <kbd>F4</kbd>  | Opens the picker on Windows and Linux                                                                                                                                    |
-| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>            | Closed: chooses the previous / next option on Windows and Linux (<kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> too), opens the picker on macOS; open: moves the highlight |
-| <kbd>Home</kbd> / <kbd>End</kbd>                     | Closed on Windows and Linux: chooses the first / last option; open: highlights the first / last option                                                                   |
-| <kbd>PageUp</kbd> / <kbd>PageDown</kbd>              | Moves several options up / down (to the first / last in a short list)                                                                                                    |
-| <kbd>Enter</kbd>                                     | In the open picker: chooses the highlighted option                                                                                                                       |
-| <kbd>Escape</kbd>                                    | Closes the open picker without changing the value                                                                                                                        |
-| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd> | Type-ahead: moves to the next option whose label starts with the typed text                                                                                              |
+| Key                                                                             | Where     | Action                                                                                                                       |
+| ------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd> | Field     | Opens the list on the chosen option (else the first enabled one); <kbd>Alt</kbd>+<kbd>ArrowDown</kbd> too                    |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>                                       | Open list | Next / previous enabled option, wrapping at the ends                                                                         |
+| <kbd>Home</kbd> / <kbd>End</kbd>                                                | Open list | First / last enabled option                                                                                                  |
+| <kbd>PageUp</kbd> / <kbd>PageDown</kbd>                                         | Open list | Moves ten enabled options up / down, stopping at the first / last                                                            |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                                             | Open list | Picks the active option and closes the list                                                                                  |
+| <kbd>Tab</kbd>                                                                  | Open list | Picks the active option, closes the list and moves focus on                                                                  |
+| <kbd>Escape</kbd>                                                               | Open list | Closes the list without changing the value (a dialog underneath stays open)                                                  |
+| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd>                            | Field     | Typeahead: opens the list and makes the next option whose label starts with the typed text active (case and accents ignored) |
+
+Typed keys within half a second form one search ("New Y"); the same letter typed again cycles through the options starting with it. Typeahead and the arrows only move the active option: the value changes on <kbd>Enter</kbd>, <kbd>Space</kbd>, <kbd>Tab</kbd> or a click, so `changed` fires once per pick. The pointer moving over an option makes it the active one, so a following <kbd>Tab</kbd> picks it, as in the combobox.
+
+Under touch (the native select) the keys are the browser's own and differ slightly between operating systems: <kbd>Space</kbd> (or <kbd>Alt</kbd>+<kbd>ArrowDown</kbd> / <kbd>F4</kbd> on Windows and Linux) opens the picker, the arrows, <kbd>Home</kbd> / <kbd>End</kbd> and typeahead choose, <kbd>Escape</kbd> closes it.
 
 ## Inputs
 
@@ -408,7 +441,7 @@ The select is a native `<select>`, so these are the browser's keys and differ sl
 | `label`          | `string`                                                    | `''`        | Visible label above the control.                                                                                                           |
 | `ariaLabel`      | `string`                                                    | `''`        | Accessible name when no visible label is rendered (e.g. a table filter). Ignored when `label` is set.                                      |
 | `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                |
-| `placeholder`    | `string`                                                    | `''`        | Disabled first option shown while nothing is selected.                                                                                     |
+| `placeholder`    | `string`                                                    | `''`        | Muted text shown while nothing is selected.                                                                                                |
 | `helpText`       | `string`                                                    | `''`        | Helper text under the control.                                                                                                             |
 | `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                            |
 | `disabled`       | `boolean`                                                   | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                       |
@@ -417,7 +450,7 @@ The select is a native `<select>`, so these are the browser's keys and differ sl
 | `invalid`        | `boolean`                                                   | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                           |
 | `touched`        | `boolean`                                                   | `false`     | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                        |
 | `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                        |
-| `name`           | `string`                                                    | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                      |
+| `name`           | `string`                                                    | `''`        | Form name: of a hidden input carrying the selected option's key, or of the native select. Set by `[formField]`; do not bind it yourself.   |
 | `id`             | `string`                                                    | `generated` | Control id; generated when not set.                                                                                                        |
 | `value`          | `T \| null`                                                 | `null`      | The selected option's value, `null` while nothing is selected; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.          |
 
@@ -434,7 +467,8 @@ The select is a native `<select>`, so these are the browser's keys and differ sl
 
 ### `focus(options?: FocusOptions): void`
 
-Focuses the native select; Signal Forms calls it from `focusBoundControl()`.
+Focuses the field, or the native select under a coarse pointer; Signal Forms calls it from
+`focusBoundControl()`.
 
 | Parameter  | Type           | Description                                                           |
 | ---------- | -------------- | --------------------------------------------------------------------- |
@@ -445,7 +479,8 @@ Focuses the native select; Signal Forms calls it from `focusBoundControl()`.
 ### Do
 
 - Provide a `placeholder` when no option is a sensible default, and make the field required.
-- Keep option labels short; long labels are truncated by the native control.
+- Keep option labels short; a long label is truncated in the field.
+- Add `provideBfSelect()` once when a page has a stacked, sortable `bf-table`: in the app config, or on the lazy route that holds the table, so the styled select and the CDK overlay stay out of the initial bundle.
 
 ### Don't
 
@@ -453,6 +488,29 @@ Focuses the native select; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.5.0
+
+**Breaking:** `bf-select` moved from `@bitforgehq/ui` to `@bitforgehq/ui/overlay` (see
+Migration). Under a fine pointer it now opens a styled list, the combobox's panel without the
+search, exactly as wide as the field: a focusable `role="combobox"` field following the APG
+select-only combobox pattern (Enter, Space, the arrows and Alt+ArrowDown open; the arrows,
+Home/End and PageUp/PageDown move; Enter, Space, Tab or a click pick; Escape closes without
+closing a dialog underneath). Typeahead (500 ms buffer, case and accents ignored) moves the active
+option, open or closed, and never commits on its own. Under a coarse pointer
+(`matchMedia('(pointer: coarse)')`, followed live) it renders the native `<select>` as before;
+on the server it renders the styled field. With `name` set, a hidden input carries the chosen
+option's key, so plain form posts keep working (none while disabled). With a visible `label` the
+field is named by `aria-labelledby` pointing at the label (a `<label for>` cannot name a div);
+`ariaLabel` and `ariaLabelledby` still apply only without one. Under forced colours a disabled
+field shows `GrayText`. `@bitforgehq/ui/testing`: `BfSelectHarness` drives both modes by label,
+and has a new `isOpen()`; in both modes `getOptionLabels()` reads a read-only or disabled
+select's options, and `selectOption()` on a read-only select changes nothing.
+
+The styled list animates open and closed with the popover's motion (180 ms in, 130 ms out). The
+field's `aria-expanded` and focus change at once; the closing list is inert and keeps the options
+it showed until it is gone. Under `prefers-reduced-motion` it only fades. The native select under
+touch is unchanged.
+
 ### 0.3.0
 
 **Breaking:** typed values. `BfSelectComponent<T = string>` is generic over the option value

package/ai/components/sidebar-toggle.md

@@ -41,11 +41,13 @@ interface NavLink {
   template: `
     <div class="border-border bg-bg rounded-card flex h-72 overflow-hidden border">
       <bf-sidebar label="Toggle demo" [(collapsed)]="collapsed">
-        <div bfSlot="header" class="flex items-center justify-between gap-2">
-          @if (!collapsed()) {
-            <span class="text-heading text-text ps-3">Atlas</span>
-          }
-          <bf-sidebar-toggle>
+        <!-- The brand fades while it narrows to nothing, so the toggle slides with the edge. -->
+        <div bfSlot="header" class="flex items-center">
+          <span
+            class="text-heading text-text ease-md min-w-0 flex-1 truncate ps-3 pe-2 transition-[opacity,padding] duration-(--bf-duration-layout) in-data-collapsed:ps-0 in-data-collapsed:pe-0 in-data-collapsed:opacity-0 motion-reduce:transition-none"
+            >Atlas</span
+          >
+          <bf-sidebar-toggle class="shrink-0">
             <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
             <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
           </bf-sidebar-toggle>
@@ -134,7 +136,7 @@ interface NavLink {
  * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
  * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
  * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
- * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * line closes and fades out. The theme binds a local signal so the docs site keeps its theme; an app binds
  * `BfColorSchemeService.scheme`.
  */
 @Component({
@@ -176,8 +178,13 @@ interface NavLink {
             <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
           </bf-sidebar-toggle>
         </div>
-        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
-          Version 0.3.2
+        <!-- The version line closes and fades on the sidebar's timing (a grid row from 1fr to
+             0fr), so the footer shrinks smoothly instead of jumping. -->
+        <p
+          bfSlot="footer"
+          class="text-caption text-text-muted ease-md grid grid-rows-[1fr] ps-3 transition-[grid-template-rows,opacity] duration-(--bf-duration-layout) in-data-collapsed:grid-rows-[0fr] in-data-collapsed:opacity-0 motion-reduce:transition-none"
+        >
+          <span class="min-h-0 min-w-0 truncate">Version 0.3.2</span>
         </p>
       </bf-sidebar>
       <div class="min-w-0 flex-1 p-4">
@@ -195,7 +202,7 @@ export class SidebarFooterExampleComponent {
 
   /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
   protected readonly rowClasses = computed(() =>
-    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+    this.collapsed() ? 'flex flex-col items-start gap-1' : 'flex items-center justify-between',
   );
   protected readonly themeIcon = computed(
     () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],

package/ai/components/sidebar.md

@@ -41,7 +41,8 @@ interface NavLink {
  * Live demo of `bf-sidebar`: a brand and a collapse toggle in the header, two `bf-nav-group`s of
  * `a[bfNavItem]` router links (this page is the current one, one item has a count badge) and a
  * footer link. The toggle binds `[(collapsed)]`; collapsed, the items show their icon only and
- * name themselves in a tooltip. The result line reports the state.
+ * name themselves in a tooltip. The width, the labels and the brand animate together (instantly
+ * under reduced motion). The result line reports the state.
  */
 @Component({
   selector: 'app-example-sidebar-overview',
@@ -57,11 +58,15 @@ interface NavLink {
   template: `
     <div class="border-border bg-bg rounded-card flex h-96 overflow-hidden border">
       <bf-sidebar label="Docs" [(collapsed)]="collapsed">
-        <div bfSlot="header" class="flex items-center justify-between gap-2">
-          @if (!collapsed()) {
-            <span class="text-heading text-text ps-3">Atlas</span>
-          }
+        <!-- The brand stays in the DOM and fades while it narrows to nothing, on the sidebar's
+             own timing, so the toggle slides with the edge instead of jumping. -->
+        <div bfSlot="header" class="flex items-center">
+          <span
+            class="text-heading text-text ease-md min-w-0 flex-1 truncate ps-3 pe-2 transition-[opacity,padding] duration-(--bf-duration-layout) in-data-collapsed:ps-0 in-data-collapsed:pe-0 in-data-collapsed:opacity-0 motion-reduce:transition-none"
+            >Atlas</span
+          >
           <bf-icon-button
+            class="shrink-0"
             variant="text"
             [label]="collapsed() ? 'Expand sidebar' : 'Collapse sidebar'"
             (clicked)="collapsed.set(!collapsed())"
@@ -157,7 +162,13 @@ Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActiv
 
 ## Collapsing to an icon rail
 
-`collapsed` is a model. Put a [`bf-sidebar-toggle`](https://bitforge-ui.web.app/components/sidebar-toggle) (`@bitforgehq/ui/overlay`) in the header or footer: it flips the model, names itself by what the next press does ("Collapse sidebar", "Expand sidebar") and takes its two icons as slots, since a widget never imports one. Bind `[(collapsed)]` to keep the state in your own signal, or bind it to your own button outside the sidebar. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+`collapsed` is a model. Put a [`bf-sidebar-toggle`](https://bitforge-ui.web.app/components/sidebar-toggle) (`@bitforgehq/ui/overlay`) in the header or footer: it flips the model, names itself by what the next press does ("Collapse sidebar", "Expand sidebar") and takes its two icons as slots, since a widget never imports one. Bind `[(collapsed)]` to keep the state in your own signal, or bind it to your own button outside the sidebar. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. Expanded the sidebar is `w-60` (240 px); the rail is one item square of the app's `controlSize` plus the 12 px padding on each side: 56, 64 or 72 px for `sm`, `md` and `lg`, and 68 px under a coarse pointer for `sm` and `md`, where items are 44 px wide.
+
+## Motion
+
+Collapsing and expanding animate on the layout timing (`--bf-duration-layout`, 200 ms, on `ease-md`): the width moves, the item labels and group headings fade while the row narrows to its icon, the icons stay where they are, and the count pill shrinks away while its dot grows in. Content beside the sidebar, such as the [`bf-app-frame`](https://bitforge-ui.web.app/components/app-frame) content column, moves with it. Under `prefers-reduced-motion: reduce` the sidebar switches at once, and the first render never animates, so a collapsed state restored by `provideBfSidebarState()` is simply there on load.
+
+Your own `header` and `footer` content can follow on the same timing: the host carries `data-collapsed` while collapsed, so Tailwind's `in-data-collapsed:` variant styles anything inside it. Keep the content in the DOM and let the sidebar clip it rather than removing it with `@if`, which makes it jump: fade a brand name with `transition-opacity duration-(--bf-duration-layout) ease-md in-data-collapsed:opacity-0 motion-reduce:transition-none`, and close a block (an account card, a version line) with a grid row, `grid grid-rows-[1fr] in-data-collapsed:grid-rows-[0fr]` around a `min-h-0 overflow-hidden` child, transitioning `grid-template-rows`. The overview and footer examples do both.
 
 ## Remember the collapsed sidebar
 
@@ -218,7 +229,7 @@ export class SidebarRememberedExampleComponent {
 
 ## Footer
 
-The footer slot takes several elements, stacked with a 4 px gap: a Settings link as an `a[bfNavItem]`, a row holding an icon-only text [`bf-theme-menu-button`](https://bitforge-ui.web.app/components/theme-menu-button) and the `bf-sidebar-toggle`, and an optional version line in `text-caption text-text-muted`. Expanded, the row puts the two buttons at either end (`flex items-center justify-between`). As an icon rail every footer element is centred: switch the row to a column (`flex flex-col items-center gap-1`) so both buttons fit the rail, and hide the version line (`[class.hidden]="collapsed()"`), which has no icon to shrink to. Open the theme menu upwards (`placement="above-start"`), since the footer sits at the bottom of the screen.
+The footer slot takes several elements, stacked with a 4 px gap: a Settings link as an `a[bfNavItem]`, a row holding an icon-only text [`bf-theme-menu-button`](https://bitforge-ui.web.app/components/theme-menu-button) and the `bf-sidebar-toggle`, and an optional version line in `text-caption text-text-muted`. Expanded, the row puts the two buttons at either end (`flex items-center justify-between`). As an icon rail switch the row to a column (`flex flex-col items-start gap-1`) so both buttons fit the rail; aligned to the start, the theme button does not move while the width animates. Close the version line, which has no icon to shrink to, with a grid row (`in-data-collapsed:grid-rows-[0fr]`, see Motion) so the footer shrinks smoothly. Open the theme menu upwards (`placement="above-start"`), since the footer sits at the bottom of the screen.
 
 ```ts
 import { Component, computed, signal } from '@angular/core';
@@ -250,7 +261,7 @@ interface NavLink {
  * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
  * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
  * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
- * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * line closes and fades out. The theme binds a local signal so the docs site keeps its theme; an app binds
  * `BfColorSchemeService.scheme`.
  */
 @Component({
@@ -292,8 +303,13 @@ interface NavLink {
             <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
           </bf-sidebar-toggle>
         </div>
-        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
-          Version 0.3.2
+        <!-- The version line closes and fades on the sidebar's timing (a grid row from 1fr to
+             0fr), so the footer shrinks smoothly instead of jumping. -->
+        <p
+          bfSlot="footer"
+          class="text-caption text-text-muted ease-md grid grid-rows-[1fr] ps-3 transition-[grid-template-rows,opacity] duration-(--bf-duration-layout) in-data-collapsed:grid-rows-[0fr] in-data-collapsed:opacity-0 motion-reduce:transition-none"
+        >
+          <span class="min-h-0 min-w-0 truncate">Version 0.3.2</span>
         </p>
       </bf-sidebar>
       <div class="min-w-0 flex-1 p-4">
@@ -311,7 +327,7 @@ export class SidebarFooterExampleComponent {
 
   /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
   protected readonly rowClasses = computed(() =>
-    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+    this.collapsed() ? 'flex flex-col items-start gap-1' : 'flex items-center justify-between',
   );
   protected readonly themeIcon = computed(
     () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],
@@ -481,12 +497,13 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 ## Theming
 
 - Surface: `surface` with a `border` line on its inline-end edge (`border-e`); 12 px padding and 24 px between the header, the groups and the footer.
-- Width: `w-60` (240 px) expanded, the icon rail's own width collapsed.
+- Width: `w-60` (240 px) expanded; collapsed, a rail of one `controlSize` square plus padding (`w-14`, `w-16` or `w-18`; `w-17` under a coarse pointer for `sm` and `md`).
+- Motion: `--bf-duration-layout` and `--ease-md` for the width, the labels, the headings and the badge.
 - The items' and the groups' tokens are on the [nav item](https://bitforge-ui.web.app/components/nav-item#theming) and [nav group](https://bitforge-ui.web.app/components/nav-group#theming) pages.
 
 ## Accessibility
 
-`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. `bf-sidebar-toggle` is a native button named by what it does ("Collapse sidebar"), with `aria-expanded` and `aria-controls` on the `nav`; your own toggle should do the same, and sit in the sidebar or right before it.
+`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible, and it animates only without `prefers-reduced-motion: reduce`: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. `bf-sidebar-toggle` is a native button named by what it does ("Collapse sidebar"), with `aria-expanded` and `aria-controls` on the `nav`; your own toggle should do the same, and sit in the sidebar or right before it.
 
 ### Keyboard
 
@@ -515,14 +532,25 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 - Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"` on every link.
 - Drive the sidebar, the small-screen menu and the shell's tab bar from one array of destinations.
 - Remember the collapsed state with `BfSidebarStateService` and `provideBfSidebarState()`.
+- Let header and footer content fade or close with `in-data-collapsed:` on `--bf-duration-layout`, so it moves with the sidebar.
 
 ### Don't
 
 - Don't put actions (Create, Log out) among the destinations; a sidebar is for places, so put an action in the header or footer as a button.
 - Don't use `bf-sidebar` inside the Capacitor shell; use `bf-tabs` with a `bf-tab-bar` there.
+- Don't remove header or footer content with `@if` on the collapsed state; it disappears before the width has moved.
 
 ## Migration notes
 
+### 0.5.0
+
+Collapsing and expanding now animate: the width moves over `--bf-duration-layout` on `ease-md`
+from `w-60` to a fixed rail (see Migration 4), and the content beside it (the `bf-app-frame`
+column) moves with it. Under `prefers-reduced-motion: reduce` it still switches at once. The first
+render never animates, so a collapsed state restored by `provideBfSidebarState()` does not slide
+on load. The host carries `data-collapsed` as before; header and footer content can follow on the
+same timing with `in-data-collapsed:` (new Motion section in the docs).
+
 ### 0.3.2
 
 New `BfSidebarStateService` (a `collapsed` signal) and `provideBfSidebarState()` in