@bitforgehq/ui 0.5.0-next.3 → 0.5.0-next.4

package/ai/components/image-tile.md

@@ -0,0 +1,452 @@
+# bf-image-tile
+
+Small card for thumbnail grids: a picture and title that act as one target
+
+`BfImageTileComponent` from `@bitforgehq/ui` · Data display · since 0.5.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfActionDirective, BfBadgeComponent, BfImageTileComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Box, ImagePlus } from 'lucide';
+
+/** One model in the grid, as the app tracks it. */
+interface Model {
+  readonly id: string;
+  readonly name: string;
+  readonly src: string;
+  readonly alt: string;
+  readonly versions: number;
+  readonly updated: string;
+}
+
+/** How long the simulated render of the last model takes. */
+const RENDER_MS = 3000;
+
+/**
+ * The bf-image-tile overview.
+ *
+ * A grid of 3D models, one picture each: a click selects a tile (the ring, and "Selected" read
+ * before its title), a badge counts the versions, the last picture is still rendering and fades
+ * in when it arrives, and a model without a render yet shows the placeholder. The titles differ
+ * in length, yet every tile in a row is as tall.
+ */
+@Component({
+  selector: 'app-example-image-tile-overview',
+  imports: [BfActionDirective, BfBadgeComponent, BfIconComponent, BfImageTileComponent],
+  template: `
+    <div class="grid grid-cols-2 gap-4 @md:grid-cols-4">
+      @for (model of models(); track model.id) {
+        <bf-image-tile
+          [src]="model.src"
+          [alt]="model.alt"
+          [loading]="model.id === 'lantern' && rendering()"
+          [selected]="model.id === current()"
+        >
+          <h2>
+            <button bfAction type="button" (click)="current.set(model.id)">{{ model.name }}</button>
+          </h2>
+          <span bfSlot="meta">{{ model.updated }}</span>
+          @if (model.versions > 1) {
+            <bf-badge bfSlot="badge" variant="info"
+              ><bf-icon bfSlot="icon-start" [icon]="box" />{{ model.versions }} versions</bf-badge
+            >
+          }
+          <bf-icon bfSlot="placeholder-icon" [icon]="imagePlus" />
+        </bf-image-tile>
+      }
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">
+      Selected: {{ currentName() }}
+    </p>
+  `,
+})
+export class ImageTileOverviewExampleComponent {
+  protected readonly box = Box;
+  protected readonly imagePlus = ImagePlus;
+  protected readonly current = signal('ship');
+  protected readonly rendering = signal(true);
+  protected readonly models = signal<Model[]>([
+    {
+      id: 'ship',
+      name: 'Harbour ship',
+      src: 'media/harbour.svg',
+      alt: 'A ship in a harbour',
+      versions: 3,
+      updated: 'Today',
+    },
+    {
+      id: 'tower',
+      name: 'Glacier watchtower with a long rope bridge',
+      src: 'media/glacier.svg',
+      alt: 'A tower on a glacier',
+      versions: 1,
+      updated: 'Yesterday',
+    },
+    { id: 'well', name: 'Desert well', src: '', alt: '', versions: 1, updated: 'Last week' },
+    {
+      id: 'lantern',
+      name: 'Forest lantern',
+      src: '',
+      alt: 'A lantern in a pine forest',
+      versions: 2,
+      updated: 'Rendering…',
+    },
+  ]);
+
+  constructor() {
+    const timer = setTimeout(() => {
+      this.models.update((models) =>
+        models.map((m) =>
+          m.id === 'lantern' ? { ...m, src: 'media/forest.svg', updated: 'Just now' } : m,
+        ),
+      );
+      this.rendering.set(false);
+    }, RENDER_MS);
+    inject(DestroyRef).onDestroy(() => clearTimeout(timer));
+  }
+
+  protected currentName(): string {
+    return this.models().find((m) => m.id === this.current())?.name ?? '';
+  }
+}
+```
+
+## Overview
+
+Small card for a grid of thumbnails: mostly picture, at a fixed aspect ratio (square by
+default), with a title and an optional meta line below it or, with `captionPlacement="overlay"`,
+on a soft gradient over its bottom. Without a picture yet it shows a placeholder (an icon and a
+text); while one loads a shimmering skeleton; the picture fades in when it arrives; a failed load
+shows a short message. Make the whole tile one link or button with a `bfAction` in its title, as
+on `bf-card`: it then lifts on hover, zooms the picture slightly and shows the focus ring.
+`selected` draws a ring. The title clamps to two lines and always takes two, so tiles in a grid
+row are as tall whatever their titles.
+
+A small card for a grid of thumbnails: 3D models with one render each, a board of reference pictures, a gallery. It is mostly picture, at a fixed aspect ratio (square by default), with a title and an optional meta line below it or over it on a soft gradient. Like `bf-media-card` it owns the whole life of the picture: a placeholder before there is one, a shimmering skeleton while it loads, a fade when it arrives and a short message when it fails.
+
+## When to use
+
+Use `bf-image-tile` for many pictures in a grid, where each one opens or selects something and the picture says more than the text. Use [bf-media-card](https://bitforge-ui.web.app/components/media-card) instead when a card also needs a body text, a footer with buttons or a select-several check button, and [bf-card](https://bitforge-ui.web.app/components/card) for a card without a picture. Open the full-size picture with [bf-image-viewer](https://bitforge-ui.web.app/components/image-viewer).
+
+## Basic usage
+
+Give each tile the picture's `src` and `alt`, a heading with a `bfAction` button or link as its title, and an optional `bfSlot="meta"` line such as a date or a count. A `bf-badge` in `bfSlot="badge"` sits in the picture's top start corner. `selected` marks the current tile with a ring. The titles differ in length, yet every tile in a row is as tall.
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfActionDirective, BfBadgeComponent, BfImageTileComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Box, ImagePlus } from 'lucide';
+
+/** One model in the grid, as the app tracks it. */
+interface Model {
+  readonly id: string;
+  readonly name: string;
+  readonly src: string;
+  readonly alt: string;
+  readonly versions: number;
+  readonly updated: string;
+}
+
+/** How long the simulated render of the last model takes. */
+const RENDER_MS = 3000;
+
+/**
+ * The bf-image-tile overview.
+ *
+ * A grid of 3D models, one picture each: a click selects a tile (the ring, and "Selected" read
+ * before its title), a badge counts the versions, the last picture is still rendering and fades
+ * in when it arrives, and a model without a render yet shows the placeholder. The titles differ
+ * in length, yet every tile in a row is as tall.
+ */
+@Component({
+  selector: 'app-example-image-tile-overview',
+  imports: [BfActionDirective, BfBadgeComponent, BfIconComponent, BfImageTileComponent],
+  template: `
+    <div class="grid grid-cols-2 gap-4 @md:grid-cols-4">
+      @for (model of models(); track model.id) {
+        <bf-image-tile
+          [src]="model.src"
+          [alt]="model.alt"
+          [loading]="model.id === 'lantern' && rendering()"
+          [selected]="model.id === current()"
+        >
+          <h2>
+            <button bfAction type="button" (click)="current.set(model.id)">{{ model.name }}</button>
+          </h2>
+          <span bfSlot="meta">{{ model.updated }}</span>
+          @if (model.versions > 1) {
+            <bf-badge bfSlot="badge" variant="info"
+              ><bf-icon bfSlot="icon-start" [icon]="box" />{{ model.versions }} versions</bf-badge
+            >
+          }
+          <bf-icon bfSlot="placeholder-icon" [icon]="imagePlus" />
+        </bf-image-tile>
+      }
+    </div>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">
+      Selected: {{ currentName() }}
+    </p>
+  `,
+})
+export class ImageTileOverviewExampleComponent {
+  protected readonly box = Box;
+  protected readonly imagePlus = ImagePlus;
+  protected readonly current = signal('ship');
+  protected readonly rendering = signal(true);
+  protected readonly models = signal<Model[]>([
+    {
+      id: 'ship',
+      name: 'Harbour ship',
+      src: 'media/harbour.svg',
+      alt: 'A ship in a harbour',
+      versions: 3,
+      updated: 'Today',
+    },
+    {
+      id: 'tower',
+      name: 'Glacier watchtower with a long rope bridge',
+      src: 'media/glacier.svg',
+      alt: 'A tower on a glacier',
+      versions: 1,
+      updated: 'Yesterday',
+    },
+    { id: 'well', name: 'Desert well', src: '', alt: '', versions: 1, updated: 'Last week' },
+    {
+      id: 'lantern',
+      name: 'Forest lantern',
+      src: '',
+      alt: 'A lantern in a pine forest',
+      versions: 2,
+      updated: 'Rendering…',
+    },
+  ]);
+
+  constructor() {
+    const timer = setTimeout(() => {
+      this.models.update((models) =>
+        models.map((m) =>
+          m.id === 'lantern' ? { ...m, src: 'media/forest.svg', updated: 'Just now' } : m,
+        ),
+      );
+      this.rendering.set(false);
+    }, RENDER_MS);
+    inject(DestroyRef).onDestroy(() => clearTimeout(timer));
+  }
+
+  protected currentName(): string {
+    return this.models().find((m) => m.id === this.current())?.name ?? '';
+  }
+}
+```
+
+## States
+
+Without a `src` the tile shows a placeholder: the `bfSlot="placeholder-icon"` icon and `placeholderLabel`, or the `imageTileEmpty` label ("No image yet"). `loading` shows a `bf-skeleton` shimmer while there is no `src` yet (a render that is still being made), and the same shimmer shows while a `src` loads. The picture fades in over 260 ms (`bfFadeIn`) while the skeleton fades out under it; under reduced motion it appears at once. A picture that fails to load, or one the app could not make (`failed`), shows `failedLabel` or the `imageLoadFailed` label ("The image could not be loaded"). A new `src` starts over and forgets a load error; `failed` is the app's to clear. `loaded` and `errored` report the picture's events.
+
+```ts
+import { Component } from '@angular/core';
+import { BfImageTileComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ImagePlus } from 'lucide';
+
+/**
+ * The four states of a tile side by side.
+ *
+ * Without `src` the placeholder shows (an icon and "No image yet"); `loading` shows the skeleton;
+ * a `src` fades in when it loads; `failed` (or a load error) shows a short message.
+ */
+@Component({
+  selector: 'app-example-image-tile-states',
+  imports: [BfIconComponent, BfImageTileComponent],
+  template: `
+    <div class="grid grid-cols-2 gap-4 @md:grid-cols-4">
+      <bf-image-tile>
+        <h2>Placeholder</h2>
+        <bf-icon bfSlot="placeholder-icon" [icon]="imagePlus" />
+      </bf-image-tile>
+      <bf-image-tile loading><h2>Loading</h2></bf-image-tile>
+      <bf-image-tile src="media/forest.svg" alt="A pine forest under a pale sun">
+        <h2>Loaded</h2>
+      </bf-image-tile>
+      <bf-image-tile failed failedLabel="Render failed"><h2>Failed</h2></bf-image-tile>
+    </div>
+  `,
+})
+export class ImageTileStatesExampleComponent {
+  protected readonly imagePlus = ImagePlus;
+}
+```
+
+## Caption over the picture
+
+`captionPlacement="overlay"` lays the title and the meta line on a soft gradient over the bottom of the picture, so the tile is as tall as its picture and a board of pictures stays dense. The gradient is the `scrim` colour, darkest under the text, and the caption uses the dark theme's text colours, so it reads on light and dark pictures in both themes. `aspect` is `1/1` (default), `4/3`, `16/9` or `3/4` (portrait); the picture covers its area and is cropped to it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfActionDirective, BfBadgeComponent, BfImageTileComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Check } from 'lucide';
+
+/** One reference picture on the board. */
+interface Reference {
+  readonly id: string;
+  readonly title: string;
+  readonly source: string;
+  readonly src: string;
+  readonly reference: boolean;
+}
+
+/**
+ * A board of reference pictures with the caption over the picture.
+ *
+ * `captionPlacement="overlay"` lays the title and meta line on a soft gradient over the bottom of
+ * a 4:3 picture; each tile is a link, and a check badge marks the chosen references.
+ */
+@Component({
+  selector: 'app-example-image-tile-overlay',
+  imports: [BfActionDirective, BfBadgeComponent, BfIconComponent, BfImageTileComponent],
+  template: `
+    <div class="grid grid-cols-1 gap-4 @sm:grid-cols-2 @lg:grid-cols-3">
+      @for (item of references; track item.id) {
+        <bf-image-tile [src]="item.src" alt="" aspect="4/3" captionPlacement="overlay">
+          <h2>
+            <a bfAction [href]="'#' + item.id">{{ item.title }}</a>
+          </h2>
+          <span bfSlot="meta">{{ item.source }}</span>
+          @if (item.reference) {
+            <bf-badge bfSlot="badge" variant="success" emphasis="strong"
+              ><bf-icon bfSlot="icon-start" [icon]="check" />Reference</bf-badge
+            >
+          }
+        </bf-image-tile>
+      }
+    </div>
+  `,
+})
+export class ImageTileOverlayExampleComponent {
+  protected readonly check = Check;
+  protected readonly references: Reference[] = [
+    {
+      id: 'skyline',
+      title: 'Skyline at dusk',
+      source: 'Moodboard',
+      src: 'media/skyline.svg',
+      reference: true,
+    },
+    {
+      id: 'desert',
+      title: 'Dunes in the late afternoon, warm light from the west',
+      source: 'Upload',
+      src: 'media/desert.svg',
+      reference: false,
+    },
+    {
+      id: 'glacier',
+      title: 'Glacier',
+      source: 'Moodboard',
+      src: 'media/glacier.svg',
+      reference: true,
+    },
+  ];
+}
+```
+
+## Grids of tiles
+
+Put the tiles straight into a CSS grid (`grid grid-cols-2 gap-4`, more columns on wider screens). Each tile stretches to its row. The title is clamped to two lines with an ellipsis and always takes the height of two, so a short title and a long one make tiles of the same height; give every tile in a grid a meta line, or none, for the same reason. Below the picture the caption adds 12 px of padding on each side.
+
+## Desktop
+
+A tile with a `bfAction` shows the pointer and, while the pointer is over it, lifts by 2 px to `shadow-floating` and zooms its picture by 5 % inside its frame; pressing it sets it back down. The lift runs on the base timing (200 ms) and the zoom on the slow timing (260 ms). Under reduced motion neither moves: only the shadow changes. The focus ring shows around the whole tile while its action has keyboard focus, not after a click. Text under the stretched action cannot be selected with the mouse.
+
+## Theming
+
+- Tile: `bg-surface`, `text-text`, `rounded-card`, `shadow-raised` (`shadow-floating` on hover).
+- Picture area: `bg-surface-sunken`; the skeleton is a `bf-skeleton` rect; the placeholder and failure texts are `text-caption text-text-muted`.
+- Caption: the title is `text-label-sm` bold, the meta line `text-caption text-text-muted`; over the picture, a `scrim` gradient (80 % to transparent) with the `.dark` text tokens.
+- Selection: a 2 px `primary` outline 2 px outside the tile.
+- Forced colours: a 1 px `CanvasText` border keeps each tile's edge; the selection ring is `Highlight`.
+- Focus: `ring-4 ring-ring` around the tile.
+- Motion: `duration-base` (200 ms) for the lift, shadow and selection ring, `duration-slow` (260 ms) for the zoom and the picture's fade, on `ease-md`; no movement under reduced motion.
+
+## Accessibility
+
+The tile is a plain `<div>`; the picture is an `<img>` with `alt`. When the title names the picture well enough, as in a board of references, leave `alt` empty so it is not read twice. A clickable tile follows the stretched-link pattern of `bf-card`: the only interactive element is the `bfAction` link or button in its title, and its name is the title. A selected tile starts that name with the `imageTileSelected` label, so a screen reader hears "Selected, Harbour ship"; without a `bfAction` the same text is read in the tile. While loading, the picture area is `aria-busy="true"` with a visually hidden "Loading", not a live region, so a grid of loading tiles is not announced tile by tile. Under forced colours the selection ring becomes a `Highlight` outline and the focus indicator a system outline around the tile.
+
+### Keyboard
+
+| Key              | Action                                                     |
+| ---------------- | ---------------------------------------------------------- |
+| <kbd>Tab</kbd>   | Moves to the tile's `bfAction` link or button              |
+| <kbd>Enter</kbd> | Follows a `bfAction` link or activates a `bfAction` button |
+| <kbd>Space</kbd> | Activates a `bfAction` button; a link ignores it           |
+
+## Inputs
+
+| Name               | Type                                                      | Default   | Description                                                                                                                                                 |
+| ------------------ | --------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src`              | `string`                                                  | `''`      | URL of the picture; empty shows the placeholder, or the skeleton while `loading`. A new URL starts over: skeleton, fade-in, and a failed load is forgotten. |
+| `alt`              | `string`                                                  | `''`      | Alternative text of the picture; empty marks it decorative (the title names the tile).                                                                      |
+| `aspect`           | `BfImageTileAspect` (`'1/1' \| '4/3' \| '16/9' \| '3/4'`) | `'1/1'`   | Aspect ratio of the picture: `1/1` (default), `4/3`, `16/9` or `3/4`.                                                                                       |
+| `captionPlacement` | `BfImageTileCaptionPlacement` (`'below' \| 'overlay'`)    | `'below'` | Where the title and the meta line sit: `below` the picture (default) or `overlay`, on a gradient over its bottom.                                           |
+| `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.                 |
+| `selected`         | `boolean`                                                 | `false`   | Marks the tile as the selected one: a ring around it, and "Selected" read before its title.                                                                 |
+| `placeholderLabel` | `string`                                                  | `''`      | Placeholder text while there is no picture; empty uses `provideBfLabels()`'s `imageTileEmpty` ("No image yet").                                             |
+| `failedLabel`      | `string`                                                  | `''`      | Failure message; empty uses `provideBfLabels()`'s `imageLoadFailed`.                                                                                        |
+
+## Outputs
+
+| Name      | Payload | Description                                                               |
+| --------- | ------- | ------------------------------------------------------------------------- |
+| `loaded`  | `void`  | The picture of `src` has loaded.                                          |
+| `errored` | `void`  | The picture of `src` failed to load (the tile shows the failure message). |
+
+## Slots
+
+- `placeholder-icon`: The placeholder's icon, shown with its text while there is no picture.
+- `badge`: A `bf-badge` in the picture's top start corner.
+- `default`: The title: a heading holding the tile's `bfAction` link or button.
+- `meta`: A short line under the title, such as a date or a count.
+
+## Notes
+
+### Do
+
+- Use a heading for the title, at the level that fits the page, with the `bfAction` inside it.
+- Set `loading` while a picture is being made, so the tile holds its place.
+- Keep the meta line short: a date, a count, a source.
+
+### Don't
+
+- Don't put more than one `bfAction` in a tile, or other buttons in it; use a `bf-media-card` for a card with actions.
+- Don't project your own `<img>` for the picture; pass `src`, so the tile handles loading, fading and failing.
+- Don't rely on the ring alone to mark the selected tile in your own text: the tile already tells assistive technology.
+
+## Migration notes
+
+### 0.5.0
+
+New: `bf-image-tile`, a small card for grids of thumbnails (3D models with one render each, a
+board of reference pictures). It is mostly picture, at a fixed `aspect` (new type
+`BfImageTileAspect`: `'1/1'` (default), `'4/3'`, `'16/9'`, `'3/4'`), with the title (default slot,
+a heading holding a `bfAction` link or button) and an optional `bfSlot="meta"` line below the
+picture, or with `captionPlacement="overlay"` (new type `BfImageTileCaptionPlacement`: `'below'`
+(default), `'overlay'`) on a soft `scrim` gradient over its bottom. States share
+`bf-media-card`'s logic: without `src` a placeholder (`bfSlot="placeholder-icon"` and
+`placeholderLabel`, default: the new label `imageTileEmpty`, "No image yet"); `loading`, and a
+`src` that is loading, show a `bf-skeleton` shimmer (`aria-busy`); the picture fades in over
+260 ms; a load error or `failed` shows `failedLabel` (default `imageLoadFailed`). `loaded` and
+`errored` report the picture's events. A `bfAction` makes the whole tile one link or button: the
+pointer, a 2 px lift to `shadow-floating` and a 5 % zoom of the picture on hover (no movement
+under reduced motion), and the focus ring. `selected` draws a 2 px primary ring and starts the
+action's name with the new label `imageTileSelected` ("Selected, Harbour ship"). `bfSlot="badge"`
+puts a `bf-badge` in the picture's top start corner. The title clamps to two lines and always
+takes two, so tiles in a grid row are as tall. `@bitforgehq/ui/testing`: new
+`BfImageTileHarness` (`getTitle()`, `getMeta()`, `getState()`, `getSrc()`, `getAlt()`,
+`getPlaceholderText()`, `getFailedMessage()`, `isSelected()`, `isClickable()`, `click()`,
+`loadImage()`, `failImage()`).

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)).
@@ -327,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
 
@@ -363,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/pagination.md

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