@bitforgehq/ui 0.4.0 → 0.5.0-next.4

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

@@ -288,6 +288,55 @@ export class MenuButtonSizesExampleComponent {
 }
 ```
 
+## Full width
+
+`fullWidth` stretches the host and its button to the width of their container, as on
+`bf-button`: in a grid of actions, a "More" menu button then fills its cell like the buttons
+beside it. The label and caret stay centred. It does nothing with `iconOnly`, which stays a
+square.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * A two-column grid of actions on a card, where a menu button fills its cell like the buttons
+ * beside it.
+ *
+ * `fullWidth` stretches the host and its button, as on `bf-button`.
+ */
+@Component({
+  selector: 'app-example-menu-button-full-width',
+  imports: [BfButtonComponent, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],
+  template: `
+    <div class="grid max-w-sm grid-cols-2 gap-2">
+      <bf-button variant="outline" fullWidth (clicked)="result.set('Opened.')">Open</bf-button>
+      <bf-button variant="outline" fullWidth (clicked)="result.set('Duplicated.')"
+        >Duplicate</bf-button
+      >
+      <bf-button variant="outline" fullWidth (clicked)="result.set('Shared.')">Share</bf-button>
+      <bf-menu-button [menu]="more" fullWidth>More</bf-menu-button>
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ result() }}</p>
+
+    <ng-template #more>
+      <bf-menu>
+        <button bfMenuItem (triggered)="result.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="result.set('Archived.')">Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class MenuButtonFullWidthExampleComponent {
+  protected readonly result = signal('');
+}
+```
+
 ## Desktop
 
 Hover and focus look like `bf-button` (or `bf-icon-button` with `iconOnly`): the fill, border or text darkens on hover with the pointer cursor, and the focus ring shows on keyboard focus only. A click opens the menu; a second click on the button closes it. Under a fine pointer the visible box is the hit area. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
@@ -311,6 +360,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
 
@@ -325,15 +376,16 @@ The keys inside the open menu are on the [bf-menu](https://bitforge-ui.web.app/c
 
 ## Inputs
 
-| Name        | Type                                                                               | Default         | Description                                                                                                                      |
-| ----------- | ---------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `menu`      | `TemplateRef<unknown>`                                                             | required        | The `ng-template` holding the `bf-menu` to open.                                                                                 |
-| `variant`   | `BfMenuButtonVariant` (`'outline' \| 'text' \| 'tonal'`)                           | `'outline'`     | Visual style: outline (default), text, tonal.                                                                                    |
-| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                        | `undefined`     | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                       |
-| `placement` | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-start'` | Where the menu opens against the button; it flips when it would overflow.                                                        |
-| `label`     | `string`                                                                           | `''`            | Accessible name (`aria-label`). Required with `iconOnly`; with a visible label leave it empty or start it with the visible text. |
-| `iconOnly`  | `boolean`                                                                          | `false`         | Square button holding only the projected icon, like `bf-icon-button`; set `label`.                                               |
-| `disabled`  | `boolean`                                                                          | `false`         | Disables the button; the menu cannot open.                                                                                       |
+| Name        | Type                                                                               | Default         | Description                                                                                                                                                 |
+| ----------- | ---------------------------------------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `menu`      | `TemplateRef<unknown>`                                                             | required        | The `ng-template` holding the `bf-menu` to open.                                                                                                            |
+| `variant`   | `BfMenuButtonVariant` (`'outline' \| 'text' \| 'tonal'`)                           | `'outline'`     | Visual style: outline (default), text, tonal.                                                                                                               |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                        | `undefined`     | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                  |
+| `placement` | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-start'` | Where the menu opens against the button; it flips when it would overflow.                                                                                   |
+| `label`     | `string`                                                                           | `''`            | Accessible name (`aria-label`). Required with `iconOnly`; with a visible label leave it empty or start it with the visible text.                            |
+| `iconOnly`  | `boolean`                                                                          | `false`         | Square button holding only the projected icon, like `bf-icon-button`; set `label`.                                                                          |
+| `fullWidth` | `boolean`                                                                          | `false`         | Stretches the host and the button to the width of their container, as `bf-button`'s `fullWidth`; the label and caret stay centred. Ignored with `iconOnly`. |
+| `disabled`  | `boolean`                                                                          | `false`         | Disables the button; the menu cannot open.                                                                                                                  |
 
 ## Outputs
 
@@ -361,6 +413,12 @@ The keys inside the open menu are on the [bf-menu](https://bitforge-ui.web.app/c
 
 ## Migration notes
 
+### 0.5.0
+
+New `fullWidth` input, as on `bf-button`: the host and its button stretch to the width of their
+container (label and caret stay centred), so app CSS no longer needs to reach into the inner
+`<button>`. Ignored with `iconOnly`.
+
 ### 0.3.0
 
 New `bf-menu-button` in `@bitforgehq/ui/overlay`: a native `<button>` that opens a `bf-menu`

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