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

package/ai/REFERENCE.json

@@ -915,6 +915,40 @@
       "signature": "type BfImageInputShape = 'round' | 'square'",
       "values": ["round", "square"]
     },
+    {
+      "name": "BfImageTileAspect",
+      "slug": "bf-image-tile-aspect",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/image-tile/image-tile.component.ts",
+      "summary": "The four aspect ratios of an image tile's picture, square by default",
+      "description": "The aspect ratio of a `bf-image-tile`'s picture: square (default), 4:3, 16:9 or 3:4.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-image-tile-component"],
+      "since": "0.5.0",
+      "signature": "type BfImageTileAspect = '1/1' | '4/3' | '16/9' | '3/4'",
+      "values": ["1/1", "4/3", "16/9", "3/4"]
+    },
+    {
+      "name": "BfImageTileCaptionPlacement",
+      "slug": "bf-image-tile-caption-placement",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/image-tile/image-tile.component.ts",
+      "summary": "Where an image tile's caption sits, below the picture or over it",
+      "description": "Where a `bf-image-tile`'s title and meta line sit: `below` the picture (default), or `overlay`,\non a soft gradient over the bottom of the picture.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-image-tile-component"],
+      "since": "0.5.0",
+      "signature": "type BfImageTileCaptionPlacement = 'below' | 'overlay'",
+      "values": ["below", "overlay"]
+    },
     {
       "name": "BfInputAutocapitalize",
       "slug": "bf-input-autocapitalize",
@@ -1899,10 +1933,28 @@
           "kind": "property",
           "type": "string",
           "required": true,
-          "doc": "bf-media-card's and bf-image-viewer's message for an image that failed to load.",
+          "doc": "bf-media-card's, bf-image-tile's and bf-image-viewer's message for an image that failed to load.",
           "readonly": true,
           "default": "'The image could not be loaded'"
         },
+        {
+          "name": "imageTileEmpty",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-image-tile's placeholder text while it has no image yet.",
+          "readonly": true,
+          "default": "'No image yet'"
+        },
+        {
+          "name": "imageTileSelected",
+          "kind": "property",
+          "type": "string",
+          "required": true,
+          "doc": "bf-image-tile's selected state, read before the tile's title (\"Selected, Dragon\").",
+          "readonly": true,
+          "default": "'Selected'"
+        },
         {
           "name": "imageViewer",
           "kind": "property",
@@ -2020,6 +2072,22 @@
       "signature": "type BfPageHeaderHeadingLevel = 1 | 2",
       "values": ["1", "2"]
     },
+    {
+      "name": "BfPaginationPositionLabel",
+      "slug": "bf-pagination-position-label",
+      "kind": "type",
+      "entryPoint": "@bitforgehq/ui",
+      "file": "src/components/pagination/pagination.component.ts",
+      "summary": "Function that writes a compact pager's position text, such as \"v3 of 7\"",
+      "description": "Writes a compact `bf-pagination`'s position text from the current page and the page count, such\nas \"v3 of 7\" for page 3 of 7.",
+      "members": [],
+      "methods": [],
+      "slots": [],
+      "references": [],
+      "usedBy": ["bf-pagination-component"],
+      "since": "0.5.0",
+      "signature": "type BfPaginationPositionLabel = (page: number, count: number) => string"
+    },
     {
       "name": "BfProgressSize",
       "slug": "bf-progress-size",
@@ -3170,7 +3238,7 @@
       "entryPoint": "@bitforgehq/ui",
       "file": "src/config/labels.ts",
       "summary": "Replaces built-in strings for an app or a sub-tree, such as a translation",
-      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`,\n`fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`, `fileInputRemove`,\n`fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`, `fileInputRemoved`, `fileInputCount`,\n`fileRejectedType`, `fileRejectedSize`, `fileRejectedCount`,\n`imageInputChoose`, `imageInputUpload`, `imageInputReplace`, `imageInputRemove`,\n`chatThread`, `chatJumpToLatest`, `chatMessageStopped`, `chatMessageFailed`, `chatComposer`,\n`chatSend`, `chatStop`, `mediaCardSelect`, `imageLoadFailed`, `validation`); the overlay\nservices (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,\n`sheetPosition`, `dialog`, `notifications`, `imageViewer`, `imageViewerPrevious`,\n`imageViewerNext`, `imageViewerPosition`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
+      "description": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`,\n`fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`, `fileInputRemove`,\n`fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`, `fileInputRemoved`, `fileInputCount`,\n`fileRejectedType`, `fileRejectedSize`, `fileRejectedCount`,\n`imageInputChoose`, `imageInputUpload`, `imageInputReplace`, `imageInputRemove`,\n`chatThread`, `chatJumpToLatest`, `chatMessageStopped`, `chatMessageFailed`, `chatComposer`,\n`chatSend`, `chatStop`, `mediaCardSelect`, `imageLoadFailed`, `imageTileEmpty`,\n`imageTileSelected`, `validation`); the overlay\nservices (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,\n`sheetPosition`, `dialog`, `notifications`, `imageViewer`, `imageViewerPrevious`,\n`imageViewerNext`, `imageViewerPosition`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`.",
       "members": [],
       "methods": [
         {
@@ -3185,7 +3253,7 @@
             }
           ],
           "returns": "Provider",
-          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`,\n`fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`, `fileInputRemove`,\n`fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`, `fileInputRemoved`, `fileInputCount`,\n`fileRejectedType`, `fileRejectedSize`, `fileRejectedCount`,\n`imageInputChoose`, `imageInputUpload`, `imageInputReplace`, `imageInputRemove`,\n`chatThread`, `chatJumpToLatest`, `chatMessageStopped`, `chatMessageFailed`, `chatComposer`,\n`chatSend`, `chatStop`, `mediaCardSelect`, `imageLoadFailed`, `validation`); the overlay\nservices (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,\n`sheetPosition`, `dialog`, `notifications`, `imageViewer`, `imageViewerPrevious`,\n`imageViewerNext`, `imageViewerPosition`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
+          "doc": "Replaces built-in strings, merged over the parent's (validation merged key by key); a key left\nout or set to `undefined` keeps the parent's string. In `ApplicationConfig.providers` it covers\nevery string. In a component's `providers` it covers that sub-tree's widgets and form controls\n(`loading`, `dismiss`, `tabBar`, `tabBadge`, `back`, `refreshing`, `tableSelectAll`, `tableSortBy`,\n`tableSortNone`, `tableSortAscending`, `tableSortDescending`, `theme`, `themeSystem`, `themeLight`, `themeDark`,\n`breadcrumb`, `breadcrumbExpand`, `navigation`, `navBadge`, `sidebarCollapse`, `sidebarExpand`,\n`skipToContent`, `pagination`, `previousPage`, `nextPage`, `pageOf`, `goToPage`, `tabGroup`,\n`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`,\n`statTrendUp`, `statTrendDown`, `statTrendFlat`, `comboboxEmpty`, `comboboxRemove`,\n`dateInputDay`, `dateInputMonth`, `dateInputYear`, `dateInputOpenCalendar`, `dateInputInvalid`,\n`dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,\n`timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,\n`chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,\n`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`,\n`fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`, `fileInputRemove`,\n`fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`, `fileInputRemoved`, `fileInputCount`,\n`fileRejectedType`, `fileRejectedSize`, `fileRejectedCount`,\n`imageInputChoose`, `imageInputUpload`, `imageInputReplace`, `imageInputRemove`,\n`chatThread`, `chatJumpToLatest`, `chatMessageStopped`, `chatMessageFailed`, `chatComposer`,\n`chatSend`, `chatStop`, `mediaCardSelect`, `imageLoadFailed`, `imageTileEmpty`,\n`imageTileSelected`, `validation`); the overlay\nservices (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`,\n`sheetPosition`, `dialog`, `notifications`, `imageViewer`, `imageViewerPrevious`,\n`imageViewerNext`, `imageViewerPosition`) are root singletons and pick it up only when the caller passes its injector:\n`open(…, { injector: inject(Injector) })`."
         }
       ],
       "slots": [],
@@ -10229,6 +10297,107 @@
       "since": "0.5.0",
       "signature": "class BfImageInputHarness extends ComponentHarness"
     },
+    {
+      "name": "BfImageTileHarness",
+      "slug": "bf-image-tile-harness",
+      "kind": "class",
+      "entryPoint": "@bitforgehq/ui/testing",
+      "file": "testing/harnesses/image-tile.harness.ts",
+      "summary": "Test harness for an image tile: its picture state, title, meta, selection and action",
+      "description": "Harness for `bf-image-tile`. jsdom never loads images, so `loadImage()` and `failImage()` fire\nthe picture's `load` and `error` events the way a browser would; `getState()` then tells what\nthe tile shows. `click()` clicks the tile's `bfAction` link or button.",
+      "members": [],
+      "methods": [
+        {
+          "name": "getTitle",
+          "signature": "getTitle(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The tile's title: the text of its default slot."
+        },
+        {
+          "name": "getMeta",
+          "signature": "getMeta(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The meta line under the title."
+        },
+        {
+          "name": "getState",
+          "signature": "getState(): Promise<'empty' | 'loading' | 'loaded' | 'failed'>",
+          "params": [],
+          "returns": "Promise<'empty' | 'loading' | 'loaded' | 'failed'>",
+          "doc": "What the picture area shows: `empty` (the placeholder), `loading` (the skeleton), `loaded`\n(the picture) or `failed` (the failure message)."
+        },
+        {
+          "name": "getSrc",
+          "signature": "getSrc(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The URL of the picture."
+        },
+        {
+          "name": "getAlt",
+          "signature": "getAlt(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The alternative text of the picture."
+        },
+        {
+          "name": "getPlaceholderText",
+          "signature": "getPlaceholderText(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The placeholder text while there is no picture."
+        },
+        {
+          "name": "getFailedMessage",
+          "signature": "getFailedMessage(): Promise<string>",
+          "params": [],
+          "returns": "Promise<string>",
+          "doc": "The failure message."
+        },
+        {
+          "name": "isSelected",
+          "signature": "isSelected(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the tile is marked selected."
+        },
+        {
+          "name": "isClickable",
+          "signature": "isClickable(): Promise<boolean>",
+          "params": [],
+          "returns": "Promise<boolean>",
+          "doc": "Whether the tile is clickable (has a `bfAction` link or button)."
+        },
+        {
+          "name": "click",
+          "signature": "click(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Clicks the tile's `bfAction` link or button. Throws for a tile without one."
+        },
+        {
+          "name": "loadImage",
+          "signature": "loadImage(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Fires the picture's `load` event, as a browser does when it arrives. Throws without one."
+        },
+        {
+          "name": "failImage",
+          "signature": "failImage(): Promise<void>",
+          "params": [],
+          "returns": "Promise<void>",
+          "doc": "Fires the picture's `error` event, as a browser does when it fails. Throws without one."
+        }
+      ],
+      "slots": [],
+      "references": [],
+      "usedBy": [],
+      "since": "0.5.0",
+      "signature": "class BfImageTileHarness extends ComponentHarness"
+    },
     {
       "name": "BfImageViewerHarness",
       "slug": "bf-image-viewer-harness",

package/ai/UI_GUIDE.md

@@ -147,10 +147,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`,
@@ -254,7 +254,7 @@ you can guess a binding without looking it up:
   spinner, tab bar, progress or icon); every component that renders a native input, select or
   textarea (checkbox and toggle included) also takes `ariaLabel` and `ariaLabelledby` for when no
   visible `label` is shown; a built-in sub-control's name is `<part>Label` (`dismissLabel`,
-  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar` and `bf-media-card`.
+  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar`, `bf-media-card` and `bf-image-tile`.
 - Types: every union or object type of an input, model, output, `Bf…Options`/`Bf…Config` property
   or an interface they name is a named type exported from the same entry
   (`BfToggleLabelPosition`, `BfRefresherRefreshEvent`, `BfDialogRole`, …), so type your own state
@@ -416,6 +416,11 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   when it fails; retry with a changed `src`. Never project your own `<img>` for the main picture.
   Clickable like `bf-card` (a `bfAction` in the title); `selectable` with `[(selected)]` and
   `label` for a pick-several grid.
+- **Thumbnail grids:** `bf-image-tile` (`[src]`, `alt`, `aspect`, `captionPlacement="overlay"`
+  for the title on a gradient over the picture), with a `bfAction` link or button in its title
+  heading, `bfSlot="meta"` for a date or count, `bfSlot="badge"` for a `bf-badge` and
+  `[selected]` for the current one. Put tiles straight into a CSS grid: they stretch to the row
+  and keep two title lines, so a row lines up; give every tile a meta line or none.
 - **Rows on a card:** `<bf-list [inset]="false" divided class="-mx-card">`, flush to the card's
   edges with lines between the rows.
 - **Theme switch:** `<bf-theme-switch [(value)]="colorScheme.scheme" />` (or
@@ -427,6 +432,9 @@ protected readonly colorScheme = inject(BfColorSchemeService);
 - **Paging and loading:** `<bf-pagination [(page)]="page" [total]="count" [pageSize]="20">` under a
   `bf-table` (the app slices its rows); `bf-skeleton` (`shape` text/rect/circle, `lines`) as the
   placeholder while data loads, inside a region with `aria-busy="true"`.
+- **Stepping through versions:** a compact `bf-pagination` with `[pageCount]`,
+  `[positionLabel]="(page, count) => …"` ("v3 of 7") and `previousLabel`/`nextLabel`; past four
+  options it replaces a `bf-segmented`.
 - **Dates and times:** `<bf-calendar [(value)]="date">` for an inline month view;
   `bf-date-input`, `bf-time-input` and `bf-datetime-input` (`/overlay`) for a field: typed parts
   in locale order plus a calendar or time-list popover (`picker="none"` for typed only, `native`
@@ -1027,7 +1035,7 @@ describe('bf-button in a consumer app (Vitest)', () => {
 
 ### 6. Drive a form widget through its harness
 
-The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfToggleHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfChatComposerHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`. jsdom has no `URL.createObjectURL`, so after `addFile()` `BfImageInputHarness.hasPreview()` stays false: assert on the bound value, or stub `URL.createObjectURL` to read the preview.
+The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfToggleHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfImageTileHarness`, `BfChatComposerHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`. jsdom has no `URL.createObjectURL`, so after `addFile()` `BfImageInputHarness.hasPreview()` stays false: assert on the bound value, or stub `URL.createObjectURL` to read the preview.
 
 `select-harness.spec.ts`:
 
@@ -1097,7 +1105,7 @@ describe('BfSelectHarness in a consumer app (Vitest)', () => {
 
 ### 7. Drive a dialog from the document root
 
-Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`; `BfImageViewerHarness` drives the image viewer the same way. jsdom never loads images: `BfMediaCardHarness` and `BfImageViewerHarness` fire the `load` and `error` events with `loadImage()` and `failImage()`.
+Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`; `BfImageViewerHarness` drives the image viewer the same way. jsdom never loads images: `BfMediaCardHarness`, `BfImageTileHarness` and `BfImageViewerHarness` fire the `load` and `error` events with `loadImage()` and `failImage()`.
 
 `dialog-harness.spec.ts`:
 
@@ -1289,6 +1297,7 @@ notes.
 | `div[bfDescriptionItem]` | `@bitforgehq/ui`        | One label and value pair of a description list, label as term, content as value         |
 | `bf-description-list`    | `@bitforgehq/ui`        | Native description list of label-value pairs, as divided rows or a tile grid            |
 | `bf-donut-chart`         | `@bitforgehq/ui/charts` | Donut chart of the parts of a whole, with a legend, tooltip and centre slot             |
+| `bf-image-tile`          | `@bitforgehq/ui`        | Small card for thumbnail grids: a picture and title that act as one target              |
 | `bf-line-chart`          | `@bitforgehq/ui/charts` | Line chart of series over categories, with tooltip, legend and data table               |
 | `bf-list`                | `@bitforgehq/ui`        | Container for list rows, inset by default with rounded corners on a warm background     |
 | `bf-list-item`           | `@bitforgehq/ui`        | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |

package/ai/components/badge.md

@@ -91,6 +91,37 @@ import { BfBadgeComponent } from '@bitforgehq/ui';
 export class BadgeStrongExampleComponent {}
 ```
 
+## Icon
+
+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.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Box, Check, Clock } from 'lucide';
+
+/** Badges with a leading icon: the icon repeats the meaning, the text still says it. */
+@Component({
+  selector: 'app-example-badge-icon',
+  imports: [BfBadgeComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-2">
+      <bf-badge variant="success"><bf-icon bfSlot="icon-start" [icon]="check" />Reference</bf-badge>
+      <bf-badge variant="info"><bf-icon bfSlot="icon-start" [icon]="box" />3 versions</bf-badge>
+      <bf-badge variant="warning" emphasis="strong"
+        ><bf-icon bfSlot="icon-start" [icon]="clock" />Queued</bf-badge
+      >
+    </div>
+  `,
+})
+export class BadgeIconExampleComponent {
+  protected readonly check = Check;
+  protected readonly box = Box;
+  protected readonly clock = Clock;
+}
+```
+
 ## Count pill
 
 Setting `count` switches to the compact primary pill. Values above 99 render as "99+"; zero renders as "0".
@@ -154,11 +185,12 @@ Consumes tokens by variant, background then text:
 - `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)
 - Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`
 - 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
+- Icon (`icon-start`): drawn in the text colour (`currentColor`), so it follows the variant and stays visible in forced colours
 - 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.
+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.
 
 ## Inputs
 
@@ -171,6 +203,7 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Slots
 
+- `icon-start`: An icon before the text, drawn at 12 px; not shown on a count pill.
 - `default`: The badge text, shown when no `count` is set.
 
 ## Notes
@@ -190,6 +223,13 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Migration notes
 
+### 0.5.0
+
+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.
+
 ### 0.4.0
 
 New `emphasis` input (`BfBadgeEmphasis`: `soft`, the default, or `strong`). `strong` is a solid