@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/ai/components/image-viewer.md

@@ -0,0 +1,309 @@
+# bf-image-viewer
+
+Full-screen image viewer that zooms from a thumbnail and steps through a set
+
+`BfImageViewerComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.5.0
+
+## Example
+
+```ts
+import {
+  Component,
+  ElementRef,
+  Injector,
+  type TemplateRef,
+  inject,
+  signal,
+  viewChild,
+  viewChildren,
+} from '@angular/core';
+import { BfActionDirective, BfButtonComponent, BfMediaCardComponent } from '@bitforgehq/ui';
+import {
+  type BfImageViewerActionsContext,
+  type BfImageViewerImage,
+  BfImageViewerService,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-image-viewer overview.
+ *
+ * Live demo of `BfImageViewerService`: a grid of `bf-media-card` thumbnails opens the viewer on
+ * the clicked one, zooming out of its picture. The arrow keys or the side buttons step through the set, and closing zooms
+ * back into the thumbnail of the image shown. The "Use as cover" action closes the viewer and
+ * keeps the pick.
+ */
+@Component({
+  selector: 'app-example-image-viewer-overview',
+  imports: [BfActionDirective, BfButtonComponent, BfMediaCardComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="grid grid-cols-2 gap-3 @md:grid-cols-5">
+        @for (image of images; track image.src; let i = $index) {
+          <bf-media-card #card aspect="1/1" [src]="image.src" [alt]="image.label">
+            <button bfAction type="button" class="text-label text-start" (click)="open(i)">
+              {{ image.caption ?? 'Untitled' }}
+            </button>
+          </bf-media-card>
+        }
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+
+    <ng-template #actions let-image let-ref="ref">
+      <bf-button variant="primary" size="sm" (clicked)="useAsCover(image); ref.close()">
+        Use as cover
+      </bf-button>
+    </ng-template>
+  `,
+})
+export class ImageViewerOverviewExampleComponent {
+  private readonly viewer = inject(BfImageViewerService);
+  private readonly injector = inject(Injector);
+
+  protected readonly images: readonly BfImageViewerImage[] = [
+    { src: 'media/skyline.svg', label: 'Neon skyline at dusk', caption: 'Starfall, concept 1' },
+    { src: 'media/forest.svg', label: 'Pine forest under a pale sun', caption: 'Rootbound' },
+    { src: 'media/harbour.svg', label: 'Harbour at sunset', caption: 'Tidewalk' },
+    { src: 'media/desert.svg', label: 'Dunes under an orange sun' },
+    { src: 'media/glacier.svg', label: 'Glacier under a small sun', caption: 'Coldlight' },
+  ];
+  protected readonly status = signal('No cover picked.');
+
+  private readonly cards = viewChildren<BfMediaCardComponent, ElementRef<HTMLElement>>('card', {
+    read: ElementRef,
+  });
+  private readonly actions =
+    viewChild.required<TemplateRef<BfImageViewerActionsContext>>('actions');
+
+  protected open(index: number): void {
+    this.viewer.open({
+      images: this.images,
+      index,
+      // Any image's thumbnail, so closing zooms into the one shown.
+      origin: (i) => this.cards()[i]?.nativeElement.querySelector('img'),
+      actions: this.actions(),
+      injector: this.injector,
+    });
+  }
+
+  protected useAsCover(image: BfImageViewerImage): void {
+    this.status.set(`Cover: ${image.label}.`);
+  }
+}
+```
+
+## Overview
+
+The full-screen image viewer (lightbox) `BfImageViewerService.open()` renders: one image large
+over a dark scrim, with a counter, previous and next buttons, a close button, an optional
+caption and actions. It opens with a zoom out of the clicked thumbnail and steps with a
+cross-fade. Apps do not place it in templates; open it with the service.
+
+A full-screen image viewer (a lightbox) from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no Capacitor). `BfImageViewerService.open()` shows one image large over a dark scrim and steps through a set: previous and next buttons, the arrow keys, a counter ("2 of 5"), the caption and optional actions. It zooms out of the thumbnail that was clicked and back into it, and returns a `BfImageViewerRef`.
+
+## When to use
+
+Use `BfImageViewerService` to look at a picture larger than the page shows it, such as a card's cover, a gallery or the results of an image generator, and to step through a set of them. Use [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) instead for a picture that comes with a form or a decision, and [bf-media-card](https://bitforge-ui.web.app/components/media-card) for the thumbnails themselves.
+
+## Basic usage
+
+Call `open()` with the `images` (each a `src`, a `label`, which becomes the image's `alt`, and an optional `caption`) and the `index` to show first. Pass the clicked thumbnail as `origin`, or a function that returns the thumbnail of any image (`(index) => thumbnails[index]`), so closing after a few steps zooms into the right one. Actions under the image (a download link, a "Use this one" button) come from an `actions` template, whose context is `{ $implicit: image, index, ref }`; inject `BfImageViewerRef` or use `ref` to close or step from it.
+
+```ts
+import {
+  Component,
+  ElementRef,
+  Injector,
+  type TemplateRef,
+  inject,
+  signal,
+  viewChild,
+  viewChildren,
+} from '@angular/core';
+import { BfActionDirective, BfButtonComponent, BfMediaCardComponent } from '@bitforgehq/ui';
+import {
+  type BfImageViewerActionsContext,
+  type BfImageViewerImage,
+  BfImageViewerService,
+} from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-image-viewer overview.
+ *
+ * Live demo of `BfImageViewerService`: a grid of `bf-media-card` thumbnails opens the viewer on
+ * the clicked one, zooming out of its picture. The arrow keys or the side buttons step through the set, and closing zooms
+ * back into the thumbnail of the image shown. The "Use as cover" action closes the viewer and
+ * keeps the pick.
+ */
+@Component({
+  selector: 'app-example-image-viewer-overview',
+  imports: [BfActionDirective, BfButtonComponent, BfMediaCardComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="grid grid-cols-2 gap-3 @md:grid-cols-5">
+        @for (image of images; track image.src; let i = $index) {
+          <bf-media-card #card aspect="1/1" [src]="image.src" [alt]="image.label">
+            <button bfAction type="button" class="text-label text-start" (click)="open(i)">
+              {{ image.caption ?? 'Untitled' }}
+            </button>
+          </bf-media-card>
+        }
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+
+    <ng-template #actions let-image let-ref="ref">
+      <bf-button variant="primary" size="sm" (clicked)="useAsCover(image); ref.close()">
+        Use as cover
+      </bf-button>
+    </ng-template>
+  `,
+})
+export class ImageViewerOverviewExampleComponent {
+  private readonly viewer = inject(BfImageViewerService);
+  private readonly injector = inject(Injector);
+
+  protected readonly images: readonly BfImageViewerImage[] = [
+    { src: 'media/skyline.svg', label: 'Neon skyline at dusk', caption: 'Starfall, concept 1' },
+    { src: 'media/forest.svg', label: 'Pine forest under a pale sun', caption: 'Rootbound' },
+    { src: 'media/harbour.svg', label: 'Harbour at sunset', caption: 'Tidewalk' },
+    { src: 'media/desert.svg', label: 'Dunes under an orange sun' },
+    { src: 'media/glacier.svg', label: 'Glacier under a small sun', caption: 'Coldlight' },
+  ];
+  protected readonly status = signal('No cover picked.');
+
+  private readonly cards = viewChildren<BfMediaCardComponent, ElementRef<HTMLElement>>('card', {
+    read: ElementRef,
+  });
+  private readonly actions =
+    viewChild.required<TemplateRef<BfImageViewerActionsContext>>('actions');
+
+  protected open(index: number): void {
+    this.viewer.open({
+      images: this.images,
+      index,
+      // Any image's thumbnail, so closing zooms into the one shown.
+      origin: (i) => this.cards()[i]?.nativeElement.querySelector('img'),
+      actions: this.actions(),
+      injector: this.injector,
+    });
+  }
+
+  protected useAsCover(image: BfImageViewerImage): void {
+    this.status.set(`Cover: ${image.label}.`);
+  }
+}
+```
+
+## Stepping and the ref
+
+The ref's `index` is a signal of the shown image. `next()` and `previous()` wrap around at both ends, `goTo(index)` jumps (a negative index counts from the end), and `close()` closes; `afterClosed` resolves once the viewer has left the page, and `closed()` turns true. A viewer of one image shows no counter and no step buttons.
+
+```ts
+import { Component, Injector, inject, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfImageViewerService } from '@bitforgehq/ui/overlay';
+
+/**
+ * One image, no thumbnail.
+ *
+ * Without an `origin` the viewer fades in and out; with a single image it shows no counter and
+ * no step buttons. `afterClosed` resolves once it has gone.
+ */
+@Component({
+  selector: 'app-example-image-viewer-single',
+  imports: [BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-button variant="tonal" (clicked)="open()">View the key art</bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ImageViewerSingleExampleComponent {
+  private readonly viewer = inject(BfImageViewerService);
+  private readonly injector = inject(Injector);
+  protected readonly status = signal('');
+
+  protected async open(): Promise<void> {
+    const ref = this.viewer.open({
+      images: [
+        { src: 'media/glacier.svg', label: 'Glacier under a small sun', caption: 'Key art' },
+      ],
+      injector: this.injector,
+    });
+    this.status.set('Viewer open.');
+    await ref.afterClosed;
+    this.status.set('Viewer closed.');
+  }
+}
+```
+
+## Motion
+
+The viewer opens with a zoom: the image's frame starts on the thumbnail's box, cropped as the thumbnail crops it, and grows to its place in 260 ms on the overlay curve (`--ease-ios`), while the scrim and the controls fade in. With no `origin`, or one that is off screen, it fades in instead. Closing zooms back into the thumbnail of the shown image when it is still on screen, else fades out. Stepping cross-fades the images. Under `prefers-reduced-motion` the viewer only fades, in 150 ms, and the images appear without a fade.
+
+## Loading and failing
+
+While a large image loads, the viewer shows its thumbnail (the `origin` image, when there is one) with a spinner over it, and the frame already has the thumbnail's aspect ratio; the image fades in over it when it arrives (`bfFadeIn`). An image that fails to load shows the `imageLoadFailed` label ("The image could not be loaded") in its place.
+
+## Desktop
+
+Built for desktop and touch alike: the image fills the space between the top bar (counter and close) and the caption row, at its own aspect ratio. The previous and next buttons sit on the image's sides and the close button at the top end, each a `tonal` `bf-icon-button` that follows `provideBfDefaults()`; their hover tint and focus ring are the button's. A click on the scrim or beside the image closes the viewer; a click on the image, the caption or the actions does not. The page behind it is inert and does not scroll.
+
+## Theming
+
+- The viewer is a `.dark` sub-tree, so its text and buttons take their dark-mode tokens in both colour schemes; the scrim is `bg-scrim/90`.
+- Counter `text-label`, caption `text-body`, failure message `text-body text-text-secondary`.
+- Buttons: `tonal` `bf-icon-button`s with lucide `ChevronLeft`, `ChevronRight` (mirrored under `dir="rtl"`) and `X`; the spinner is a `lg` `bf-spinner`.
+- Motion: `OVERLAY_DURATION` (260 ms) and `OVERLAY_EASING` from the overlay core, `OVERLAY_REDUCED_DURATION` (150 ms) under reduced motion; the images fade on `duration-slow`.
+
+## Accessibility
+
+The viewer is a modal `role="dialog"` named by `ariaLabel` or the `imageViewer` label ("Image viewer"), with `aria-modal="true"`. On open, focus moves to the close button and is trapped in the viewer; on close it returns to the element that opened it. The page behind it is `inert`. Every image has its `label` as `alt`, the step buttons are named by `imageViewerPrevious` and `imageViewerNext`, and after each step a polite live region announces the position and the label ("3 of 5, Harbour at sunset"); the counter itself is the `imageViewerPosition` label. The service is a root singleton: pass `injector: inject(Injector)` so a feature-level `provideBfLabels()` names its parts.
+
+### Keyboard
+
+| Key                                              | Action                                                      |
+| ------------------------------------------------ | ----------------------------------------------------------- |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd>     | Next / previous image, wrapping (swapped under `dir="rtl"`) |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | First / last image                                          |
+| <kbd>Escape</kbd>                                | Closes the viewer                                           |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Next / previous control, wrapping inside the viewer         |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Activates the focused button                                |
+
+## Notes
+
+### Do
+
+- Give every image a `label` that says what it shows; it is all a screen reader gets of the picture.
+- Pass `origin` (a function for a gallery), so the image visibly comes from and returns to its thumbnail.
+- Keep actions to one or two buttons that act on the shown image.
+
+### Don't
+
+- Don't open the viewer for a picture that already fills the page.
+- Don't put a form in the actions; open a dialog for that.
+
+## Migration notes
+
+### 0.5.0
+
+New: `BfImageViewerService` in `@bitforgehq/ui/overlay`, a full-screen image viewer (lightbox).
+`open({ images: [{ src, label, caption? }], index?, origin?, actions?, ariaLabel?,
+closeOnNavigation?, injector? })` (new types `BfImageViewerOptions`, `BfImageViewerImage`,
+`BfImageViewerOrigin`, `BfImageViewerActionsContext`) renders `bf-image-viewer` over a dark scrim
+and returns a `BfImageViewerRef` (`index()`, `next()`, `previous()`, `goTo()`, `close()`,
+`afterClosed`, `closed()`). Previous and next buttons, the arrow keys (mirrored under rtl), Home
+and End step through the set, wrapping at both ends; a counter shows "2 of 5" and a polite live
+region announces each step. It is a modal dialog: focus moves to its close button and is trapped,
+`Escape`, the close button and a click on the scrim close it, the page behind is `inert`, and
+focus returns to the opener. The `actions` template (context `{ $implicit: image, index, ref }`)
+sits beside the caption. It zooms out of `origin` (the clicked thumbnail, or a function returning
+any image's thumbnail) with a 260 ms FLIP on the overlay curve and zooms back into it on close
+when it is on screen, else fades; images cross-fade on a step; reduced motion only fades. While a
+large image loads it shows the thumbnail and a spinner, then fades the image in. New labels
+`imageViewer`, `imageViewerPrevious`, `imageViewerNext` and `imageViewerPosition`.
+`@bitforgehq/ui/testing`: new `BfImageViewerHarness` (`getIndex()`, `getCount()`,
+`getCounterText()`, `getSrc()`, `getAlt()`, `getCaption()`, `next()`, `previous()`,
+`pressKey()`, `close()`, `loadImage()`, `failImage()`, `isLoaded()`, `hasFailed()`).

package/ai/components/list-item.md

@@ -100,6 +100,7 @@ export class ListItemOverviewExampleComponent {
 One row of a list: leading slot (avatar, icon tile), title and subtitle, trailing slot
 (time, toggle, badge) and an optional chevron for rows that navigate. A navigation row puts a
 `bfAction` link in the `title` slot, so the row stays a list item and the link covers it.
+`unread` marks a row not yet opened with a dot and a bolder title.
 
 A row of a list: a leading slot (an avatar, an icon), the title and subtitle, a trailing slot (a time, a toggle, a chip) and an optional chevron. Place rows in a [`bf-list`](https://bitforge-ui.web.app/components/list), which gives them the list semantics and the inset container; a row can also stand alone. A row is static text, a navigation link or an action button, never more than one of them.
 
@@ -230,6 +231,87 @@ export class ListItemActionsExampleComponent {
 }
 ```
 
+## Unread rows
+
+`unread` marks a row the user has not opened yet, such as a new message or notification: a small `primary` dot at the row's inline start, on the title line, and the title in a bolder weight. It is not colour alone: the row also reads a visually hidden state before the title, from the `listItemUnread` label ("Unread"; set it with `provideBfLabels({ listItemUnread: 'Ungelesen' })` in a German app), so a screen reader says "Unread, Scan finished". The dot sits in the row's own inline-start padding (or the gap after a leading avatar or icon), so read and unread rows keep their text aligned and nothing moves when a row is marked read; without `unread` nothing changes. Clear `unread` when the row is opened.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfActionDirective, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+interface Notice {
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle: string;
+  readonly time: string;
+  readonly unread: boolean;
+}
+
+/**
+ * An inbox with unread rows.
+ *
+ * Each title is a stretched `<button bfAction>`; opening a row marks it read.
+ */
+@Component({
+  selector: 'app-example-list-item-unread',
+  imports: [BfActionDirective, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      @for (notice of notices(); track notice.id) {
+        <bf-list-item [unread]="notice.unread" [subtitle]="notice.subtitle">
+          <button bfSlot="title" bfAction type="button" class="text-start" (click)="open(notice)">
+            {{ notice.title }}
+          </button>
+          <span bfSlot="trailing" class="text-caption text-text-muted">{{ notice.time }}</span>
+        </bf-list-item>
+      }
+    </bf-list>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+  `,
+})
+export class ListItemUnreadExampleComponent {
+  protected readonly notices = signal<readonly Notice[]>([
+    {
+      id: 'scan',
+      title: 'Scan finished',
+      subtitle: '3 new findings on api.example.com',
+      time: '9:41',
+      unread: true,
+    },
+    {
+      id: 'cert',
+      title: 'Certificate expires soon',
+      subtitle: 'shop.example.com, in 12 days',
+      time: '8:15',
+      unread: true,
+    },
+    {
+      id: 'report',
+      title: 'Weekly report',
+      subtitle: 'Ready to download',
+      time: 'Mon',
+      unread: false,
+    },
+  ]);
+  private readonly opened = signal('');
+
+  protected readonly status = computed(() => {
+    const unread = this.notices().filter((notice) => notice.unread).length;
+    const opened = this.opened();
+    return opened ? `${unread} unread · Opened: ${opened}` : `${unread} unread`;
+  });
+
+  protected open(notice: Notice): void {
+    this.opened.set(notice.title);
+    this.notices.update((list) =>
+      list.map((item) => (item.id === notice.id ? { ...item, unread: false } : item)),
+    );
+  }
+}
+```
+
+With a `bfAction` link or button in the `title` slot, the state becomes part of that element's accessible name: the directive sets `aria-labelledby` to the state text and the element itself (it gives the element an id if it has none, and keeps an `aria-labelledby` of its own after the state), so the link reads "Unread, Scan finished" when tabbed to or listed, and the state text is hidden from the tree so it is read once. An `interactive` row holds the state text inside its button, so its name starts with it too.
+
 ## Desktop
 
 An `interactive` row and a row holding a `bfAction` link take a `surface-muted` fill and the pointer cursor while hovered; a static row has none. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring is drawn around the row on keyboard focus only. A navigation row keeps the browser's link behaviour: Ctrl/Cmd-click and a middle click open it in a new tab. The trailing slot sits above the stretched link, so a toggle or button there takes its own click. Rows have one height; they do not follow `provideBfDefaults()`.
@@ -240,10 +322,11 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 - Text: the title, the title slot and the subtitle wrap (`wrap-anywhere`); with `truncate` each keeps one line (`truncate`).
 - `interactive` rows and rows holding a `bfAction` link add a pointer, a `surface-muted` hover, a `surface-pressed` fill while pressed (the row's action, for a `bfAction` row) and a `ring` focus ring; `interactive` rows dim to `text-disabled` when `disabled` and have no pressed state then.
 - The `chevron` mark uses `text-subtle`.
+- `unread`: the dot is `primary` (`CanvasText` in forced colours), `rounded-full` and 8 px (`size-2`); the title turns `font-extrabold`.
 
 ## Accessibility
 
-`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree.
+`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree. An `unread` row's dot carries a visually hidden (`sr-only`) state text from the `listItemUnread` label, read before the title ("Unread, Scan finished"); on a row with a `bfAction` the text is `aria-hidden` and the action names itself with `aria-labelledby` from it and its own content, so the state is part of the link's or button's name and is read once. The row stays a `listitem`.
 
 ### Keyboard
 
@@ -255,14 +338,15 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 
 ## Inputs
 
-| Name          | Type      | Default | Description                                                                                                                                           |
-| ------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title`       | `string`  | `''`    | Primary text. For a navigation row, project an `<a bfSlot="title" bfAction>` instead.                                                                 |
-| `subtitle`    | `string`  | `''`    | Secondary text under the title.                                                                                                                       |
-| `interactive` | `boolean` | `false` | Render the row as a button that emits `clicked` (an action row; a row that navigates puts a `bfAction` link in the `title` slot instead).             |
-| `chevron`     | `boolean` | `false` | Show a trailing chevron (navigation rows).                                                                                                            |
-| `disabled`    | `boolean` | `false` | Disable an interactive row.                                                                                                                           |
-| `truncate`    | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes. |
+| Name          | Type      | Default | Description                                                                                                                                               |
+| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`  | `''`    | Primary text. For a navigation row, project an `<a bfSlot="title" bfAction>` instead.                                                                     |
+| `subtitle`    | `string`  | `''`    | Secondary text under the title.                                                                                                                           |
+| `interactive` | `boolean` | `false` | Render the row as a button that emits `clicked` (an action row; a row that navigates puts a `bfAction` link in the `title` slot instead).                 |
+| `chevron`     | `boolean` | `false` | Show a trailing chevron (navigation rows).                                                                                                                |
+| `disabled`    | `boolean` | `false` | Disable an interactive row.                                                                                                                               |
+| `truncate`    | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes.     |
+| `unread`      | `boolean` | `false` | Mark the row as not yet opened: a dot at the inline start, a bolder title and a visually hidden state (the `listItemUnread` label) read before the title. |
 
 ## Outputs
 
@@ -283,14 +367,26 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 
 - Keep titles short; a long one wraps. Add `truncate` only where one line per row is the pattern (a mail list).
 - Make a row that navigates a `bfAction` link in the `title` slot, and a row that acts on the page `interactive`; put secondary actions in the trailing slot.
+- Set `unread` on rows not yet opened (messages, notifications) and clear it when the row is opened.
 
 ### Don't
 
 - Don't nest interactive controls inside an `interactive` row (it is one button); use a navigation row with a trailing control instead.
 - Don't wrap a `bf-list-item` in an `<a>`, and don't navigate from an `interactive` row's `(clicked)`.
+- Don't mark unread rows with a coloured title or a badge of your own; `unread` gives the dot, the weight and the screen-reader state together.
 
 ## Migration notes
 
+### 0.4.0
+
+New `unread` input (boolean, default false) for a row not yet opened: a `primary` dot at the
+row's inline start on the title line, a bolder title (`font-extrabold`) and a visually hidden
+state read before the title, from the new label key `listItemUnread` ("Unread"). A row's
+`bfAction` link or button then names itself `aria-labelledby="<state> <itself>"` ("Unread,
+Report"; an id is added if it has none, and its own `aria-labelledby` is kept after the state).
+The dot sits in the row's own inline-start padding, so read and unread rows stay aligned. Opt-in: without `unread` nothing
+changes.
+
 ### 0.3.0
 
 **Behaviour:** logical properties: text aligns to the inline start and the chevron sits at the