@bitforgehq/ui 0.4.0 → 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()`).