@bitforgehq/ui 0.4.0 → 0.5.0-next.4

package/ai/reference/bf-image-input-harness.md

@@ -0,0 +1,67 @@
+# BfImageInputHarness
+
+Test harness for the image input: drops an image on it and reads the preview
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-image-input`. `addFile()` drops the image on the tile, so it goes through the
+same `accept` and `maxSize` rules as a real drop; read the outcome with `hasPreview()`,
+`getPreviewSrc()` and `getRejectedMessage()`. jsdom has no `URL.createObjectURL`, so a picked
+image shows no preview there: assert on the bound value, or stub `URL.createObjectURL` to read
+the preview.
+
+```ts
+import { BfImageInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfImageInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the tile's `aria-label`.
+
+### `getErrorText(): Promise<string>`
+
+The error text beside the tile (an explicit message, or the first form error once touched).
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the control is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the control is read-only: its tile is not a button and there are no Upload or Remove
+buttons.
+
+### `hasPreview(): Promise<boolean>`
+
+Whether the tile shows an image, picked or from `src`. A picked image needs
+`URL.createObjectURL`, which jsdom lacks: stub it to see one.
+
+### `getPreviewSrc(): Promise<string | null>`
+
+The `src` of the shown image.
+
+### `addFile(file: File): Promise<void>`
+
+Drops an image on the tile, as a user would. On a disabled or read-only control it does
+nothing, like the UI. It waits on no timer, so it works under fake timers and `fakeAsync`.
+
+| Parameter | Type   | Description        |
+| --------- | ------ | ------------------ |
+| `file`    | `File` | The image to drop. |
+
+### `remove(): Promise<void>`
+
+Presses Remove, which clears the picked and the existing image. Throws while there is no
+image or the control cannot be edited.
+
+### `getRejectedMessage(): Promise<string>`
+
+The reason the last pick was refused, until the next pick or Remove.

package/ai/reference/bf-image-input-shape.md

@@ -0,0 +1,27 @@
+# BfImageInputShape
+
+The two tile shapes of an image picker, a circle or a rounded square
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+The shape of a `bf-image-input` tile: a circle (`round`, for avatars) or a rounded square
+(`square`, for logos and covers).
+
+```ts
+import { type BfImageInputShape } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfImageInputShape = 'round' | 'square'
+```
+
+## Values
+
+- `round`
+- `square`
+
+## Used by
+
+- [bf-image-input](../components/image-input.md)

package/ai/reference/bf-image-tile-aspect.md

@@ -0,0 +1,28 @@
+# BfImageTileAspect
+
+The four aspect ratios of an image tile's picture, square by default
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+The aspect ratio of a `bf-image-tile`'s picture: square (default), 4:3, 16:9 or 3:4.
+
+```ts
+import { type BfImageTileAspect } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfImageTileAspect = '1/1' | '4/3' | '16/9' | '3/4'
+```
+
+## Values
+
+- `1/1`
+- `4/3`
+- `16/9`
+- `3/4`
+
+## Used by
+
+- [bf-image-tile](../components/image-tile.md)

package/ai/reference/bf-image-tile-caption-placement.md

@@ -0,0 +1,27 @@
+# BfImageTileCaptionPlacement
+
+Where an image tile's caption sits, below the picture or over it
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+Where a `bf-image-tile`'s title and meta line sit: `below` the picture (default), or `overlay`,
+on a soft gradient over the bottom of the picture.
+
+```ts
+import { type BfImageTileCaptionPlacement } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfImageTileCaptionPlacement = 'below' | 'overlay'
+```
+
+## Values
+
+- `below`
+- `overlay`
+
+## Used by
+
+- [bf-image-tile](../components/image-tile.md)

package/ai/reference/bf-image-tile-harness.md

@@ -0,0 +1,70 @@
+# BfImageTileHarness
+
+Test harness for an image tile: its picture state, title, meta, selection and action
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-image-tile`. jsdom never loads images, so `loadImage()` and `failImage()` fire
+the picture's `load` and `error` events the way a browser would; `getState()` then tells what
+the tile shows. `click()` clicks the tile's `bfAction` link or button.
+
+```ts
+import { BfImageTileHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfImageTileHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getTitle(): Promise<string>`
+
+The tile's title: the text of its default slot.
+
+### `getMeta(): Promise<string>`
+
+The meta line under the title.
+
+### `getState(): Promise<'empty' | 'loading' | 'loaded' | 'failed'>`
+
+What the picture area shows: `empty` (the placeholder), `loading` (the skeleton), `loaded`
+(the picture) or `failed` (the failure message).
+
+### `getSrc(): Promise<string>`
+
+The URL of the picture.
+
+### `getAlt(): Promise<string>`
+
+The alternative text of the picture.
+
+### `getPlaceholderText(): Promise<string>`
+
+The placeholder text while there is no picture.
+
+### `getFailedMessage(): Promise<string>`
+
+The failure message.
+
+### `isSelected(): Promise<boolean>`
+
+Whether the tile is marked selected.
+
+### `isClickable(): Promise<boolean>`
+
+Whether the tile is clickable (has a `bfAction` link or button).
+
+### `click(): Promise<void>`
+
+Clicks the tile's `bfAction` link or button. Throws for a tile without one.
+
+### `loadImage(): Promise<void>`
+
+Fires the picture's `load` event, as a browser does when it arrives. Throws without one.
+
+### `failImage(): Promise<void>`
+
+Fires the picture's `error` event, as a browser does when it fails. Throws without one.

package/ai/reference/bf-image-viewer-actions-context.md

@@ -0,0 +1,29 @@
+# BfImageViewerActionsContext
+
+What the viewer's actions template receives: the shown image, its index and the ref
+
+Interface from `@bitforgehq/ui/overlay` · since 0.5.0
+
+Context of the `actions` template of `BfImageViewerService.open()`: `let-image`,
+`let-index="index"` and `let-ref="ref"`.
+
+```ts
+import { type BfImageViewerActionsContext } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name        | Type                 | Default  | Description                                              |
+| ----------- | -------------------- | -------- | -------------------------------------------------------- |
+| `$implicit` | `BfImageViewerImage` | required | The image the viewer shows (`let-image`).                |
+| `index`     | `number`             | required | Its 0-based index in the set (`let-index="index"`).      |
+| `ref`       | `BfImageViewerRef`   | required | The viewer's ref (`let-ref="ref"`), to close it or step. |
+
+## Uses
+
+- [BfImageViewerImage](bf-image-viewer-image.md)
+- [BfImageViewerRef](bf-image-viewer-ref.md)
+
+## Used by
+
+- [BfImageViewerOptions](bf-image-viewer-options.md)

package/ai/reference/bf-image-viewer-harness.md

@@ -0,0 +1,87 @@
+# BfImageViewerHarness
+
+Test harness for an image viewer: its image, index, caption, steps and close
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-image-viewer`, the lightbox `BfImageViewerService.open()` renders. It renders
+in the CDK overlay container outside the tested component, so get it through
+`TestbedHarnessEnvironment.documentRootLoader(fixture)`. jsdom never loads images: call
+`loadImage()` to fire the shown image's `load` event.
+
+```ts
+import { BfImageViewerHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfImageViewerHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The viewer's accessible name (`ariaLabel`, else the `imageViewer` label).
+
+### `getIndex(): Promise<number>`
+
+The 0-based index of the shown image.
+
+### `getCount(): Promise<number>`
+
+How many images the viewer steps through.
+
+### `getCounterText(): Promise<string>`
+
+The counter's text ("2 of 5"); a viewer of one image shows none.
+
+### `getSrc(): Promise<string>`
+
+The URL of the shown image.
+
+### `getAlt(): Promise<string>`
+
+The alternative text of the shown image.
+
+### `getCaption(): Promise<string>`
+
+The caption under the shown image.
+
+### `isLoaded(): Promise<boolean>`
+
+Whether the shown image has loaded (no spinner and no failure message).
+
+### `hasFailed(): Promise<boolean>`
+
+Whether the shown image failed to load (the failure message shows).
+
+### `loadImage(): Promise<void>`
+
+Fires the shown image's `load` event, as a browser does when it arrives.
+
+### `failImage(): Promise<void>`
+
+Fires the shown image's `error` event, as a browser does when it fails.
+
+### `next(): Promise<void>`
+
+Clicks the next button. Throws for a viewer of one image (it has none).
+
+### `previous(): Promise<void>`
+
+Clicks the previous button. Throws for a viewer of one image (it has none).
+
+### `pressKey(key: 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'Escape'): Promise<void>`
+
+Presses a key inside the viewer: ArrowLeft and ArrowRight step, Home and End jump, Escape
+closes.
+
+| Parameter | Type                                                         | Description       |
+| --------- | ------------------------------------------------------------ | ----------------- |
+| `key`     | `'ArrowLeft' \| 'ArrowRight' \| 'Home' \| 'End' \| 'Escape'` | The key to press. |
+
+### `close(): Promise<void>`
+
+Clicks the close button.

package/ai/reference/bf-image-viewer-image.md

@@ -0,0 +1,25 @@
+# BfImageViewerImage
+
+One image the viewer shows: its URL, its name as alternative text and a caption
+
+Interface from `@bitforgehq/ui/overlay` · since 0.5.0
+
+One image of a `BfImageViewerService.open()` set.
+
+```ts
+import { type BfImageViewerImage } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name      | Type     | Default  | Description                                                                                                                                            |
+| --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `src`     | `string` | required | URL of the full-size image.                                                                                                                            |
+| `label`   | `string` | required | The image's name: its alternative text (`alt`), read when it shows and announced after a step (required: the viewer shows nothing else that names it). |
+| `caption` | `string` |          | Text shown under the image; none shows no caption.                                                                                                     |
+
+## Used by
+
+- [BfImageViewerActionsContext](bf-image-viewer-actions-context.md)
+- [BfImageViewerOptions](bf-image-viewer-options.md)
+- [BfImageViewerRef](bf-image-viewer-ref.md)

package/ai/reference/bf-image-viewer-options.md

@@ -0,0 +1,33 @@
+# BfImageViewerOptions
+
+Options of an image viewer: its images, the first one, its thumbnail and actions
+
+Interface from `@bitforgehq/ui/overlay` · since 0.5.0
+
+Options of `BfImageViewerService.open()`.
+
+```ts
+import { type BfImageViewerOptions } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name                | Type                                                                                         | Default  | Description                                                                                                                                                                           |
+| ------------------- | -------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `images`            | `readonly BfImageViewerImage[]`                                                              | required | The images to step through, in order; at least one.                                                                                                                                   |
+| `index`             | `number`                                                                                     | `0`      | Index of the image shown first, wrapped into the set.                                                                                                                                 |
+| `origin`            | `BfImageViewerOrigin` (`HTMLElement \| (index: number) => HTMLElement \| null \| undefined`) |          | The thumbnail the viewer zooms out of and back into (or a function returning the thumbnail of an image by index); none fades the viewer in and out.                                   |
+| `actions`           | `TemplateRef<BfImageViewerActionsContext>`                                                   |          | Actions under the image, beside its caption (a download link, a "Use this one" button); its context is `{ $implicit: image, index, ref }`.                                            |
+| `ariaLabel`         | `string`                                                                                     |          | Accessible name of the viewer; empty uses `provideBfLabels()`'s `imageViewer`.                                                                                                        |
+| `closeOnNavigation` | `boolean`                                                                                    | `true`   | A navigation to another URL path closes the viewer (default true).                                                                                                                    |
+| `injector`          | `Injector`                                                                                   |          | Parent of the viewer's injector and source of its labels (default the root injector). Pass the opener's `inject(Injector)` so a feature-level `provideBfLabels()` reaches the viewer. |
+
+## Uses
+
+- [BfImageViewerActionsContext](bf-image-viewer-actions-context.md)
+- [BfImageViewerImage](bf-image-viewer-image.md)
+- [BfImageViewerOrigin](bf-image-viewer-origin.md)
+
+## Used by
+
+- [BfImageViewerService](bf-image-viewer-service.md)

package/ai/reference/bf-image-viewer-origin.md

@@ -0,0 +1,23 @@
+# BfImageViewerOrigin
+
+The thumbnail an image viewer zooms from and back into, or a lookup per image
+
+Type from `@bitforgehq/ui/overlay` · since 0.5.0
+
+Where the viewer zooms from and back to: the thumbnail that was clicked, or a function that
+returns the thumbnail of any image of the set (so closing after stepping zooms into the right
+one), `null` for none.
+
+```ts
+import { type BfImageViewerOrigin } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfImageViewerOrigin = HTMLElement | ((index: number) => HTMLElement | null | undefined) | null
+```
+
+## Used by
+
+- [BfImageViewerOptions](bf-image-viewer-options.md)

package/ai/reference/bf-image-viewer-ref.md

@@ -0,0 +1,55 @@
+# BfImageViewerRef
+
+Handle on an open image viewer that steps through its images and closes it
+
+Class from `@bitforgehq/ui/overlay` · since 0.5.0
+
+Handle to an open image viewer, returned by `BfImageViewerService.open()` and injectable in
+its actions template (`inject(BfImageViewerRef)`). `index` is the shown image; `next()`,
+`previous()` and `goTo()` step through the set (wrapping at both ends), `close()` plays the
+exit motion and resolves `afterClosed`.
+
+```ts
+import { BfImageViewerRef } from '@bitforgehq/ui/overlay';
+```
+
+## Properties
+
+| Name          | Type                            | Default | Description                                             |
+| ------------- | ------------------------------- | ------- | ------------------------------------------------------- |
+| `id`          | `string`                        |         | Unique id of the viewer (its overlay's `bf-overlay-N`). |
+| `images`      | `readonly BfImageViewerImage[]` |         | The images of the set, in order.                        |
+| `afterClosed` | `Promise<void>`                 |         | Resolves once the viewer has closed and left the page.  |
+| `closed`      | `Signal<boolean>`               |         | True once the viewer has been detached.                 |
+| `index`       | `Signal<number>`                |         | Index (0-based) of the image the viewer shows.          |
+
+## Methods
+
+### `next(): void`
+
+Shows the next image; after the last one, the first.
+
+### `previous(): void`
+
+Shows the previous image; before the first one, the last.
+
+### `goTo(index: number): void`
+
+Shows the image at `index`, wrapped into the set (`-1` is the last one).
+
+| Parameter | Type     | Description                             |
+| --------- | -------- | --------------------------------------- |
+| `index`   | `number` | The 0-based index of the image to show. |
+
+### `close(): void`
+
+Closes the viewer: it zooms back into its thumbnail, or fades out. Ignored once closing.
+
+## Uses
+
+- [BfImageViewerImage](bf-image-viewer-image.md)
+
+## Used by
+
+- [BfImageViewerActionsContext](bf-image-viewer-actions-context.md)
+- [BfImageViewerService](bf-image-viewer-service.md)

package/ai/reference/bf-image-viewer-service.md

@@ -0,0 +1,32 @@
+# BfImageViewerService
+
+Opens a full-screen image viewer that zooms from a thumbnail and steps through a set
+
+Service from `@bitforgehq/ui/overlay` · since 0.5.0
+
+Opens a full-screen image viewer (a lightbox) on the overlay core: one image large over a dark
+scrim, previous and next buttons, the arrow keys, Home and End to step through the set
+(wrapping at both ends), a counter, the caption and optional actions. It zooms out of the
+clicked thumbnail (`origin`) and back into it, cross-fades between images, and fades when there
+is no thumbnail on screen; reduced motion only fades. 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 it is `inert` and does not scroll, and focus returns to the opener.
+
+```ts
+import { BfImageViewerService } from '@bitforgehq/ui/overlay';
+```
+
+## Methods
+
+### `open(options: BfImageViewerOptions): BfImageViewerRef`
+
+Opens the viewer on `options.images`, showing `options.index` first.
+
+| Parameter | Type                   | Description                                                               |
+| --------- | ---------------------- | ------------------------------------------------------------------------- |
+| `options` | `BfImageViewerOptions` | The images, the first index, the thumbnail, the actions and the injector. |
+
+## Uses
+
+- [BfImageViewerOptions](bf-image-viewer-options.md)
+- [BfImageViewerRef](bf-image-viewer-ref.md)