@bitforgehq/ui 0.4.0 → 0.5.0-next.4

package/ai/components/nav-group.md

@@ -72,7 +72,7 @@ Put the group's links in its default slot and its name in `label`. Groups stack
 
 ## In a collapsed sidebar
 
-While the sidebar is collapsed to an icon rail the heading is hidden visually (`sr-only`), so only the icons show, and it still names the group for screen readers.
+While the sidebar is collapsed to an icon rail the heading's row closes and the text fades out (on `--bf-duration-layout`, at once under reduced motion), so only the icons show, and it still names the group for screen readers. The heading stays on one line and truncates, so its height never changes while the sidebar's width moves.
 
 ```ts
 import { Component } from '@angular/core';
@@ -84,7 +84,7 @@ import { Layers, LayoutList, PanelTop, SquareStack } from 'lucide';
 /**
  * Groups in a collapsed sidebar.
  *
- * The headings are hidden visually and still name their groups for screen readers; the items
+ * The headings close and fade out (at once under reduced motion) and still name their groups for screen readers; the items
  * show their icons only.
  */
 @Component({
@@ -146,7 +146,7 @@ The group itself is static; its links carry the hover, pressed and focus styles
 
 ## Accessibility
 
-The host has `role="group"` and `aria-labelledby` pointing at its heading, so a screen reader announces the group's name when focus enters it ("Workspace, group"). The heading is text, not a heading element, so it does not add to the page outline. Collapsed, the heading is `sr-only` and keeps naming the group.
+The host has `role="group"` and `aria-labelledby` pointing at its heading, so a screen reader announces the group's name when focus enters it ("Workspace, group"). The heading is text, not a heading element, so it does not add to the page outline. Collapsed, the heading is closed to no height and transparent, but stays in the accessibility tree and keeps naming the group.
 
 ## Inputs
 
@@ -172,6 +172,13 @@ The host has `role="group"` and `aria-labelledby` pointing at its heading, so a
 
 ## Migration notes
 
+### 0.5.0
+
+Collapsed, the heading's row closes and its text fades out on `--bf-duration-layout` instead of
+switching to `sr-only`; it stays in the accessibility tree and still names the group. The heading
+stays on one line and truncates (it wrapped before), so its height does not change while the
+width moves.
+
 ### 0.3.1
 
 New `bf-nav-group`: a titled group of sidebar links, `role="group"` named by its small heading,

package/ai/components/nav-item.md

@@ -109,7 +109,7 @@ The router sets `aria-current="page"` on the current page's link (`routerLinkAct
 
 ## Collapsed
 
-In a collapsed `bf-sidebar` the item shows only its icon in a square of its height step. The label stays in the DOM as screen-reader text, so the link's name does not change, and becomes the link's `title` (the tooltip on hover, kept up to date when the label changes); your own `title` comes back when the sidebar expands. The badge becomes a small dot on the icon's corner and is still announced. Give every item an icon, or it shows nothing while collapsed. For a styled tooltip that also shows on keyboard focus, add `bfTooltip` from `@bitforgehq/ui/overlay` with the label's text while collapsed (an empty text while expanded shows none) and `bfTooltipPlacement="end"` (see [bf-tooltip](https://bitforge-ui.web.app/components/tooltip)).
+In a collapsed `bf-sidebar` the item shows only its icon in a square of its height step: the row keeps its layout, its start padding centres a 20 px icon, and the label fades out while the sidebar narrows, so the icon never moves. The label stays in the DOM, so the link's name does not change, and becomes the link's `title` (the tooltip on hover, kept up to date when the label changes); your own `title` comes back when the sidebar expands. The badge pill shrinks away while a small dot grows on the icon's corner, on the same timing, and the count is still announced. Give every item an icon, or it shows nothing while collapsed. For a styled tooltip that also shows on keyboard focus, add `bfTooltip` from `@bitforgehq/ui/overlay` with the label's text while collapsed (an empty text while expanded shows none) and `bfTooltipPlacement="end"` (see [bf-tooltip](https://bitforge-ui.web.app/components/tooltip)).
 
 ## Sizes
 
@@ -161,11 +161,12 @@ Hover gives a `surface-muted` fill with the `text` colour and the pointer; press
 - Current page (`aria-current="page"`): `primary-soft` with `primary-strong`, hover `primary-soft-hover`, pressed `primary-soft-pressed`; under forced colours a `LinkText` outline.
 - Shape: `rounded-control`; label `font-bold`, `text-label-xs` / `text-label-sm` / `text-label` by size.
 - Badge: `primary` with `on-primary`, `text-micro`; collapsed, a `primary` dot (`CanvasText` under forced colours).
+- Motion: in a sidebar, the padding, the label and the badge move on `--bf-duration-layout` with `ease-md` (none under reduced motion); hover and press colours fade over 150 ms.
 - Focus: `ring` (4 px).
 
 ## Accessibility
 
-The item is the consumer's native `<a>`: exposed as a link, reached with Tab and followed with Enter, its name being its label (plus the badge announcement). The current page carries `aria-current="page"`, which screen readers announce; the fill is not the only cue, as an outline marks it under forced colours. The icon slot is decorative (a `bf-icon` is `aria-hidden` by default). Collapsed, the label is visually hidden but still the name, and `title` adds a pointer tooltip only; the badge dot is `aria-hidden`, its count announced through the screen-reader text. In Safari, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise).
+The item is the consumer's native `<a>`: exposed as a link, reached with Tab and followed with Enter, its name being its label (plus the badge announcement). The current page carries `aria-current="page"`, which screen readers announce; the fill is not the only cue, as an outline marks it under forced colours. The icon slot is decorative (a `bf-icon` is `aria-hidden` by default). Collapsed, the label is transparent and clipped but still the name, and `title` adds a pointer tooltip only; the badge dot is `aria-hidden`, its count announced through the screen-reader text. In Safari, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise).
 
 ### Keyboard
 
@@ -200,6 +201,14 @@ The item is the consumer's native `<a>`: exposed as a link, reached with Tab and
 
 ## Migration notes
 
+### 0.5.0
+
+In a collapsing sidebar the item no longer switches to a centred square: the row keeps its layout
+and its start padding moves so the icon ends centred in the rail without moving, while the label
+fades out (it stays the accessible name; it is no longer `sr-only`). The count pill shrinks away
+while the dot (new element, `[data-badge-dot]`) grows in on the same timing. Each item clips
+what does not fit the rail. No animation under reduced motion or in a top nav.
+
 ### 0.3.1
 
 New `a[bfNavItem]`: one destination of a `bf-sidebar` or `bf-top-nav` on the app's own

package/ai/components/number-input.md

@@ -165,13 +165,8 @@ The control works in Reactive Forms through Angular's Signal Forms interop (no `
 ```ts
 import { Component } from '@angular/core';
 import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
-import {
-  BfButtonComponent,
-  BfCheckboxComponent,
-  BfInputComponent,
-  BfSelectComponent,
-  type BfSelectOption,
-} from '@bitforgehq/ui';
+import { BfButtonComponent, BfCheckboxComponent, BfInputComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
 
 /**

package/ai/components/pagination.md

@@ -42,7 +42,9 @@ export class PaginationOverviewExampleComponent {
 Page navigation for a long list or table: Previous and Next buttons around the page numbers,
 the current one marked, the hidden runs shown as an ellipsis. `compact` shows "Page 3 of 12"
 between the arrows instead, for narrow screens. The page count comes from `pageCount`, or from
-`total` and `pageSize`; the consumer shows the rows of `page`.
+`total` and `pageSize`; the consumer shows the rows of `page`. A compact pagination with its own
+`positionLabel`, `previousLabel` and `nextLabel` steps through anything numbered, such as the
+versions of a model ("‹ v3 of 7 ›").
 
 Pagination splits a long list or table into pages and lets the user move between them: Previous and Next buttons around the page numbers, the current page marked, the first and the last page always in reach, and an ellipsis for each run of pages in between. `bf-pagination` holds only the page number. You bind `[(page)]` and show that page's rows, sliced on the client or fetched from the server. It works the same in both shells: in a desktop web app and in the Capacitor shell.
 
@@ -89,6 +91,41 @@ export class PaginationCompactExampleComponent {
 }
 ```
 
+## Stepping through versions
+
+A compact pagination also steps through anything else that is numbered, such as the versions of a model: "‹ v3 of 7 ›". `positionLabel` takes a `BfPaginationPositionLabel`, a function from the page and the count to the position text (`` (page, count) => `v${page} of ${count}` ``); unset, the text comes from `pageOf`. `previousLabel` and `nextLabel` name the arrows ("Previous version") where "Previous page" would be wrong, and `label` names the navigation. Use it instead of a [bf-segmented](https://bitforge-ui.web.app/components/segmented) control once there are more than four versions; the arrows are disabled at the ends, as on any pagination.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfPaginationComponent, type BfPaginationPositionLabel } from '@bitforgehq/ui';
+
+/**
+ * A compact pager that steps through the versions of a model, "‹ v3 of 7 ›".
+ *
+ * `positionLabel` writes the position text; `previousLabel` and `nextLabel` name the arrows.
+ */
+@Component({
+  selector: 'app-example-pagination-versions',
+  imports: [BfPaginationComponent],
+  template: `
+    <bf-pagination
+      compact
+      size="sm"
+      label="Versions"
+      previousLabel="Previous version"
+      nextLabel="Next version"
+      [positionLabel]="versionOf"
+      [pageCount]="7"
+      [(page)]="version"
+    />
+  `,
+})
+export class PaginationVersionsExampleComponent {
+  readonly version = signal(3);
+  protected readonly versionOf: BfPaginationPositionLabel = (page, count) => `v${page} of ${count}`;
+}
+```
+
 ## With a table
 
 Put the pagination under the table it pages, aligned to the inline end or centred, and show only the current page's rows: slice them in a `computed()` from `page`, or fetch the page from the server in a `httpResource()` keyed on it. When the user sorts or filters, set `page` back to 1. The [table](https://bitforge-ui.web.app/components/table) page has a paged example.
@@ -123,16 +160,19 @@ At the first and the last page the arrow is disabled with `aria-disabled="true"`
 
 ## Inputs
 
-| Name        | Type                                                        | Default     | Description                                                                                                                                               |
-| ----------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pageCount` | `number`                                                    | `0`         | The number of pages; wins over `total` and `pageSize` when above 0.                                                                                       |
-| `total`     | `number`                                                    | `0`         | The number of items, used with `pageSize` while `pageCount` is 0.                                                                                         |
-| `pageSize`  | `number`                                                    | `10`        | Items per page, used with `total` while `pageCount` is 0.                                                                                                 |
-| `siblings`  | `number`                                                    | `1`         | How many pages to show on each side of the current one.                                                                                                   |
-| `compact`   | `boolean`                                                   | `false`     | Shows "Page 3 of 12" between the arrows instead of the page buttons, for narrow screens.                                                                  |
-| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Button height step: sm 32, md 40, lg 48 px (44 px hit area under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
-| `label`     | `string`                                                    | `''`        | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `pagination` ("Pagination").                                                 |
-| `page`      | `number`                                                    | `1`         | The current page, 1-based; two-way bindable. The buttons set it; show the rows of this page. Two-way: `[(page)]`.                                         |
+| Name            | Type                                                        | Default     | Description                                                                                                                                                            |
+| --------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageCount`     | `number`                                                    | `0`         | The number of pages; wins over `total` and `pageSize` when above 0.                                                                                                    |
+| `total`         | `number`                                                    | `0`         | The number of items, used with `pageSize` while `pageCount` is 0.                                                                                                      |
+| `pageSize`      | `number`                                                    | `10`        | Items per page, used with `total` while `pageCount` is 0.                                                                                                              |
+| `siblings`      | `number`                                                    | `1`         | How many pages to show on each side of the current one.                                                                                                                |
+| `compact`       | `boolean`                                                   | `false`     | Shows "Page 3 of 12" between the arrows instead of the page buttons, for narrow screens.                                                                               |
+| `positionLabel` | `BfPaginationPositionLabel \| undefined`                    | `undefined` | Writes the compact position text from the page and the count, such as "v3 of 7"; unset uses `provideBfLabels()`'s `pageOf` ("Page 3 of 12"). Only used with `compact`. |
+| `previousLabel` | `string`                                                    | `''`        | Accessible name of the previous button, such as "Previous version"; empty falls back to `provideBfLabels()`'s `previousPage` ("Previous page").                        |
+| `nextLabel`     | `string`                                                    | `''`        | Accessible name of the next button, such as "Next version"; empty falls back to `provideBfLabels()`'s `nextPage` ("Next page").                                        |
+| `size`          | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Button height step: sm 32, md 40, lg 48 px (44 px hit area under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).              |
+| `label`         | `string`                                                    | `''`        | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `pagination` ("Pagination").                                                              |
+| `page`          | `number`                                                    | `1`         | The current page, 1-based; two-way bindable. The buttons set it; show the rows of this page. Two-way: `[(page)]`.                                                      |
 
 ## Methods
 
@@ -159,6 +199,14 @@ Goes to a page: sets `page` when it is another page within 1…count; else does
 
 ## Migration notes
 
+### 0.5.0
+
+New `positionLabel` input (new type `BfPaginationPositionLabel`, `(page, count) => string`) that
+writes a compact pagination's position text, such as "v3 of 7"; unset it is the `pageOf` label as
+before. New `previousLabel` and `nextLabel` inputs name the arrows ("Previous version"); empty
+they fall back to `previousPage` and `nextPage`. Together they make a compact pager for stepping
+through versions.
+
 ### 0.3.1
 
 New `bf-pagination` in `@bitforgehq/ui`, page navigation for both shells: a `nav` (named by

package/ai/components/popover.md

@@ -207,6 +207,9 @@ in the Capacitor shell a `bf-sheet` suits phone screens better.
   `Shift+Tab` before the first control closes it onto the trigger.
 - `Escape` goes to the popover first: inside a dialog, the first `Escape` closes the popover and
   the next one the dialog.
+- Motion: the panel grows out of the trigger as it opens (a fade, a slight scale and a 4 px slide,
+  180 ms) and shrinks back as it closes (130 ms). Focus and `aria-expanded` change at once; the
+  closing panel is inert while it fades. Under `prefers-reduced-motion` it only fades.
 
 ### Keyboard
 
@@ -238,6 +241,16 @@ in the Capacitor shell a `bf-sheet` suits phone screens better.
 
 ## Migration notes
 
+### 0.5.0
+
+The panel animates open and closed. It grows out of the trigger (a fade, a scale from 96 % and a
+4 px slide away from the trigger, 180 ms, ease-out; transform origin on the trigger's corner,
+following a flip above or below) and shrinks back on close (130 ms). Focus, `aria-expanded` and
+`bfPopoverClosed` still change at once; the closing panel stays in the overlay container, inert
+and click-through, until its exit has played, and opening again during the exit replaces it. Under
+`prefers-reduced-motion` it only fades. Where the Web Animations API is missing or stubbed
+(jsdom), the panel is still removed at once.
+
 ### 0.3.1
 
 New `[bfPopoverTriggerFor]` (`BfPopoverTriggerDirective`, exported as `bfPopoverTrigger`) and the

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