@bitforgehq/ui 0.4.0 → 0.5.0-next.4

package/ai/components/image-tile.md

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