@bitforgehq/ui 0.4.0 → 0.5.0-next.4

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

package/ai/components/tab-group.md

@@ -148,6 +148,8 @@ export class TabGroupLazyExampleComponent {
 
 `[(selected)]` holds the shown panel's `value`; `(changed)` emits the new value after a user change, never for a write of `selected`. While `selected` matches no panel (unset, or a value that went away), the first enabled panel shows; `selected` itself keeps its value until the user picks a tab.
 
+The underline slides to the newly selected tab, 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`. The panel a user switches to fades in over 200 ms (`animate-panel-in`); the first panel shown, and every panel under reduced motion, appears at once.
+
 ## Sizes and width
 
 `size` sets the tabs' height: `sm` 32 px, `md` 40 px, `lg` 48 px. Unset, it follows `provideBfDefaults()`'s `controlSize`, `md` by default. `fitted` stretches the tabs to share the group's width (two or three tabs on a phone). When the tabs do not fit, the row scrolls sideways; focusing a tab with the keyboard scrolls it into view.
@@ -159,7 +161,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 ## Theming
 
 - Tabs: `text-muted` at rest, hover `surface-muted` with `text`, pressed `surface-pressed`; top corners `rounded-tile`.
-- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab).
+- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab). It slides over `--bf-duration-layout` with the `ease-md` curve.
 - Disabled tab: `text-disabled` (never opacity).
 - The row: a 1 px `border` line under the tabs, across the group's width.
 - Badge: `primary` with `on-primary` text, `rounded-control`, `text-micro`.
@@ -168,7 +170,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 
 ## Accessibility
 
-The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
+The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. The sliding underline is one decorative `aria-hidden` element of the row. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
 
 ### Keyboard
 
@@ -213,6 +215,20 @@ The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabG
 
 ## Migration notes
 
+### 0.5.0
+
+The selected tab's underline is now one indicator element of the row that slides to the newly
+selected tab, 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`. It is measured
+from the selected tab's inline-start offset, so it mirrors under `dir="rtl"`, and is re-measured
+on resize and when labels, badges, size or `fitted` change. Until it has been measured (jsdom,
+server render, a hidden group) the tab keeps drawing its own underline, so unit tests and the
+first paint are unchanged. The indicator is `aria-hidden`; roles, keyboard and focus are
+unchanged.
+
+The panel a user switches to fades in (200 ms of opacity, new `--animate-panel-in`, behind
+`motion-safe:`); the panel shown on the first render never does.
+
 ### 0.3.1
 
 New `bf-tab-group`: in-page tabs over the content they switch, in both shells. A `tablist` of

package/ai/components/table.md

@@ -489,11 +489,12 @@ export class TablePagedExampleComponent {
 
 `stack` lets the table itself fit a narrow space. With `stack="narrow"` it stacks while the table is narrower than 36rem (576 px at the default root size, Tailwind's `xl` container size): a container query on the table's own width, so a table in a narrow column or a side panel stacks even on a wide screen. The host is then a size container (`container-type: inline-size`), so give the table its width from its parent (a block or `w-full` / `flex-1`), not from its columns. With `stack="coarse"` it stacks under a coarse pointer at any width (phones, tablets, the Capacitor shell). The default `never` keeps the table as it is.
 
-Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`.
+Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. The Sort by select is a native `<select>` unless the app adds `provideBfSelect()` from `@bitforgehq/ui/overlay` to its providers: then it is the styled [bf-select](https://bitforge-ui.web.app/components/select) (still native under touch), through the `BF_TABLE_SORT_SELECT` token, so `@bitforgehq/ui` itself never loads the CDK. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`, in either form.
 
 ```ts
 import { Component, computed, signal } from '@angular/core';
 import {
+  BF_TABLE_SORT_SELECT,
   BfBadgeComponent,
   BfSegmentedComponent,
   BfTableCellDirective,
@@ -502,6 +503,7 @@ import {
   type BfTableColumn,
   type BfTableSort,
 } from '@bitforgehq/ui';
+import { BfSelectComponent } from '@bitforgehq/ui/overlay';
 
 interface Task {
   id: string;
@@ -526,10 +528,16 @@ type Width = 'phone' | 'full';
  * than 36rem: the selection checkbox and the first cell head the tile, and a bar above the tiles
  * holds Select all and a Sort by select, whose first option, Not sorted, shows while `sort` is
  * null and clears it. Switch the box between phone width and full width.
+ *
+ * The Sort by select is the styled `bf-select`. In an app, add `provideBfSelect()` from
+ * `@bitforgehq/ui/overlay` to `app.config.ts` once; this page provides `BF_TABLE_SORT_SELECT`
+ * on the example instead, so the docs site loads the select only with this example.
  */
 @Component({
   selector: 'app-example-table-stacked',
   imports: [BfTableComponent, BfTableCellDirective, BfBadgeComponent, BfSegmentedComponent],
+  // In an app: provideBfSelect() in app.config.ts (see the comment above).
+  providers: [{ provide: BF_TABLE_SORT_SELECT, useValue: BfSelectComponent }],
   template: `
     <!-- A stacking table is a size container: its width comes from its parent, never its columns. -->
     <div class="flex w-152 max-w-full flex-col gap-3">
@@ -684,7 +692,7 @@ A table that can stack (`stack` other than `never`) sets explicit `table`, `rowg
 | <kbd>Space</kbd>                                 | Toggles the focused checkbox, or sorts by the focused header                                                                                                                |
 | <kbd>Enter</kbd>                                 | Sorts by the focused header                                                                                                                                                 |
 
-A stacked table's Sort by select is a native select with its own keys.
+A stacked table's Sort by select has its own keys: the native select's, or with `provideBfSelect()` those of [bf-select](https://bitforge-ui.web.app/components/select#keyboard).
 
 Text fields, selects and composite widgets (radios, comboboxes, sliders) in a cell keep their own arrow keys.
 
@@ -751,6 +759,13 @@ Selects or clears one row.
 
 ## Migration notes
 
+### 0.5.0
+
+New `BF_TABLE_SORT_SELECT` injection token: the component a stacked table renders as its "Sort
+by" select (`null`, the default, keeps the native one). `provideBfSelect()` from
+`@bitforgehq/ui/overlay` sets it to the styled `bf-select`, so the core entry still never imports
+the CDK. `BfTableHarness.getSortSelect()` returns a working `BfSelectHarness` either way.
+
 ### 0.4.0
 
 New: toggle cells for a settings matrix (rows of alert kinds, columns of channels, a `bf-toggle`

package/ai/components/theme-menu-button.md

@@ -127,6 +127,7 @@ The button consumes `bf-menu-button`'s tokens (`bf-button`'s, or `bf-icon-button
 - The three items are `role="menuitemradio"` with `aria-checked`, so a screen reader announces the current choice. The dot is drawn in CSS and adds nothing to the name.
 - Choosing an item closes the menu and returns focus to the button.
 - Hit area: at least 32 px, 44 px under a coarse pointer, as `bf-menu-button`.
+- Motion: the menu fades and grows out of the button as it opens, and closes at once. Under `prefers-reduced-motion` it only fades in.
 
 ### Keyboard
 

package/ai/components/time-input.md

@@ -138,6 +138,8 @@ The field shows the `primary` border and focus ring while any part has focus, th
 
 The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`); each part is a `role="spinbutton"` named from the `timeInputHour`, `timeInputMinute`, `timeInputSecond` and `timeInputDayPeriod` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext` (the AM or PM name), and the field's `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled`. The clock button is named by `timeInputOpenList`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The list is a `role="listbox"` named by the same label, its times `role="option"` with `aria-selected` and `aria-disabled`; focus stays on the list and `aria-activedescendant` names the active time.
 
+Motion: 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). Focus returns at once and the closing list is inert. Under `prefers-reduced-motion` it only fades.
+
 ### Keyboard
 
 | Key                                              | Where | Action                                                   |

package/ai/components/toolbar.md

@@ -12,11 +12,10 @@ import {
   BfButtonComponent,
   BfInputComponent,
   BfSegmentedComponent,
-  BfSelectComponent,
   BfToolbarComponent,
   type BfSegmentOption,
-  type BfSelectOption,
 } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 type ProjectStatus = 'active' | 'paused' | 'done';
 type StatusFilter = ProjectStatus | 'all';
@@ -125,7 +124,7 @@ export class ToolbarOverviewExampleComponent {
 Row of search, filters, a view switch and trailing actions above a list or table. Every
 control projected into it is `sm` unless it sets `size` itself.
 
-A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select`, `bf-chip-group`, `bf-segmented` and `bf-button`s.
+A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select` (from `@bitforgehq/ui/overlay`), `bf-chip-group`, `bf-segmented` and `bf-button`s.
 
 ## When to use
 
@@ -191,13 +190,8 @@ The row is a wrapping flex row with an 8 px gap between items and between rows.
 
 ```ts
 import { Component } from '@angular/core';
-import {
-  BfButtonComponent,
-  BfInputComponent,
-  BfSelectComponent,
-  BfToolbarComponent,
-  type BfSelectOption,
-} from '@bitforgehq/ui';
+import { BfButtonComponent, BfInputComponent, BfToolbarComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * A toolbar that wraps.
@@ -238,13 +232,8 @@ At phone width (in a desktop web app's narrow window or a narrow column) the sea
 
 ```ts
 import { Component, signal } from '@angular/core';
-import {
-  BfButtonComponent,
-  BfInputComponent,
-  BfSelectComponent,
-  BfToolbarComponent,
-  type BfSelectOption,
-} from '@bitforgehq/ui';
+import { BfButtonComponent, BfInputComponent, BfToolbarComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * A toolbar at phone width.
@@ -317,7 +306,7 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 ## Slots
 
-- `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
+- `default`: The search field and the filters (bf-input, bf-chip-group, bf-select from /overlay), in order.
 - `view`: A view switch after the filters, such as a bf-segmented of list and grid.
 - `actions`: The trailing actions, kept together at the inline end of the row, beside the status.
 

package/ai/reference/bf-chat-composer-harness.md

@@ -0,0 +1,64 @@
+# BfChatComposerHarness
+
+Test harness for the chat composer: types, sends, stops and reads its state
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-chat-composer` (`@bitforgehq/ui/overlay`). Its `label` filter matches the text
+field's name: the visible label, else its `aria-label` ("Message" by default).
+
+```ts
+import { BfChatComposerHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfChatComposerHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The text field's name: the visible label, else its `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The text in the field.
+
+### `setValue(text: string): Promise<void>`
+
+Replaces the text as the user would type it (`changed` and the value update).
+
+| Parameter | Type     | Description   |
+| --------- | -------- | ------------- |
+| `text`    | `string` | The new text. |
+
+### `send(): Promise<void>`
+
+Sends the text with the send button, as a click does. Does nothing while it cannot send.
+
+### `pressEnter(): Promise<void>`
+
+Sends the text with `Enter` in the field, as the keyboard does.
+
+### `stop(): Promise<void>`
+
+Stops the running reply with the stop button. Does nothing unless a reply is running.
+
+### `isRunning(): Promise<boolean>`
+
+Whether a reply is running, so the button stops instead of sending.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the composer is disabled (its text field is).
+
+### `canAct(): Promise<boolean>`
+
+Whether the button can send (or stop) now: not disabled and, to send, with text.
+
+### `getButtonLabel(): Promise<string>`
+
+The button's name, "Send" or "Stop" by default.

package/ai/reference/bf-chat-message-role.md

@@ -0,0 +1,27 @@
+# BfChatMessageRole
+
+Who wrote a chat message, the user or the assistant
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+Who wrote a `bf-chat-message`: `user` (a tinted bubble at the inline end) or `assistant` (full
+width, no bubble).
+
+```ts
+import { type BfChatMessageRole } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChatMessageRole = 'user' | 'assistant'
+```
+
+## Values
+
+- `user`
+- `assistant`
+
+## Used by
+
+- [bf-chat-message](../components/chat-message.md)

package/ai/reference/bf-chat-message-status.md

@@ -0,0 +1,28 @@
+# BfChatMessageStatus
+
+How a chat message ended: done, stopped by the user, or failed
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+How a `bf-chat-message` ended: `done` (the default, no status line), `stopped` (the user
+stopped the reply) or `failed` (it did not arrive or was not sent).
+
+```ts
+import { type BfChatMessageStatus } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChatMessageStatus = 'done' | 'stopped' | 'failed'
+```
+
+## Values
+
+- `done`
+- `stopped`
+- `failed`
+
+## Used by
+
+- [bf-chat-message](../components/chat-message.md)

package/ai/reference/bf-fade-in-directive.md

@@ -0,0 +1,18 @@
+# BfFadeInDirective
+
+Fades an image in once it has loaded instead of popping in
+
+Directive from `@bitforgehq/ui` · since 0.5.0
+
+Fades an image in when it has loaded instead of letting it pop in line by line: put
+`bfFadeIn` on the `<img>`. The image stays transparent until its `load` (or `error`) event,
+then fades in over 260 ms (`duration-slow`), at once under `prefers-reduced-motion: reduce`. An
+image that is already loaded when it renders (from the cache) shows straight away. Reserve its
+space (`width`/`height` attributes or an aspect ratio) so the layout does not move when it
+arrives; for a placeholder while it loads, put a `bf-skeleton` behind it.
+
+```ts
+import { BfFadeInDirective } from '@bitforgehq/ui';
+```
+
+Selector: `img[bfFadeIn]`

package/ai/reference/bf-file-input-harness.md

@@ -0,0 +1,67 @@
+# BfFileInputHarness
+
+Test harness for the file input: drops files and reads the list and rejections
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-file-input`, in both looks. `addFiles()` drops files on the field, so they go
+through the same `accept`, `maxSize` and `maxFiles` rules as a real drop; read the outcome with
+`getFileNames()` and `getRejected()`. It works by file name, so a test never needs the rows.
+
+```ts
+import { BfFileInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfFileInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else `ariaLabel`.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the field (an explicit message, or the first form error once touched).
+
+### `getVariant(): Promise<'field' | 'dropzone'>`
+
+The look of the field.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the field is read-only: it has no pick target.
+
+### `addFiles(files: File[]): Promise<void>`
+
+Drops files on the field, as a user would. On a disabled or read-only field it does nothing,
+like the UI.
+
+| Parameter | Type     | Description        |
+| --------- | -------- | ------------------ |
+| `files`   | `File[]` | The files to drop. |
+
+### `getFileNames(): Promise<string[]>`
+
+The names of the chosen files, in order (rejected files are not included).
+
+### `getRejected(): Promise<{ name: string; message: string }[]>`
+
+The files the last pick or drop refused, each with its reason, until they are dismissed.
+
+### `removeFile(name: string): Promise<void>`
+
+Removes the chosen file with this name, as the row's remove button does. Throws when no
+chosen file has that name or the field cannot be edited.
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `name`    | `string` | The file's name. |

package/ai/reference/bf-file-input-variant.md

@@ -0,0 +1,27 @@
+# BfFileInputVariant
+
+The two looks of a file picker, a compact field or a drop zone
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+The look of a `bf-file-input`: a compact field with a pick button (`field`), or a drop zone
+(`dropzone`). Both have the same API and behaviour.
+
+```ts
+import { type BfFileInputVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfFileInputVariant = 'field' | 'dropzone'
+```
+
+## Values
+
+- `field`
+- `dropzone`
+
+## Used by
+
+- [bf-file-input](../components/file-input.md)