@bitforgehq/ui 0.4.0 → 0.5.0-next.3

package/ai/components/media-card.md

@@ -0,0 +1,478 @@
+# bf-media-card
+
+Card with an image that loads, fades in or fails, plus a body and actions
+
+`BfMediaCardComponent` from `@bitforgehq/ui` · Data display · since 0.5.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, type WritableSignal, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfMediaCardComponent } from '@bitforgehq/ui';
+
+/** One generated picture as the app tracks it. */
+interface Generation {
+  readonly src: string;
+  readonly generating: boolean;
+  readonly failed: boolean;
+}
+
+/** How long the simulated generation takes (a real one takes 30 to 90 seconds). */
+const GENERATION_MS = 4000;
+
+/**
+ * The bf-media-card overview.
+ *
+ * Live demo of `bf-media-card` with pictures that take a while to exist: the first is being drawn
+ * (a timer stands in for the image service) and fades in when it arrives; the second fails, and
+ * its Retry button starts it again; the third is already there.
+ */
+@Component({
+  selector: 'app-example-media-card-overview',
+  imports: [BfButtonComponent, BfMediaCardComponent],
+  template: `
+    <div class="grid gap-4 @md:grid-cols-3">
+      <bf-media-card
+        alt="A neon city skyline at dusk"
+        loadingLabel="Drawing…"
+        [src]="starfall().src"
+        [loading]="starfall().generating"
+      >
+        <h2 class="text-heading">Starfall</h2>
+        <p class="text-body text-text-secondary">A city that falls one floor a night.</p>
+        <bf-button
+          bfSlot="footer"
+          class="relative z-1 self-start"
+          variant="tonal"
+          size="sm"
+          [disabled]="starfall().generating"
+          (clicked)="generate(starfall, 'media/skyline.svg', false)"
+        >
+          Draw again
+        </bf-button>
+      </bf-media-card>
+
+      <bf-media-card
+        alt="A harbour under a low sun"
+        loadingLabel="Drawing…"
+        failedLabel="The picture could not be drawn"
+        [src]="tidewalk().src"
+        [loading]="tidewalk().generating"
+        [failed]="tidewalk().failed"
+      >
+        <h2 class="text-heading">Tidewalk</h2>
+        <p class="text-body text-text-secondary">A harbour town that floods at every tide.</p>
+        <bf-button
+          bfSlot="failed-action"
+          variant="tonal"
+          size="sm"
+          (clicked)="generate(tidewalk, 'media/harbour.svg', false)"
+        >
+          Retry
+        </bf-button>
+      </bf-media-card>
+
+      <bf-media-card src="media/forest.svg" alt="A pine forest under a pale sun">
+        <h2 class="text-heading">Rootbound</h2>
+        <p class="text-body text-text-secondary">A forest that rearranges itself at night.</p>
+      </bf-media-card>
+    </div>
+  `,
+})
+export class MediaCardOverviewExampleComponent {
+  protected readonly starfall = signal<Generation>({ src: '', generating: true, failed: false });
+  protected readonly tidewalk = signal<Generation>({ src: '', generating: true, failed: false });
+  private readonly timers = new Set<ReturnType<typeof setTimeout>>();
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.timers.forEach((timer) => clearTimeout(timer)));
+    this.generate(this.starfall, 'media/skyline.svg', false);
+    // The first attempt at Tidewalk fails, so Retry shows.
+    this.generate(this.tidewalk, 'media/harbour.svg', true);
+  }
+
+  /** Starts a (simulated) generation that ends with the picture, or with a failure. */
+  protected generate(target: WritableSignal<Generation>, src: string, fails: boolean): void {
+    target.set({ src: '', generating: true, failed: false });
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      target.set(
+        fails
+          ? { src: '', generating: false, failed: true }
+          : { src, generating: false, failed: false },
+      );
+    }, GENERATION_MS);
+    this.timers.add(timer);
+  }
+}
+```
+
+## Overview
+
+Card for a picture and its story: a game pitch, a generated image, a product. The top is an
+image area at a fixed aspect ratio that shows a shimmering skeleton while the picture loads
+(also while it does not exist yet: set `loading`), fades the picture in when it arrives, and
+shows a message with a Retry slot when it fails. Below it sit a body and a footer. Make the card
+clickable with a `bfAction` link or button in its title, as on `bf-card`, and selectable with
+`selectable` and `[(selected)]`.
+
+A card led by a picture: a game pitch, a generated image, a product. The top is an image area at a fixed aspect ratio that the card fills itself from `src` and `alt`, so it owns the whole life of the picture: a shimmering skeleton while it loads (also while it does not exist yet), a fade when it arrives, and a message with a Retry slot when it fails. Below the image sit a body and a footer, as on `bf-card`.
+
+## When to use
+
+Use `bf-media-card` when a picture is the main content of a card, and especially when it is slow to arrive (an image generated in 30 to 90 seconds) or can fail. Use [bf-card](https://bitforge-ui.web.app/components/card) instead for a card without a picture or with a small one inside its text, [bf-image-input](https://bitforge-ui.web.app/components/image-input) to let the user pick an image, and [bf-skeleton](https://bitforge-ui.web.app/components/skeleton) for a placeholder of other content. Open the full-size picture with [bf-image-viewer](https://bitforge-ui.web.app/components/image-viewer).
+
+## Basic usage
+
+Give the card the picture's `src` and `alt` (empty `alt` marks it decorative), and put a title and text in its body. The image area keeps its ratio (`16/9` by default) whether the picture is there or not, so a grid of cards never jumps.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent, BfButtonComponent, BfMediaCardComponent } from '@bitforgehq/ui';
+
+/**
+ * A media card.
+ *
+ * The card shows the picture from `src` in a 16:9 area, with a title, a line of text and a footer
+ * of a badge and a button under it.
+ */
+@Component({
+  selector: 'app-example-media-card-basic',
+  imports: [BfBadgeComponent, BfButtonComponent, BfMediaCardComponent],
+  template: `
+    <bf-media-card class="max-w-sm" src="media/skyline.svg" alt="A neon city skyline at dusk">
+      <h3 class="text-heading">Starfall</h3>
+      <p class="text-body text-text-secondary">
+        A roguelike set in a city that falls one floor a night.
+      </p>
+      <div bfSlot="footer" class="flex items-center justify-between gap-2">
+        <bf-badge>Roguelike</bf-badge>
+        <bf-button variant="tonal" size="sm">Read the pitch</bf-button>
+      </div>
+    </bf-media-card>
+  `,
+})
+export class MediaCardBasicExampleComponent {}
+```
+
+## Loading, arriving and failing
+
+While the picture loads, the area shows a `bf-skeleton` shimmer. A picture that does not exist yet (it is still being made) has no `src`: set `loading` and the skeleton shows until `src` arrives. `loadingLabel` puts a caption over the skeleton ("Drawing…"); without it, screen readers hear the `loading` label ("Loading") and the area is `aria-busy`.
+
+When the picture arrives it fades in over 260 ms (`bfFadeIn`) while the skeleton fades out under it, instead of popping in line by line; under reduced motion it appears at once.
+
+A picture that fails to load (its `error` event), or one the app could not make (`failed`), shows a message, `failedLabel` or the `imageLoadFailed` label ("The image could not be loaded"), and the `bfSlot="failed-action"` content under it, such as a Retry button. A new `src` starts over: skeleton, fade and a forgotten load error. To retry the same URL, change it (add a query such as `?retry=2`). `failed` is the app's to clear. `loaded` and `errored` report the picture's events.
+
+```ts
+import { Component, DestroyRef, type WritableSignal, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfMediaCardComponent } from '@bitforgehq/ui';
+
+/** One generated picture as the app tracks it. */
+interface Generation {
+  readonly src: string;
+  readonly generating: boolean;
+  readonly failed: boolean;
+}
+
+/** How long the simulated generation takes (a real one takes 30 to 90 seconds). */
+const GENERATION_MS = 4000;
+
+/**
+ * The bf-media-card overview.
+ *
+ * Live demo of `bf-media-card` with pictures that take a while to exist: the first is being drawn
+ * (a timer stands in for the image service) and fades in when it arrives; the second fails, and
+ * its Retry button starts it again; the third is already there.
+ */
+@Component({
+  selector: 'app-example-media-card-overview',
+  imports: [BfButtonComponent, BfMediaCardComponent],
+  template: `
+    <div class="grid gap-4 @md:grid-cols-3">
+      <bf-media-card
+        alt="A neon city skyline at dusk"
+        loadingLabel="Drawing…"
+        [src]="starfall().src"
+        [loading]="starfall().generating"
+      >
+        <h2 class="text-heading">Starfall</h2>
+        <p class="text-body text-text-secondary">A city that falls one floor a night.</p>
+        <bf-button
+          bfSlot="footer"
+          class="relative z-1 self-start"
+          variant="tonal"
+          size="sm"
+          [disabled]="starfall().generating"
+          (clicked)="generate(starfall, 'media/skyline.svg', false)"
+        >
+          Draw again
+        </bf-button>
+      </bf-media-card>
+
+      <bf-media-card
+        alt="A harbour under a low sun"
+        loadingLabel="Drawing…"
+        failedLabel="The picture could not be drawn"
+        [src]="tidewalk().src"
+        [loading]="tidewalk().generating"
+        [failed]="tidewalk().failed"
+      >
+        <h2 class="text-heading">Tidewalk</h2>
+        <p class="text-body text-text-secondary">A harbour town that floods at every tide.</p>
+        <bf-button
+          bfSlot="failed-action"
+          variant="tonal"
+          size="sm"
+          (clicked)="generate(tidewalk, 'media/harbour.svg', false)"
+        >
+          Retry
+        </bf-button>
+      </bf-media-card>
+
+      <bf-media-card src="media/forest.svg" alt="A pine forest under a pale sun">
+        <h2 class="text-heading">Rootbound</h2>
+        <p class="text-body text-text-secondary">A forest that rearranges itself at night.</p>
+      </bf-media-card>
+    </div>
+  `,
+})
+export class MediaCardOverviewExampleComponent {
+  protected readonly starfall = signal<Generation>({ src: '', generating: true, failed: false });
+  protected readonly tidewalk = signal<Generation>({ src: '', generating: true, failed: false });
+  private readonly timers = new Set<ReturnType<typeof setTimeout>>();
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.timers.forEach((timer) => clearTimeout(timer)));
+    this.generate(this.starfall, 'media/skyline.svg', false);
+    // The first attempt at Tidewalk fails, so Retry shows.
+    this.generate(this.tidewalk, 'media/harbour.svg', true);
+  }
+
+  /** Starts a (simulated) generation that ends with the picture, or with a failure. */
+  protected generate(target: WritableSignal<Generation>, src: string, fails: boolean): void {
+    target.set({ src: '', generating: true, failed: false });
+    const timer = setTimeout(() => {
+      this.timers.delete(timer);
+      target.set(
+        fails
+          ? { src: '', generating: false, failed: true }
+          : { src, generating: false, failed: false },
+      );
+    }, GENERATION_MS);
+    this.timers.add(timer);
+  }
+}
+```
+
+## Aspect ratios
+
+`aspect` is `16/9` (default), `4/3`, `1/1` or `3/4` (portrait). The picture covers the area and is cropped to it (`object-cover`).
+
+```ts
+import { Component } from '@angular/core';
+import { type BfMediaCardAspect, BfMediaCardComponent } from '@bitforgehq/ui';
+
+/**
+ * Aspect ratios.
+ *
+ * `aspect` sets the ratio of the image area: 16:9 (default), 4:3, square and portrait 3:4. The
+ * picture covers the area and is cropped to it.
+ */
+@Component({
+  selector: 'app-example-media-card-aspects',
+  imports: [BfMediaCardComponent],
+  template: `
+    <div class="grid grid-cols-2 items-start gap-4 @lg:grid-cols-4">
+      @for (aspect of aspects; track aspect) {
+        <bf-media-card src="media/desert.svg" alt="Dunes under an orange sun" [aspect]="aspect">
+          <h3 class="text-label">{{ aspect }}</h3>
+        </bf-media-card>
+      }
+    </div>
+  `,
+})
+export class MediaCardAspectsExampleComponent {
+  protected readonly aspects: readonly BfMediaCardAspect[] = ['16/9', '4/3', '1/1', '3/4'];
+}
+```
+
+## Clickable and selectable cards
+
+A card that opens something follows the `bf-card` pattern: put a `bfAction` link (navigation) or button (an action) in its title. The whole card is then its click target, with the pointer, the hover lift and the focus ring; other controls in it, such as footer buttons, take `class="relative z-1"`.
+
+`selectable` adds a select button, a toggle (`aria-pressed`) bound with `[(selected)]`; `changed` emits each change the user makes. Without a `bfAction`, the whole card is that button, and a check disc in the image's top end corner shows the state. With a `bfAction`, the card opens on a click and the round check button in the corner (32 px, 44 px under a coarse pointer) selects, as in a photo library. A selected card has a 2 px primary ring outside its edge and a filled check. The select button is named "Select" followed by `label`, or by the body's text when `label` is empty: set `label` to the card's title.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfActionDirective, BfMediaCardComponent } from '@bitforgehq/ui';
+
+/** One concept the team can pick. */
+interface Concept {
+  readonly id: string;
+  readonly title: string;
+  readonly src: string;
+  readonly alt: string;
+}
+
+/**
+ * Selectable cards.
+ *
+ * Pick the concepts to keep: each card is one select button bound with `[(selected)]`, with a
+ * check in its corner. The last card also opens its page through a `bfAction` link, so its check
+ * becomes a separate round button.
+ */
+@Component({
+  selector: 'app-example-media-card-selectable',
+  imports: [RouterLink, BfActionDirective, BfMediaCardComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="grid gap-4 @md:grid-cols-3">
+        @for (concept of concepts; track concept.id) {
+          <bf-media-card
+            selectable
+            aspect="4/3"
+            [src]="concept.src"
+            [alt]="concept.alt"
+            [label]="concept.title"
+            [selected]="picked().has(concept.id)"
+            (changed)="toggle(concept.id, $event)"
+          >
+            <h3 class="text-heading">{{ concept.title }}</h3>
+          </bf-media-card>
+        }
+        <bf-media-card
+          selectable
+          aspect="4/3"
+          src="media/glacier.svg"
+          alt="A glacier under a small sun"
+          label="Coldlight"
+          [selected]="picked().has('coldlight')"
+          (changed)="toggle('coldlight', $event)"
+        >
+          <h3 class="text-heading">
+            <a bfAction routerLink="/components/media-card">Coldlight</a>
+          </h3>
+        </bf-media-card>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class MediaCardSelectableExampleComponent {
+  protected readonly concepts: readonly Concept[] = [
+    { id: 'starfall', title: 'Starfall', src: 'media/skyline.svg', alt: 'A neon city skyline' },
+    { id: 'rootbound', title: 'Rootbound', src: 'media/forest.svg', alt: 'A pine forest' },
+    { id: 'tidewalk', title: 'Tidewalk', src: 'media/harbour.svg', alt: 'A harbour at sunset' },
+  ];
+  protected readonly picked = signal<ReadonlySet<string>>(new Set(['rootbound']));
+  protected readonly status = computed(() => {
+    const count = this.picked().size;
+    return count === 1 ? '1 concept picked.' : `${count} concepts picked.`;
+  });
+
+  protected toggle(id: string, selected: boolean): void {
+    this.picked.update((ids) => {
+      const next = new Set(ids);
+      if (selected) {
+        next.add(id);
+      } else {
+        next.delete(id);
+      }
+      return next;
+    });
+  }
+}
+```
+
+## Desktop
+
+A card with a `bfAction` or a stretched select button shows the pointer and lifts to `shadow-floating` while the pointer is over it, and drops back to `shadow-raised` while pressed; both fade on the fast timing (150 ms). The ring around the whole card shows while its action or select button has keyboard focus, not after a click. The corner check button draws its own focus ring. The selection ring fades in and out on the same timing. Text under a stretched action cannot be selected with the mouse; give text that must stay copyable `class="relative z-1"`.
+
+## Theming
+
+- Card: `bg-surface`, `text-text`, `rounded-card`, `shadow-raised` (`shadow-floating` on hover); body padding `p-card` (`--spacing-card`).
+- Image area: `bg-surface-sunken`, the top corners `rounded-card`; the skeleton is a `bf-skeleton` rect; captions and messages `text-caption text-text-muted`.
+- Selection: the ring is a 2 px `primary` outline 2 px outside the card; the check disc is `surface` with a `border-strong` edge, `primary` with an `on-primary` check while selected.
+- Focus: `ring-4 ring-ring` around the card (stretched action) or the corner button.
+- Motion: `duration-fast` (150 ms) for hover, press and selection, `duration-slow` (260 ms) for the picture's fade and the skeleton's fade-out, on `ease-md`; none under reduced motion.
+
+## Accessibility
+
+The card is a plain `<div>`; the picture is an `<img>` with `alt`. While loading, the image area is `aria-busy="true"` and its caption (or the visually hidden "Loading") is plain text, not a live region, so a grid of loading cards is not announced card by card; the skeleton is hidden from assistive technology. The failure message is plain text too, followed by the `failed-action` content.
+
+A clickable card follows the stretched-link pattern of `bf-card`: the only interactive element is the `bfAction` link or button in its title. The select button is a native `<button>` with `aria-pressed`, named by `aria-labelledby` ("Select" and `label`, or the body's text); its check is decorative. Under forced colours the selection ring becomes a system-coloured outline, and the check is drawn with borders, so both stay visible; an unselected card has no outline there.
+
+### Keyboard
+
+| Key              | Action                                                                        |
+| ---------------- | ----------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>   | Moves to the card's `bfAction` link or button, then to its select button      |
+| <kbd>Enter</kbd> | Follows a `bfAction` link, activates a `bfAction` button or toggles selection |
+| <kbd>Space</kbd> | Activates a `bfAction` button or toggles selection; a link ignores it         |
+
+## Inputs
+
+| Name           | Type                                                      | Default  | Description                                                                                                                                                                 |
+| -------------- | --------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`          | `string`                                                  | `''`     | URL of the image; empty shows the skeleton while `loading`, else an empty area. A new URL starts over: skeleton, fade-in, and a failed load is forgotten.                   |
+| `alt`          | `string`                                                  | `''`     | Alternative text of the image; empty marks it decorative.                                                                                                                   |
+| `aspect`       | `BfMediaCardAspect` (`'16/9' \| '4/3' \| '1/1' \| '3/4'`) | `'16/9'` | Aspect ratio of the image area: `16/9` (default), `4/3`, `1/1` or `3/4`.                                                                                                    |
+| `loading`      | `boolean`                                                 | `false`  | Shows the skeleton while there is no `src` yet (a picture that is still being made).                                                                                        |
+| `failed`       | `boolean`                                                 | `false`  | Shows the failure message (the app could not make the picture); the app clears it. A load error of `src` shows it too, until `src` changes.                                 |
+| `loadingLabel` | `string`                                                  | `''`     | Caption shown over the skeleton while loading ("Drawing…"); empty shows none and tells screen readers `provideBfLabels()`'s `loading` ("Loading").                          |
+| `failedLabel`  | `string`                                                  | `''`     | Failure message; empty uses `provideBfLabels()`'s `imageLoadFailed`.                                                                                                        |
+| `selectable`   | `boolean`                                                 | `false`  | Adds a select button (a toggle with `aria-pressed`): the whole card toggles `selected`, or, with a `bfAction` in the card, a round check button in the image's corner does. |
+| `label`        | `string`                                                  | `''`     | The card's name in its select button ("Select Starfall"); empty names it by the body's text.                                                                                |
+| `selected`     | `boolean`                                                 | `false`  | Whether the card is selected (a ring around it and a filled check); two-way bindable. Drawn only on a `selectable` card. Two-way: `[(selected)]`.                           |
+
+## Outputs
+
+| Name      | Payload   | Description                                                             |
+| --------- | --------- | ----------------------------------------------------------------------- |
+| `changed` | `boolean` | The user selected or cleared the card; emits the new `selected`.        |
+| `loaded`  | `void`    | The image of `src` has loaded.                                          |
+| `errored` | `void`    | The image of `src` failed to load (the card shows the failure message). |
+
+## Slots
+
+- `failed-action`: An action shown under the failure message, such as a Retry button.
+- `default`: The card body: a title (with an optional bfAction link or button) and text.
+- `footer`: Content below the body, such as chips and buttons; it sits on the card's bottom edge.
+
+## Notes
+
+### Do
+
+- Give every meaningful picture an `alt` that says what it shows.
+- Set `loading` (and a `loadingLabel` such as "Drawing…") while a picture is being made, so the card holds its place.
+- Put a Retry button in `bfSlot="failed-action"`, and retry with a changed `src`.
+- Set `label` on a selectable card to its title, so the select button reads "Select Starfall".
+
+### Don't
+
+- Don't project your own `<img>` into the body for the main picture; pass `src`, so the card handles loading, fading and failing.
+- Don't put more than one `bfAction` in a card.
+- Don't use `selected` as a highlight without `selectable`: the ring only shows on a selectable card, whose button tells assistive technology the state.
+
+## Migration notes
+
+### 0.5.0
+
+New: `bf-media-card`, a card led by a picture (a game pitch, a generated image). The card renders
+the picture itself from `src` and `alt` in a top area at a fixed `aspect` (new type
+`BfMediaCardAspect`: `'16/9'` (default), `'4/3'`, `'1/1'`, `'3/4'`). While it loads, and while
+`src` is empty but `loading` is set (a picture still being made), the area shows a `bf-skeleton`
+shimmer with an optional `loadingLabel` caption ("Drawing…") and is `aria-busy`. The picture fades
+in over 260 ms (`bfFadeIn`) while the skeleton fades out under it; at once under reduced motion.
+A load error, or `failed` set by the app, shows `failedLabel` (default: the new label
+`imageLoadFailed`) and the `bfSlot="failed-action"` content (Retry); a new `src` starts over.
+`loaded` and `errored` report the image's events. A body slot and a `footer` slot follow. A
+`bfAction` link or button in the title makes the whole card clickable, as on `bf-card` (pointer,
+`shadow-floating` hover, focus ring, fading on `duration-fast`). `selectable` adds a toggle
+button (`aria-pressed`) bound with `[(selected)]` (a `model()`), emitting `changed` on each user
+change: the whole card without a `bfAction`, else a round check button in the image's corner; a
+selected card has a 2 px primary ring and a filled check. `label` names it ("Select" + `label`,
+new label `mediaCardSelect`). `@bitforgehq/ui/testing`: new `BfMediaCardHarness`
+(`getState()`, `loadImage()`, `failImage()`, `getLoadingLabel()`, `getFailedMessage()`,
+`isSelected()`, `toggleSelected()`).

package/ai/components/menu-button.md

@@ -311,6 +311,8 @@ Hover and focus look like `bf-button` (or `bf-icon-button` with `iconOnly`): the
   last. Closing the menu (`Escape`, `Tab`, an item) returns focus to the button.
 - The caret is drawn in CSS and adds nothing to the name.
 - Hit area: at least 32 px, 44 px under a coarse pointer (as `bf-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/menu.md

@@ -570,6 +570,9 @@ Built for desktop: hovering an item gives it the `surface-muted` fill and the po
   closing the dialog.
 - Pointer: rows are at least 32 px tall, 44 px under a coarse pointer. An open submenu stays open
   while the pointer moves diagonally towards it across other items (CDK menu aim).
+- Motion: the menu grows out of its trigger as it opens (a fade, a slight scale and a 4 px slide,
+  180 ms; a submenu out of its item). It closes at once, because the CDK menu removes it
+  immediately. Under `prefers-reduced-motion` it only fades in.
 
 ### Keyboard
 
@@ -619,6 +622,13 @@ From the [APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
 
 ## Migration notes
 
+### 0.5.0
+
+The menu animates open: it grows out of its trigger (a fade, a scale from 96 % and a 4 px slide,
+180 ms, ease-out), a submenu out of its item. It still closes at once, because the CDK menu
+removes it immediately. Under `prefers-reduced-motion` it only fades in. `bf-menu-button` and
+`bf-theme-menu-button` get the same enter.
+
 ### 0.3.1
 
 The menu's positions now come from the anchored-panel positioning the popover and tooltip share.

package/ai/components/multi-combobox.md

@@ -171,6 +171,8 @@ coarse pointer its hit area grows to 44 px and every option row is at least 44 p
   order before the input.
 - Labels, help and error text, `aria-describedby`, `aria-invalid` and `aria-errormessage` follow
   `bf-select`. `required` sets the native attribute only while no tag is picked.
+- Motion: the list opens and closes with the same short fade, scale and slide as on
+  `bf-combobox`, and only fades under `prefers-reduced-motion`.
 
 ### Keyboard
 
@@ -247,6 +249,11 @@ Focuses the input; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.5.0
+
+The list panel is exactly as wide as the field. The inner text input no longer shows a square
+border and ring on focus in apps that load `@tailwindcss/forms`.
+
 ### 0.3.1
 
 New `bf-multi-combobox` (`BfMultiComboboxComponent<T>`) in `@bitforgehq/ui/overlay`: the

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/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