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

package/CHANGELOG.md

@@ -303,6 +303,53 @@ large image loads it shows the thumbnail and a spinner, then fades the image in.
 `getCounterText()`, `getSrc()`, `getAlt()`, `getCaption()`, `next()`, `previous()`,
 `pressKey()`, `close()`, `loadImage()`, `failImage()`, `isLoaded()`, `hasFailed()`).
 
+### image-tile
+
+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()`).
+
+### badge
+
+New `icon-start` slot: `<bf-icon bfSlot="icon-start" … />` before the label text, drawn at 12 px
+whatever the icon's `size`, 4 px from the text, with the start padding tightened to 8 px. It
+takes the text colour, so it follows the variant and forced colours. A count pill does not show
+it.
+
+### menu-button
+
+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`.
+
+### pagination
+
+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.5.0-next.4 (2026-11-07)
+
+Pre-release of 0.5.0: its changes are listed under "0.5.0 (unreleased)" above.
+
 ## 0.5.0-next.3 (2026-11-07)
 
 Pre-release of 0.5.0: its changes are listed under "0.5.0 (unreleased)" above.

package/README.md

@@ -140,10 +140,10 @@ Render library components only in the browser, for example in a `@defer` block o
 route. Support will be decided before 1.0.
 
 The one server-side check is a render smoke, not a support test: the library repository's
-`tools/ssr-smoke.ts` renders 49 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`tools/ssr-smoke.ts` renders 50 fixtures with `renderApplication()` (every root widget, `bf-icon`,
 `bf-number-input`, `bf-select` from `/overlay`, a `/charts` line chart, a `/mobile` page with
 `provideBfShell()`, `bf-page`, `bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under
-the router, and an `/overlay` dialog), and all of them render without an error. 31 of them render
+the router, and an `/overlay` dialog), and all of them render without an error. 32 of them render
 identically twice. The other 18 number their ids differently on every render, from a module-level
 counter, so they could not hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-file-input`, `bf-image-input`, `bf-input`,
 `bf-radio-group`, `bf-segmented`, `bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`,
@@ -163,7 +163,7 @@ overlays and themes leave on the document after each test (when TestBed destroys
 environment, so keep its default `teardown: { destroyAfterEach: true }`), and the CDK harnesses
 (`BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`,
 `BfMenuButtonHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfDesktopToastHarness`,
-`BfTableHarness`, `BfPaginationHarness`, `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfImageViewerHarness`, `BfChatComposerHarness`, `BfChartHarness`) drive the
+`BfTableHarness`, `BfPaginationHarness`, `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfImageTileHarness`, `BfImageViewerHarness`, `BfChatComposerHarness`, `BfChartHarness`) drive the
 widgets whose DOM a spec should not query by hand; overlays come from
 `TestbedHarnessEnvironment.documentRootLoader(fixture)`. An app on the mobile shell uses
 `provideBfShellTesting()` from `@bitforgehq/ui/mobile` instead (router, shell, an in-memory theme

package/ai/MANIFEST.index.json

@@ -334,6 +334,15 @@
       "summary": "Single-image picker with a round or square preview tile and replace or remove",
       "since": "0.5.0"
     },
+    {
+      "name": "image-tile",
+      "selector": "bf-image-tile",
+      "className": "BfImageTileComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Small card for thumbnail grids: a picture and title that act as one target",
+      "since": "0.5.0"
+    },
     {
       "name": "image-viewer",
       "selector": "bf-image-viewer",

package/ai/MANIFEST.json

@@ -876,7 +876,7 @@
       "summary": "Small status label in semantic tones, or a compact numeric pill for counts",
       "description": "Status label (\"On track\", \"At risk\") or, with `count`, a compact numeric pill for unread counts.",
       "overview": "Badges label a status (\"On track\", \"At risk\") or, as a count pill, show how many items are waiting. They are read-only; use a `bf-chip` for anything the user can toggle.",
-      "example": "<bf-badge variant=\"warning\">At risk</bf-badge>\n<bf-badge variant=\"danger\" emphasis=\"strong\">Critical</bf-badge>\n<bf-badge [count]=\"unread()\" countLabel=\"unread messages\" />",
+      "example": "<bf-badge variant=\"warning\">At risk</bf-badge>\n<bf-badge variant=\"danger\" emphasis=\"strong\">Critical</bf-badge>\n<bf-badge [count]=\"unread()\" countLabel=\"unread messages\" />\n<bf-badge variant=\"success\"><bf-icon bfSlot=\"icon-start\" [icon]=\"Check\" />Reference</bf-badge>",
       "primaryExample": "badge/overview",
       "examples": [
         {
@@ -900,6 +900,13 @@
           "source": "import { Component } from '@angular/core';\nimport { BfBadgeComponent } from '@bitforgehq/ui';\n\n/** A strong badge marks the one critical finding among soft status badges. */\n@Component({\n  selector: 'app-example-badge-strong',\n  imports: [BfBadgeComponent],\n  template: `\n    <div class=\"flex flex-wrap items-center gap-2\">\n      <bf-badge variant=\"danger\" emphasis=\"strong\">Critical</bf-badge>\n      <bf-badge variant=\"danger\">High</bf-badge>\n      <bf-badge variant=\"warning\">Medium</bf-badge>\n      <bf-badge>Low</bf-badge>\n      <bf-badge variant=\"danger\" emphasis=\"strong\" [count]=\"3\" countLabel=\"critical findings\" />\n    </div>\n  `,\n})\nexport class BadgeStrongExampleComponent {}\n",
           "preview": "inline"
         },
+        {
+          "id": "badge/icon",
+          "title": "Badges with a leading icon: the icon repeats the meaning, the text still says it",
+          "file": "projects/docs/src/app/examples/badge/icon-example.component.ts",
+          "source": "import { Component } from '@angular/core';\nimport { BfBadgeComponent } from '@bitforgehq/ui';\nimport { BfIconComponent } from '@bitforgehq/ui/icons';\nimport { Box, Check, Clock } from 'lucide';\n\n/** Badges with a leading icon: the icon repeats the meaning, the text still says it. */\n@Component({\n  selector: 'app-example-badge-icon',\n  imports: [BfBadgeComponent, BfIconComponent],\n  template: `\n    <div class=\"flex flex-wrap items-center gap-2\">\n      <bf-badge variant=\"success\"><bf-icon bfSlot=\"icon-start\" [icon]=\"check\" />Reference</bf-badge>\n      <bf-badge variant=\"info\"><bf-icon bfSlot=\"icon-start\" [icon]=\"box\" />3 versions</bf-badge>\n      <bf-badge variant=\"warning\" emphasis=\"strong\"\n        ><bf-icon bfSlot=\"icon-start\" [icon]=\"clock\" />Queued</bf-badge\n      >\n    </div>\n  `,\n})\nexport class BadgeIconExampleComponent {\n  protected readonly check = Check;\n  protected readonly box = Box;\n  protected readonly clock = Clock;\n}\n",
+          "preview": "inline"
+        },
         {
           "id": "badge/count",
           "title": "A count pill that caps at 99+",
@@ -924,6 +931,10 @@
           "heading": "Emphasis",
           "body": "`emphasis=\"strong\"` turns the soft tint into a solid fill with contrasting text, for the one state that must stand out from the rest: a \"Critical\" finding among \"High\" and \"Medium\" ones. It takes every variant (`primary` uses the brand fill) and the count pill too: a strong count takes its fill from `variant`, so `variant=\"danger\" emphasis=\"strong\" [count]=\"3\"` is a red pill, while a soft count stays the primary pill. `emphasis` takes a `BfBadgeEmphasis` (`soft`, the default, or `strong`).\n\n<!-- example: badge/strong -->"
         },
+        {
+          "heading": "Icon",
+          "body": "An icon in the `icon-start` slot sits before the text, at 12 px whatever the `bf-icon`'s own `size`, 4 px from the text, and the start padding tightens to match. Use it to repeat what the text says at a glance, a check on \"Reference\" or a cube on \"3 versions\", never instead of the text. A count pill does not show it.\n\n<!-- example: badge/icon -->"
+        },
         {
           "heading": "Count pill",
           "body": "Setting `count` switches to the compact primary pill. Values above 99 render as \"99+\"; zero renders as \"0\".\n\n<!-- example: badge/count -->"
@@ -972,6 +983,10 @@
       "outputs": [],
       "models": [],
       "slots": [
+        {
+          "name": "icon-start",
+          "doc": "An icon before the text, drawn at 12 px; not shown on a count pill."
+        },
         {
           "name": "default",
           "doc": "The badge text, shown when no `count` is set."
@@ -979,6 +994,10 @@
       ],
       "methods": [],
       "changelog": [
+        {
+          "version": "0.5.0",
+          "text": "New `icon-start` slot: `<bf-icon bfSlot=\"icon-start\" … />` before the label text, drawn at 12 px\nwhatever the icon's `size`, 4 px from the text, with the start padding tightened to 8 px. It\ntakes the text colour, so it follows the variant and forced colours. A count pill does not show\nit."
+        },
         {
           "version": "0.4.0",
           "text": "New `emphasis` input (`BfBadgeEmphasis`: `soft`, the default, or `strong`). `strong` is a solid\nfill with contrasting text in every variant, for the one state that must stand out (\"Critical\");\n`primary` uses the brand fill. A strong count pill takes its fill from `variant` (a soft count pill\nstays primary, as before). In forced colours a strong badge keeps a `CanvasText` outline. Opt-in:\nwithout `emphasis` nothing changes."
@@ -994,8 +1013,8 @@
       ],
       "since": "0.1.0",
       "whenToUse": "Use `bf-badge` for a read-only status or count next to what it describes: \"At risk\" on a project, \"3\" on an inbox row. Use [bf-chip](https://bitforge-ui.web.app/components/chip) instead when the user can toggle it, and [bf-alert](https://bitforge-ui.web.app/components/alert) when the status needs a sentence of explanation.",
-      "theming": "Consumes tokens by variant, background then text:\n\n- `neutral` (default): `neutral-soft` / `neutral`\n- `primary`: `primary-soft` / `primary-strong`\n- `success`: `success-soft` / `success`\n- `warning`: `warning-soft` / `warning`\n- `danger`: `danger-soft` / `danger`\n- `info`: `info-soft` / `info` (≥ 4.5:1 in both modes; it is not derived from the primary, so a custom brand colour leaves it unchanged)\n- Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`\n- Strong (`emphasis=\"strong\"`, label and count pill): `<variant>-strong` / `on-<variant>-strong` (`neutral-strong`, `success-strong`, `warning-strong`, `danger-strong`, `info-strong`, each with its `on-` text token; ≥ 4.5:1 in both modes and the fill ≥ 3:1 on `bg`, `surface` and `surface-sunken`); `primary` uses `primary` / `on-primary`. An app can retune `--color-danger-strong` and `--color-on-danger-strong` (and the others) in `@theme` and `.dark` like any status token\n- Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).",
-      "accessibility": "A badge is a plain `<span>` with no role or ARIA attributes; its text is read as part of the surrounding content, so pair it with a label or context that says what it means rather than relying on color alone. A count pill with `countLabel` carries that context itself: a visually hidden (`sr-only`) span after the number, read as one phrase with it (\"99+ unread messages\"). A strong badge is louder, not more meaningful: its text (\"Critical\", \"Kritisch\") still says the state. In forced colours (Windows High Contrast) the fills give way to the system colours, so a strong badge draws a `CanvasText` outline and still reads as a filled pill next to a soft one.",
+      "theming": "Consumes tokens by variant, background then text:\n\n- `neutral` (default): `neutral-soft` / `neutral`\n- `primary`: `primary-soft` / `primary-strong`\n- `success`: `success-soft` / `success`\n- `warning`: `warning-soft` / `warning`\n- `danger`: `danger-soft` / `danger`\n- `info`: `info-soft` / `info` (≥ 4.5:1 in both modes; it is not derived from the primary, so a custom brand colour leaves it unchanged)\n- Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`\n- Strong (`emphasis=\"strong\"`, label and count pill): `<variant>-strong` / `on-<variant>-strong` (`neutral-strong`, `success-strong`, `warning-strong`, `danger-strong`, `info-strong`, each with its `on-` text token; ≥ 4.5:1 in both modes and the fill ≥ 3:1 on `bg`, `surface` and `surface-sunken`); `primary` uses `primary` / `on-primary`. An app can retune `--color-danger-strong` and `--color-on-danger-strong` (and the others) in `@theme` and `.dark` like any status token\n- Icon (`icon-start`): drawn in the text colour (`currentColor`), so it follows the variant and stays visible in forced colours\n- Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).",
+      "accessibility": "A badge is a plain `<span>` with no role or ARIA attributes; a `bf-icon` in `icon-start` is decorative (`aria-hidden`) unless it has a `label`, so the text alone carries the meaning; its text is read as part of the surrounding content, so pair it with a label or context that says what it means rather than relying on color alone. A count pill with `countLabel` carries that context itself: a visually hidden (`sr-only`) span after the number, read as one phrase with it (\"99+ unread messages\"). A strong badge is louder, not more meaningful: its text (\"Critical\", \"Kritisch\") still says the state. In forced colours (Windows High Contrast) the fills give way to the system colours, so a strong badge draws a `CanvasText` outline and still reads as a filled pill next to a soft one.",
       "notes": "## Do\n\n- Keep labels to one or two words; badges are scanned, not read.\n- Pair a count pill with a label or icon that says what is being counted, and set `countLabel` so the number is not read alone.\n- Keep `emphasis=\"strong\"` for the one state that must stand out on the screen, such as critical findings.\n\n## Don't\n\n- Don't use a badge as a button; it has no interactive states.\n- Don't invent new colors on it; pick the variant that matches the meaning.\n- Don't use `primary` or `success` for a category; use `info`, so the status tones keep their meaning.\n- Don't make every badge strong: when all of them shout, none stands out."
     },
     {
@@ -6318,6 +6337,185 @@
       "accessibility": "The tile is a native `<button>` named \"Choose image\" (`imageInputChoose`; `ariaLabel` replaces it while there is no visible label) and described by the label, the help and the error paragraph, so a screen reader hears \"Choose image, Profile picture\". `aria-invalid` and `aria-errormessage` are set once touched and invalid. Upload / Replace and Remove are native buttons described by the label, so \"Remove\" says what it removes. The preview image is decorative (`alt=\"\"`): the label names what it shows. The native `<input type=\"file\">` is visually hidden and out of the tab order. `required` gives the label its marker; there is no `aria-required`, which is not allowed on a button. The rejection reason shows at once under the buttons, and a polite live region announces it. After Remove, focus returns to the tile. `focus()` focuses the tile; Signal Forms calls it from `focusBoundControl()`.\n\n### Keyboard\n\n| Key                                              | Where        | Action                                                           |\n| ------------------------------------------------ | ------------ | ---------------------------------------------------------------- |\n| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Control      | Moves through the tile, Upload / Replace and Remove              |\n| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Tile, Upload | Opens the native file picker                                     |\n| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Remove       | Clears the picked and the existing image; focus goes to the tile |",
       "notes": "## Do\n\n- Bind `[(src)]` to the saved picture, and compare `value` and `src` on save to know what changed.\n- Set `accept` and `maxSize` to what the server takes.\n- Use `square` for logos and covers, `round` for people.\n\n## Don't\n\n- Don't use it for several files or documents; use `bf-file-input`.\n- Don't bind both `[(value)]` and `[formField]`.\n- Don't count on `required()` while a `src` can fill the field; use the `validate()` rule."
     },
+    {
+      "name": "image-tile",
+      "selector": "bf-image-tile",
+      "selectors": ["bf-image-tile"],
+      "className": "BfImageTileComponent",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/image-tile/image-tile.component.ts",
+      "category": "Data display",
+      "summary": "Small card for thumbnail grids: a picture and title that act as one target",
+      "description": "Small card for a grid of thumbnails: mostly picture, at a fixed aspect ratio (square by\ndefault), with a title and an optional meta line below it or, with `captionPlacement=\"overlay\"`,\non a soft gradient over its bottom. Without a picture yet it shows a placeholder (an icon and a\ntext); while one loads a shimmering skeleton; the picture fades in when it arrives; a failed load\nshows a short message. Make the whole tile one link or button with a `bfAction` in its title, as\non `bf-card`: it then lifts on hover, zooms the picture slightly and shows the focus ring.\n`selected` draws a ring. The title clamps to two lines and always takes two, so tiles in a grid\nrow are as tall whatever their titles.",
+      "overview": "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.",
+      "example": "<bf-image-tile [src]=\"model.thumbnail\" [selected]=\"model.id === current()\">\n  <h3><a bfAction [routerLink]=\"['/models', model.id]\">{{ model.name }}</a></h3>\n  <span bfSlot=\"meta\">{{ model.updated }}</span>\n  <bf-badge bfSlot=\"badge\" variant=\"info\">3 versions</bf-badge>\n</bf-image-tile>",
+      "primaryExample": "image-tile/overview",
+      "examples": [
+        {
+          "id": "image-tile/overview",
+          "title": "The bf-image-tile overview",
+          "file": "projects/docs/src/app/examples/image-tile/overview-example.component.ts",
+          "source": "import { Component, DestroyRef, inject, signal } from '@angular/core';\nimport { BfActionDirective, BfBadgeComponent, BfImageTileComponent } from '@bitforgehq/ui';\nimport { BfIconComponent } from '@bitforgehq/ui/icons';\nimport { Box, ImagePlus } from 'lucide';\n\n/** One model in the grid, as the app tracks it. */\ninterface Model {\n  readonly id: string;\n  readonly name: string;\n  readonly src: string;\n  readonly alt: string;\n  readonly versions: number;\n  readonly updated: string;\n}\n\n/** How long the simulated render of the last model takes. */\nconst RENDER_MS = 3000;\n\n/**\n * The bf-image-tile overview.\n *\n * A grid of 3D models, one picture each: a click selects a tile (the ring, and \"Selected\" read\n * before its title), a badge counts the versions, the last picture is still rendering and fades\n * in when it arrives, and a model without a render yet shows the placeholder. The titles differ\n * in length, yet every tile in a row is as tall.\n */\n@Component({\n  selector: 'app-example-image-tile-overview',\n  imports: [BfActionDirective, BfBadgeComponent, BfIconComponent, BfImageTileComponent],\n  template: `\n    <div class=\"grid grid-cols-2 gap-4 @md:grid-cols-4\">\n      @for (model of models(); track model.id) {\n        <bf-image-tile\n          [src]=\"model.src\"\n          [alt]=\"model.alt\"\n          [loading]=\"model.id === 'lantern' && rendering()\"\n          [selected]=\"model.id === current()\"\n        >\n          <h2>\n            <button bfAction type=\"button\" (click)=\"current.set(model.id)\">{{ model.name }}</button>\n          </h2>\n          <span bfSlot=\"meta\">{{ model.updated }}</span>\n          @if (model.versions > 1) {\n            <bf-badge bfSlot=\"badge\" variant=\"info\"\n              ><bf-icon bfSlot=\"icon-start\" [icon]=\"box\" />{{ model.versions }} versions</bf-badge\n            >\n          }\n          <bf-icon bfSlot=\"placeholder-icon\" [icon]=\"imagePlus\" />\n        </bf-image-tile>\n      }\n    </div>\n    <p aria-live=\"polite\" class=\"text-caption text-text-muted mt-3\">\n      Selected: {{ currentName() }}\n    </p>\n  `,\n})\nexport class ImageTileOverviewExampleComponent {\n  protected readonly box = Box;\n  protected readonly imagePlus = ImagePlus;\n  protected readonly current = signal('ship');\n  protected readonly rendering = signal(true);\n  protected readonly models = signal<Model[]>([\n    {\n      id: 'ship',\n      name: 'Harbour ship',\n      src: 'media/harbour.svg',\n      alt: 'A ship in a harbour',\n      versions: 3,\n      updated: 'Today',\n    },\n    {\n      id: 'tower',\n      name: 'Glacier watchtower with a long rope bridge',\n      src: 'media/glacier.svg',\n      alt: 'A tower on a glacier',\n      versions: 1,\n      updated: 'Yesterday',\n    },\n    { id: 'well', name: 'Desert well', src: '', alt: '', versions: 1, updated: 'Last week' },\n    {\n      id: 'lantern',\n      name: 'Forest lantern',\n      src: '',\n      alt: 'A lantern in a pine forest',\n      versions: 2,\n      updated: 'Rendering…',\n    },\n  ]);\n\n  constructor() {\n    const timer = setTimeout(() => {\n      this.models.update((models) =>\n        models.map((m) =>\n          m.id === 'lantern' ? { ...m, src: 'media/forest.svg', updated: 'Just now' } : m,\n        ),\n      );\n      this.rendering.set(false);\n    }, RENDER_MS);\n    inject(DestroyRef).onDestroy(() => clearTimeout(timer));\n  }\n\n  protected currentName(): string {\n    return this.models().find((m) => m.id === this.current())?.name ?? '';\n  }\n}\n",
+          "preview": "inline"
+        },
+        {
+          "id": "image-tile/states",
+          "title": "The four states of a tile side by side",
+          "file": "projects/docs/src/app/examples/image-tile/states-example.component.ts",
+          "source": "import { Component } from '@angular/core';\nimport { BfImageTileComponent } from '@bitforgehq/ui';\nimport { BfIconComponent } from '@bitforgehq/ui/icons';\nimport { ImagePlus } from 'lucide';\n\n/**\n * The four states of a tile side by side.\n *\n * Without `src` the placeholder shows (an icon and \"No image yet\"); `loading` shows the skeleton;\n * a `src` fades in when it loads; `failed` (or a load error) shows a short message.\n */\n@Component({\n  selector: 'app-example-image-tile-states',\n  imports: [BfIconComponent, BfImageTileComponent],\n  template: `\n    <div class=\"grid grid-cols-2 gap-4 @md:grid-cols-4\">\n      <bf-image-tile>\n        <h2>Placeholder</h2>\n        <bf-icon bfSlot=\"placeholder-icon\" [icon]=\"imagePlus\" />\n      </bf-image-tile>\n      <bf-image-tile loading><h2>Loading</h2></bf-image-tile>\n      <bf-image-tile src=\"media/forest.svg\" alt=\"A pine forest under a pale sun\">\n        <h2>Loaded</h2>\n      </bf-image-tile>\n      <bf-image-tile failed failedLabel=\"Render failed\"><h2>Failed</h2></bf-image-tile>\n    </div>\n  `,\n})\nexport class ImageTileStatesExampleComponent {\n  protected readonly imagePlus = ImagePlus;\n}\n",
+          "preview": "inline"
+        },
+        {
+          "id": "image-tile/overlay",
+          "title": "A board of reference pictures with the caption over the picture",
+          "file": "projects/docs/src/app/examples/image-tile/overlay-example.component.ts",
+          "source": "import { Component } from '@angular/core';\nimport { BfActionDirective, BfBadgeComponent, BfImageTileComponent } from '@bitforgehq/ui';\nimport { BfIconComponent } from '@bitforgehq/ui/icons';\nimport { Check } from 'lucide';\n\n/** One reference picture on the board. */\ninterface Reference {\n  readonly id: string;\n  readonly title: string;\n  readonly source: string;\n  readonly src: string;\n  readonly reference: boolean;\n}\n\n/**\n * A board of reference pictures with the caption over the picture.\n *\n * `captionPlacement=\"overlay\"` lays the title and meta line on a soft gradient over the bottom of\n * a 4:3 picture; each tile is a link, and a check badge marks the chosen references.\n */\n@Component({\n  selector: 'app-example-image-tile-overlay',\n  imports: [BfActionDirective, BfBadgeComponent, BfIconComponent, BfImageTileComponent],\n  template: `\n    <div class=\"grid grid-cols-1 gap-4 @sm:grid-cols-2 @lg:grid-cols-3\">\n      @for (item of references; track item.id) {\n        <bf-image-tile [src]=\"item.src\" alt=\"\" aspect=\"4/3\" captionPlacement=\"overlay\">\n          <h2>\n            <a bfAction [href]=\"'#' + item.id\">{{ item.title }}</a>\n          </h2>\n          <span bfSlot=\"meta\">{{ item.source }}</span>\n          @if (item.reference) {\n            <bf-badge bfSlot=\"badge\" variant=\"success\" emphasis=\"strong\"\n              ><bf-icon bfSlot=\"icon-start\" [icon]=\"check\" />Reference</bf-badge\n            >\n          }\n        </bf-image-tile>\n      }\n    </div>\n  `,\n})\nexport class ImageTileOverlayExampleComponent {\n  protected readonly check = Check;\n  protected readonly references: Reference[] = [\n    {\n      id: 'skyline',\n      title: 'Skyline at dusk',\n      source: 'Moodboard',\n      src: 'media/skyline.svg',\n      reference: true,\n    },\n    {\n      id: 'desert',\n      title: 'Dunes in the late afternoon, warm light from the west',\n      source: 'Upload',\n      src: 'media/desert.svg',\n      reference: false,\n    },\n    {\n      id: 'glacier',\n      title: 'Glacier',\n      source: 'Moodboard',\n      src: 'media/glacier.svg',\n      reference: true,\n    },\n  ];\n}\n",
+          "preview": "inline"
+        }
+      ],
+      "usage": [
+        {
+          "heading": "Basic usage",
+          "body": "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.\n\n<!-- example: image-tile/overview -->"
+        },
+        {
+          "heading": "States",
+          "body": "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.\n\n<!-- example: image-tile/states -->"
+        },
+        {
+          "heading": "Caption over the picture",
+          "body": "`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.\n\n<!-- example: image-tile/overlay -->"
+        },
+        {
+          "heading": "Grids of tiles",
+          "body": "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."
+        }
+      ],
+      "inputs": [
+        {
+          "name": "src",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "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.",
+          "default": "''"
+        },
+        {
+          "name": "alt",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "Alternative text of the picture; empty marks it decorative (the title names the tile).",
+          "default": "''"
+        },
+        {
+          "name": "aspect",
+          "kind": "input",
+          "type": "BfImageTileAspect",
+          "required": false,
+          "doc": "Aspect ratio of the picture: `1/1` (default), `4/3`, `16/9` or `3/4`.",
+          "default": "'1/1'",
+          "expandedType": "'1/1' | '4/3' | '16/9' | '3/4'"
+        },
+        {
+          "name": "captionPlacement",
+          "kind": "input",
+          "type": "BfImageTileCaptionPlacement",
+          "required": false,
+          "doc": "Where the title and the meta line sit: `below` the picture (default) or `overlay`, on a gradient over its bottom.",
+          "default": "'below'",
+          "expandedType": "'below' | 'overlay'"
+        },
+        {
+          "name": "loading",
+          "kind": "input",
+          "type": "boolean",
+          "required": false,
+          "doc": "Shows the skeleton while there is no `src` yet (a picture that is still being made).",
+          "default": "false"
+        },
+        {
+          "name": "failed",
+          "kind": "input",
+          "type": "boolean",
+          "required": false,
+          "doc": "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.",
+          "default": "false"
+        },
+        {
+          "name": "selected",
+          "kind": "input",
+          "type": "boolean",
+          "required": false,
+          "doc": "Marks the tile as the selected one: a ring around it, and \"Selected\" read before its title.",
+          "default": "false"
+        },
+        {
+          "name": "placeholderLabel",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "Placeholder text while there is no picture; empty uses `provideBfLabels()`'s `imageTileEmpty` (\"No image yet\").",
+          "default": "''"
+        },
+        {
+          "name": "failedLabel",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "Failure message; empty uses `provideBfLabels()`'s `imageLoadFailed`.",
+          "default": "''"
+        }
+      ],
+      "outputs": [
+        {
+          "name": "loaded",
+          "kind": "output",
+          "type": "void",
+          "required": false,
+          "doc": "The picture of `src` has loaded."
+        },
+        {
+          "name": "errored",
+          "kind": "output",
+          "type": "void",
+          "required": false,
+          "doc": "The picture of `src` failed to load (the tile shows the failure message)."
+        }
+      ],
+      "models": [],
+      "slots": [
+        {
+          "name": "placeholder-icon",
+          "doc": "The placeholder's icon, shown with its text while there is no picture."
+        },
+        {
+          "name": "badge",
+          "doc": "A `bf-badge` in the picture's top start corner."
+        },
+        {
+          "name": "default",
+          "doc": "The title: a heading holding the tile's `bfAction` link or button."
+        },
+        {
+          "name": "meta",
+          "doc": "A short line under the title, such as a date or a count."
+        }
+      ],
+      "methods": [],
+      "changelog": [
+        {
+          "version": "0.5.0",
+          "text": "New: `bf-image-tile`, a small card for grids of thumbnails (3D models with one render each, a\nboard of reference pictures). It is mostly picture, at a fixed `aspect` (new type\n`BfImageTileAspect`: `'1/1'` (default), `'4/3'`, `'16/9'`, `'3/4'`), with the title (default slot,\na heading holding a `bfAction` link or button) and an optional `bfSlot=\"meta\"` line below the\npicture, or with `captionPlacement=\"overlay\"` (new type `BfImageTileCaptionPlacement`: `'below'`\n(default), `'overlay'`) on a soft `scrim` gradient over its bottom. States share\n`bf-media-card`'s logic: without `src` a placeholder (`bfSlot=\"placeholder-icon\"` and\n`placeholderLabel`, default: the new label `imageTileEmpty`, \"No image yet\"); `loading`, and a\n`src` that is loading, show a `bf-skeleton` shimmer (`aria-busy`); the picture fades in over\n260 ms; a load error or `failed` shows `failedLabel` (default `imageLoadFailed`). `loaded` and\n`errored` report the picture's events. A `bfAction` makes the whole tile one link or button: the\npointer, a 2 px lift to `shadow-floating` and a 5 % zoom of the picture on hover (no movement\nunder reduced motion), and the focus ring. `selected` draws a 2 px primary ring and starts the\naction's name with the new label `imageTileSelected` (\"Selected, Harbour ship\"). `bfSlot=\"badge\"`\nputs a `bf-badge` in the picture's top start corner. The title clamps to two lines and always\ntakes two, so tiles in a grid row are as tall. `@bitforgehq/ui/testing`: new\n`BfImageTileHarness` (`getTitle()`, `getMeta()`, `getState()`, `getSrc()`, `getAlt()`,\n`getPlaceholderText()`, `getFailedMessage()`, `isSelected()`, `isClickable()`, `click()`,\n`loadImage()`, `failImage()`)."
+        }
+      ],
+      "since": "0.5.0",
+      "whenToUse": "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).",
+      "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).\n- Picture area: `bg-surface-sunken`; the skeleton is a `bf-skeleton` rect; the placeholder and failure texts are `text-caption text-text-muted`.\n- 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.\n- Selection: a 2 px `primary` outline 2 px outside the tile.\n- Forced colours: a 1 px `CanvasText` border keeps each tile's edge; the selection ring is `Highlight`.\n- Focus: `ring-4 ring-ring` around the tile.\n- 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.\n\n### Keyboard\n\n| Key              | Action                                                     |\n| ---------------- | ---------------------------------------------------------- |\n| <kbd>Tab</kbd>   | Moves to the tile's `bfAction` link or button              |\n| <kbd>Enter</kbd> | Follows a `bfAction` link or activates a `bfAction` button |\n| <kbd>Space</kbd> | Activates a `bfAction` button; a link ignores it           |",
+      "notes": "## Do\n\n- Use a heading for the title, at the level that fits the page, with the `bfAction` inside it.\n- Set `loading` while a picture is being made, so the tile holds its place.\n- Keep the meta line short: a date, a count, a source.\n\n## Don't\n\n- 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.\n- Don't project your own `<img>` for the picture; pass `src`, so the tile handles loading, fading and failing.\n- Don't rely on the ring alone to mark the selected tile in your own text: the tile already tells assistive technology."
+    },
     {
       "name": "image-viewer",
       "selector": "bf-image-viewer",
@@ -7663,6 +7861,13 @@
           "file": "projects/docs/src/app/examples/menu-button/sizes-example.component.ts",
           "source": "import { Component, signal } from '@angular/core';\nimport {\n  BfMenuButtonComponent,\n  BfMenuComponent,\n  BfMenuItemDirective,\n} from '@bitforgehq/ui/overlay';\n\n/**\n * A small menu button that opens below its end.\n *\n * `size=\"sm\"` sizes the trigger; `placement=\"below-end\"` aligns the menu to its inline end.\n */\n@Component({\n  selector: 'app-example-menu-button-sizes',\n  imports: [BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],\n  template: `\n    <div class=\"flex justify-end\">\n      <bf-menu-button [menu]=\"rowActions\" size=\"sm\" placement=\"below-end\">Actions</bf-menu-button>\n    </div>\n    <p aria-live=\"polite\" class=\"text-caption text-text-muted mt-3\">{{ result() }}</p>\n\n    <ng-template #rowActions>\n      <bf-menu>\n        <button bfMenuItem (triggered)=\"result.set('Renamed.')\">Rename</button>\n        <button bfMenuItem (triggered)=\"result.set('Archived.')\">Archive</button>\n      </bf-menu>\n    </ng-template>\n  `,\n})\nexport class MenuButtonSizesExampleComponent {\n  protected readonly result = signal('');\n}\n",
           "preview": "inline"
+        },
+        {
+          "id": "menu-button/full-width",
+          "title": "A two-column grid of actions on a card, where a menu button fills its cell like the buttons beside it",
+          "file": "projects/docs/src/app/examples/menu-button/full-width-example.component.ts",
+          "source": "import { Component, signal } from '@angular/core';\nimport { BfButtonComponent } from '@bitforgehq/ui';\nimport {\n  BfMenuButtonComponent,\n  BfMenuComponent,\n  BfMenuItemDirective,\n} from '@bitforgehq/ui/overlay';\n\n/**\n * A two-column grid of actions on a card, where a menu button fills its cell like the buttons\n * beside it.\n *\n * `fullWidth` stretches the host and its button, as on `bf-button`.\n */\n@Component({\n  selector: 'app-example-menu-button-full-width',\n  imports: [BfButtonComponent, BfMenuButtonComponent, BfMenuComponent, BfMenuItemDirective],\n  template: `\n    <div class=\"grid max-w-sm grid-cols-2 gap-2\">\n      <bf-button variant=\"outline\" fullWidth (clicked)=\"result.set('Opened.')\">Open</bf-button>\n      <bf-button variant=\"outline\" fullWidth (clicked)=\"result.set('Duplicated.')\"\n        >Duplicate</bf-button\n      >\n      <bf-button variant=\"outline\" fullWidth (clicked)=\"result.set('Shared.')\">Share</bf-button>\n      <bf-menu-button [menu]=\"more\" fullWidth>More</bf-menu-button>\n    </div>\n    <p aria-live=\"polite\" class=\"text-caption text-text-muted mt-3\">{{ result() }}</p>\n\n    <ng-template #more>\n      <bf-menu>\n        <button bfMenuItem (triggered)=\"result.set('Renamed.')\">Rename</button>\n        <button bfMenuItem (triggered)=\"result.set('Archived.')\">Archive</button>\n      </bf-menu>\n    </ng-template>\n  `,\n})\nexport class MenuButtonFullWidthExampleComponent {\n  protected readonly result = signal('');\n}\n",
+          "preview": "inline"
         }
       ],
       "usage": [
@@ -7681,6 +7886,10 @@
         {
           "heading": "Sizes and placement",
           "body": "`size` is `sm` 32, `md` 40 or `lg` 48 px; unset it follows `provideBfDefaults()` (`controlSize`,\n`md` by default). Under a coarse pointer `sm` and `md` reach 44 px without changing their look.\n`placement` sets where the menu opens: `'below-start'` (default), `'below-end'`,\n`'above-start'` or `'above-end'`, flipping when it would overflow the viewport.\n\n<!-- example: menu-button/sizes -->"
+        },
+        {
+          "heading": "Full width",
+          "body": "`fullWidth` stretches the host and its button to the width of their container, as on\n`bf-button`: in a grid of actions, a \"More\" menu button then fills its cell like the buttons\nbeside it. The label and caret stay centred. It does nothing with `iconOnly`, which stays a\nsquare.\n\n<!-- example: menu-button/full-width -->"
         }
       ],
       "inputs": [
@@ -7734,6 +7943,14 @@
           "doc": "Square button holding only the projected icon, like `bf-icon-button`; set `label`.",
           "default": "false"
         },
+        {
+          "name": "fullWidth",
+          "kind": "input",
+          "type": "boolean",
+          "required": false,
+          "doc": "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`.",
+          "default": "false"
+        },
         {
           "name": "disabled",
           "kind": "input",
@@ -7772,6 +7989,10 @@
       ],
       "methods": [],
       "changelog": [
+        {
+          "version": "0.5.0",
+          "text": "New `fullWidth` input, as on `bf-button`: the host and its button stretch to the width of their\ncontainer (label and caret stay centred), so app CSS no longer needs to reach into the inner\n`<button>`. Ignored with `iconOnly`."
+        },
         {
           "version": "0.3.0",
           "text": "New `bf-menu-button` in `@bitforgehq/ui/overlay`: a native `<button>` that opens a `bf-menu`\n(`menu`, a `TemplateRef`) with `aria-haspopup=\"menu\"` and `aria-expanded`, styled like\n`bf-button` (`variant` `outline` (default), `text`, `tonal`; a CSS caret) or, with `iconOnly`,\nlike `bf-icon-button`. `size` (unset follows `controlSize`), `placement`, `label` (the\n`aria-label`, required with `iconOnly`), `disabled`, and `opened`/`closed` outputs. Its classes\ncome from `bf-button`'s and `bf-icon-button`'s own class maps (internal `ɵ` exports of\n`@bitforgehq/ui`), so the looks never drift.\n\nJSDoc of `menu-button.component.ts` for the API reference: `@summary`/`@since` on the exported\nsymbols; `@slot` docs for `icon-start`, `default`. No behaviour change.\n\n**Behaviour:** a pressed state (F-045): the button and icon-only forms take `bf-button`'s and `bf-icon-button`'s pressed fills from their shared class maps. None while disabled; under forced colours the system colours win."
@@ -8964,9 +9185,9 @@
       "file": "src/components/pagination/pagination.component.ts",
       "category": "Navigation",
       "summary": "Previous, next and numbered page buttons for a long list or table",
-      "description": "Page navigation for a long list or table: Previous and Next buttons around the page numbers,\nthe current one marked, the hidden runs shown as an ellipsis. `compact` shows \"Page 3 of 12\"\nbetween the arrows instead, for narrow screens. The page count comes from `pageCount`, or from\n`total` and `pageSize`; the consumer shows the rows of `page`.",
+      "description": "Page navigation for a long list or table: Previous and Next buttons around the page numbers,\nthe current one marked, the hidden runs shown as an ellipsis. `compact` shows \"Page 3 of 12\"\nbetween the arrows instead, for narrow screens. The page count comes from `pageCount`, or from\n`total` and `pageSize`; the consumer shows the rows of `page`. A compact pagination with its own\n`positionLabel`, `previousLabel` and `nextLabel` steps through anything numbered, such as the\nversions of a model (\"‹ v3 of 7 ›\").",
       "overview": "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.",
-      "example": "<bf-pagination [(page)]=\"page\" [pageCount]=\"12\" />\n<bf-pagination [(page)]=\"page\" [total]=\"invoices().length\" [pageSize]=\"10\" compact />",
+      "example": "<bf-pagination [(page)]=\"page\" [pageCount]=\"12\" />\n<bf-pagination [(page)]=\"page\" [total]=\"invoices().length\" [pageSize]=\"10\" compact />\n<bf-pagination [(page)]=\"version\" [pageCount]=\"7\" compact [positionLabel]=\"versionOf\"\n  label=\"Versions\" previousLabel=\"Previous version\" nextLabel=\"Next version\" />",
       "primaryExample": "pagination/overview",
       "examples": [
         {
@@ -8982,6 +9203,13 @@
           "file": "projects/docs/src/app/examples/pagination/compact-example.component.ts",
           "source": "import { Component, signal } from '@angular/core';\nimport { BfPaginationComponent } from '@bitforgehq/ui';\n\n/**\n * Compact pagination for a narrow space.\n *\n * `compact` shows \"Page 3 of 12\" between the arrows instead of the page buttons; the text is a\n * polite live region, so each step is announced.\n */\n@Component({\n  selector: 'app-example-pagination-compact',\n  imports: [BfPaginationComponent],\n  template: `<bf-pagination\n    label=\"Compact result pages\"\n    compact\n    [(page)]=\"page\"\n    [pageCount]=\"12\"\n  />`,\n})\nexport class PaginationCompactExampleComponent {\n  readonly page = signal(3);\n}\n",
           "preview": "inline"
+        },
+        {
+          "id": "pagination/versions",
+          "title": "A compact pager that steps through the versions of a model, \"‹ v3 of 7 ›\"",
+          "file": "projects/docs/src/app/examples/pagination/versions-example.component.ts",
+          "source": "import { Component, signal } from '@angular/core';\nimport { BfPaginationComponent, type BfPaginationPositionLabel } from '@bitforgehq/ui';\n\n/**\n * A compact pager that steps through the versions of a model, \"‹ v3 of 7 ›\".\n *\n * `positionLabel` writes the position text; `previousLabel` and `nextLabel` name the arrows.\n */\n@Component({\n  selector: 'app-example-pagination-versions',\n  imports: [BfPaginationComponent],\n  template: `\n    <bf-pagination\n      compact\n      size=\"sm\"\n      label=\"Versions\"\n      previousLabel=\"Previous version\"\n      nextLabel=\"Next version\"\n      [positionLabel]=\"versionOf\"\n      [pageCount]=\"7\"\n      [(page)]=\"version\"\n    />\n  `,\n})\nexport class PaginationVersionsExampleComponent {\n  readonly version = signal(3);\n  protected readonly versionOf: BfPaginationPositionLabel = (page, count) => `v${page} of ${count}`;\n}\n",
+          "preview": "inline"
         }
       ],
       "usage": [
@@ -8997,6 +9225,10 @@
           "heading": "Compact",
           "body": "`compact` replaces the page buttons with the position as text, \"Page 3 of 12\" (`provideBfLabels()`'s `pageOf`), between the arrows. Use it where the full row does not fit: a narrow column, a phone, a side panel. A responsive page can render the full row from `md` up and the compact one below it (a `hidden md:block` and a `md:hidden` wrapper around two `bf-pagination`s bound to the same `page`).\n\n<!-- example: pagination/compact -->"
         },
+        {
+          "heading": "Stepping through versions",
+          "body": "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.\n\n<!-- example: pagination/versions -->"
+        },
         {
           "heading": "With a table",
           "body": "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."
@@ -9047,6 +9279,30 @@
           "doc": "Shows \"Page 3 of 12\" between the arrows instead of the page buttons, for narrow screens.",
           "default": "false"
         },
+        {
+          "name": "positionLabel",
+          "kind": "input",
+          "type": "BfPaginationPositionLabel | undefined",
+          "required": false,
+          "doc": "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`.",
+          "default": "undefined"
+        },
+        {
+          "name": "previousLabel",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "Accessible name of the previous button, such as \"Previous version\"; empty falls back to `provideBfLabels()`'s `previousPage` (\"Previous page\").",
+          "default": "''"
+        },
+        {
+          "name": "nextLabel",
+          "kind": "input",
+          "type": "string",
+          "required": false,
+          "doc": "Accessible name of the next button, such as \"Next version\"; empty falls back to `provideBfLabels()`'s `nextPage` (\"Next page\").",
+          "default": "''"
+        },
         {
           "name": "size",
           "kind": "input",
@@ -9095,6 +9351,10 @@
         }
       ],
       "changelog": [
+        {
+          "version": "0.5.0",
+          "text": "New `positionLabel` input (new type `BfPaginationPositionLabel`, `(page, count) => string`) that\nwrites a compact pagination's position text, such as \"v3 of 7\"; unset it is the `pageOf` label as\nbefore. New `previousLabel` and `nextLabel` inputs name the arrows (\"Previous version\"); empty\nthey fall back to `previousPage` and `nextPage`. Together they make a compact pager for stepping\nthrough versions."
+        },
         {
           "version": "0.3.1",
           "text": "New `bf-pagination` in `@bitforgehq/ui`, page navigation for both shells: a `nav` (named by\n`label`, else the new `pagination` label) with Previous and Next buttons around the page buttons.\n`[(page)]` is 1-based; the count comes from `pageCount`, else `total` over `pageSize` (default 10).\nThe row keeps the first and the last page and `siblings` (default 1) on each side of the current\none, which carries `aria-current=\"page\"`, and turns hidden runs into an `aria-hidden` ellipsis, at\na constant number of slots. `compact` shows \"Page 3 of 12\" (`pageOf`) between the arrows as a\npolite live region. At the ends the arrows are `aria-disabled` and stay focusable. `size` follows\n`controlSize`; the chevrons are CSS and mirror under `dir=\"rtl\"`. New `BfPaginationHarness` in\n`@bitforgehq/ui/testing` (`getCurrentPage()`, `getPageCount()`, `getVisiblePages()`, `goTo()`,\n`next()`, `previous()`)."

package/ai/REFERENCE.index.json

@@ -337,6 +337,20 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The two tile shapes of an image picker, a circle or a rounded square"
     },
+    {
+      "name": "BfImageTileAspect",
+      "slug": "bf-image-tile-aspect",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "The four aspect ratios of an image tile's picture, square by default"
+    },
+    {
+      "name": "BfImageTileCaptionPlacement",
+      "slug": "bf-image-tile-caption-placement",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Where an image tile's caption sits, below the picture or over it"
+    },
     {
       "name": "BfInputAutocapitalize",
       "slug": "bf-input-autocapitalize",
@@ -407,6 +421,13 @@
       "entryPoint": "@bitforgehq/ui",
       "summary": "The heading level of a page header title, one for a page or two"
     },
+    {
+      "name": "BfPaginationPositionLabel",
+      "slug": "bf-pagination-position-label",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Function that writes a compact pager's position text, such as \"v3 of 7\""
+    },
     {
       "name": "BfProgressSize",
       "slug": "bf-progress-size",
@@ -1982,6 +2003,13 @@
       "entryPoint": "@bitforgehq/ui/testing",
       "summary": "Test harness for the image input: drops an image on it and reads the preview"
     },
+    {
+      "name": "BfImageTileHarness",
+      "slug": "bf-image-tile-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "summary": "Test harness for an image tile: its picture state, title, meta, selection and action"
+    },
     {
       "name": "BfImageViewerHarness",
       "slug": "bf-image-viewer-harness",