@bitforgehq/ui 0.4.0 → 0.5.0-next.3

package/ai/components/tab-group.md

@@ -148,6 +148,8 @@ export class TabGroupLazyExampleComponent {
 
 `[(selected)]` holds the shown panel's `value`; `(changed)` emits the new value after a user change, never for a write of `selected`. While `selected` matches no panel (unset, or a value that went away), the first enabled panel shows; `selected` itself keeps its value until the user picks a tab.
 
+The underline slides to the newly selected tab, changing width as it goes (200 ms, `--bf-duration-layout`); it lands in place at once on the first render and after a resize, and always under `prefers-reduced-motion`. The panel a user switches to fades in over 200 ms (`animate-panel-in`); the first panel shown, and every panel under reduced motion, appears at once.
+
 ## Sizes and width
 
 `size` sets the tabs' height: `sm` 32 px, `md` 40 px, `lg` 48 px. Unset, it follows `provideBfDefaults()`'s `controlSize`, `md` by default. `fitted` stretches the tabs to share the group's width (two or three tabs on a phone). When the tabs do not fit, the row scrolls sideways; focusing a tab with the keyboard scrolls it into view.
@@ -159,7 +161,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 ## Theming
 
 - Tabs: `text-muted` at rest, hover `surface-muted` with `text`, pressed `surface-pressed`; top corners `rounded-tile`.
-- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab).
+- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab). It slides over `--bf-duration-layout` with the `ease-md` curve.
 - Disabled tab: `text-disabled` (never opacity).
 - The row: a 1 px `border` line under the tabs, across the group's width.
 - Badge: `primary` with `on-primary` text, `rounded-control`, `text-micro`.
@@ -168,7 +170,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 
 ## Accessibility
 
-The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
+The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. The sliding underline is one decorative `aria-hidden` element of the row. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
 
 ### Keyboard
 
@@ -213,6 +215,20 @@ The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabG
 
 ## Migration notes
 
+### 0.5.0
+
+The selected tab's underline is now one indicator element of the row that slides to the newly
+selected tab, changing width as it goes (`--bf-duration-layout`, `ease-md`). The first placement
+and a resize land at once, and so does everything under `prefers-reduced-motion`. It is measured
+from the selected tab's inline-start offset, so it mirrors under `dir="rtl"`, and is re-measured
+on resize and when labels, badges, size or `fitted` change. Until it has been measured (jsdom,
+server render, a hidden group) the tab keeps drawing its own underline, so unit tests and the
+first paint are unchanged. The indicator is `aria-hidden`; roles, keyboard and focus are
+unchanged.
+
+The panel a user switches to fades in (200 ms of opacity, new `--animate-panel-in`, behind
+`motion-safe:`); the panel shown on the first render never does.
+
 ### 0.3.1
 
 New `bf-tab-group`: in-page tabs over the content they switch, in both shells. A `tablist` of

package/ai/components/table.md

@@ -489,11 +489,12 @@ export class TablePagedExampleComponent {
 
 `stack` lets the table itself fit a narrow space. With `stack="narrow"` it stacks while the table is narrower than 36rem (576 px at the default root size, Tailwind's `xl` container size): a container query on the table's own width, so a table in a narrow column or a side panel stacks even on a wide screen. The host is then a size container (`container-type: inline-size`), so give the table its width from its parent (a block or `w-full` / `flex-1`), not from its columns. With `stack="coarse"` it stacks under a coarse pointer at any width (phones, tablets, the Capacitor shell). The default `never` keeps the table as it is.
 
-Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`.
+Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. The Sort by select is a native `<select>` unless the app adds `provideBfSelect()` from `@bitforgehq/ui/overlay` to its providers: then it is the styled [bf-select](https://bitforge-ui.web.app/components/select) (still native under touch), through the `BF_TABLE_SORT_SELECT` token, so `@bitforgehq/ui` itself never loads the CDK. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`, in either form.
 
 ```ts
 import { Component, computed, signal } from '@angular/core';
 import {
+  BF_TABLE_SORT_SELECT,
   BfBadgeComponent,
   BfSegmentedComponent,
   BfTableCellDirective,
@@ -502,6 +503,7 @@ import {
   type BfTableColumn,
   type BfTableSort,
 } from '@bitforgehq/ui';
+import { BfSelectComponent } from '@bitforgehq/ui/overlay';
 
 interface Task {
   id: string;
@@ -526,10 +528,16 @@ type Width = 'phone' | 'full';
  * than 36rem: the selection checkbox and the first cell head the tile, and a bar above the tiles
  * holds Select all and a Sort by select, whose first option, Not sorted, shows while `sort` is
  * null and clears it. Switch the box between phone width and full width.
+ *
+ * The Sort by select is the styled `bf-select`. In an app, add `provideBfSelect()` from
+ * `@bitforgehq/ui/overlay` to `app.config.ts` once; this page provides `BF_TABLE_SORT_SELECT`
+ * on the example instead, so the docs site loads the select only with this example.
  */
 @Component({
   selector: 'app-example-table-stacked',
   imports: [BfTableComponent, BfTableCellDirective, BfBadgeComponent, BfSegmentedComponent],
+  // In an app: provideBfSelect() in app.config.ts (see the comment above).
+  providers: [{ provide: BF_TABLE_SORT_SELECT, useValue: BfSelectComponent }],
   template: `
     <!-- A stacking table is a size container: its width comes from its parent, never its columns. -->
     <div class="flex w-152 max-w-full flex-col gap-3">
@@ -684,7 +692,7 @@ A table that can stack (`stack` other than `never`) sets explicit `table`, `rowg
 | <kbd>Space</kbd>                                 | Toggles the focused checkbox, or sorts by the focused header                                                                                                                |
 | <kbd>Enter</kbd>                                 | Sorts by the focused header                                                                                                                                                 |
 
-A stacked table's Sort by select is a native select with its own keys.
+A stacked table's Sort by select has its own keys: the native select's, or with `provideBfSelect()` those of [bf-select](https://bitforge-ui.web.app/components/select#keyboard).
 
 Text fields, selects and composite widgets (radios, comboboxes, sliders) in a cell keep their own arrow keys.
 
@@ -751,6 +759,13 @@ Selects or clears one row.
 
 ## Migration notes
 
+### 0.5.0
+
+New `BF_TABLE_SORT_SELECT` injection token: the component a stacked table renders as its "Sort
+by" select (`null`, the default, keeps the native one). `provideBfSelect()` from
+`@bitforgehq/ui/overlay` sets it to the styled `bf-select`, so the core entry still never imports
+the CDK. `BfTableHarness.getSortSelect()` returns a working `BfSelectHarness` either way.
+
 ### 0.4.0
 
 New: toggle cells for a settings matrix (rows of alert kinds, columns of channels, a `bf-toggle`

package/ai/components/theme-menu-button.md

@@ -127,6 +127,7 @@ The button consumes `bf-menu-button`'s tokens (`bf-button`'s, or `bf-icon-button
 - The three items are `role="menuitemradio"` with `aria-checked`, so a screen reader announces the current choice. The dot is drawn in CSS and adds nothing to the name.
 - Choosing an item closes the menu and returns focus to the button.
 - Hit area: at least 32 px, 44 px under a coarse pointer, as `bf-menu-button`.
+- Motion: the menu fades and grows out of the button as it opens, and closes at once. Under `prefers-reduced-motion` it only fades in.
 
 ### Keyboard
 

package/ai/components/time-input.md

@@ -138,6 +138,8 @@ The field shows the `primary` border and focus ring while any part has focus, th
 
 The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`); each part is a `role="spinbutton"` named from the `timeInputHour`, `timeInputMinute`, `timeInputSecond` and `timeInputDayPeriod` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext` (the AM or PM name), and the field's `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled`. The clock button is named by `timeInputOpenList`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The list is a `role="listbox"` named by the same label, its times `role="option"` with `aria-selected` and `aria-disabled`; focus stays on the list and `aria-activedescendant` names the active time.
 
+Motion: the list grows out of the field as it opens (a fade, a slight scale and a 4 px slide, 180 ms) and fades back as it closes (130 ms). Focus returns at once and the closing list is inert. Under `prefers-reduced-motion` it only fades.
+
 ### Keyboard
 
 | Key                                              | Where | Action                                                   |

package/ai/components/toolbar.md

@@ -12,11 +12,10 @@ import {
   BfButtonComponent,
   BfInputComponent,
   BfSegmentedComponent,
-  BfSelectComponent,
   BfToolbarComponent,
   type BfSegmentOption,
-  type BfSelectOption,
 } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 type ProjectStatus = 'active' | 'paused' | 'done';
 type StatusFilter = ProjectStatus | 'all';
@@ -125,7 +124,7 @@ export class ToolbarOverviewExampleComponent {
 Row of search, filters, a view switch and trailing actions above a list or table. Every
 control projected into it is `sm` unless it sets `size` itself.
 
-A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select`, `bf-chip-group`, `bf-segmented` and `bf-button`s.
+A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select` (from `@bitforgehq/ui/overlay`), `bf-chip-group`, `bf-segmented` and `bf-button`s.
 
 ## When to use
 
@@ -191,13 +190,8 @@ The row is a wrapping flex row with an 8 px gap between items and between rows.
 
 ```ts
 import { Component } from '@angular/core';
-import {
-  BfButtonComponent,
-  BfInputComponent,
-  BfSelectComponent,
-  BfToolbarComponent,
-  type BfSelectOption,
-} from '@bitforgehq/ui';
+import { BfButtonComponent, BfInputComponent, BfToolbarComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * A toolbar that wraps.
@@ -238,13 +232,8 @@ At phone width (in a desktop web app's narrow window or a narrow column) the sea
 
 ```ts
 import { Component, signal } from '@angular/core';
-import {
-  BfButtonComponent,
-  BfInputComponent,
-  BfSelectComponent,
-  BfToolbarComponent,
-  type BfSelectOption,
-} from '@bitforgehq/ui';
+import { BfButtonComponent, BfInputComponent, BfToolbarComponent } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 
 /**
  * A toolbar at phone width.
@@ -317,7 +306,7 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 ## Slots
 
-- `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
+- `default`: The search field and the filters (bf-input, bf-chip-group, bf-select from /overlay), in order.
 - `view`: A view switch after the filters, such as a bf-segmented of list and grid.
 - `actions`: The trailing actions, kept together at the inline end of the row, beside the status.
 

package/ai/reference/bf-chat-composer-harness.md

@@ -0,0 +1,64 @@
+# BfChatComposerHarness
+
+Test harness for the chat composer: types, sends, stops and reads its state
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-chat-composer` (`@bitforgehq/ui/overlay`). Its `label` filter matches the text
+field's name: the visible label, else its `aria-label` ("Message" by default).
+
+```ts
+import { BfChatComposerHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfChatComposerHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The text field's name: the visible label, else its `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The text in the field.
+
+### `setValue(text: string): Promise<void>`
+
+Replaces the text as the user would type it (`changed` and the value update).
+
+| Parameter | Type     | Description   |
+| --------- | -------- | ------------- |
+| `text`    | `string` | The new text. |
+
+### `send(): Promise<void>`
+
+Sends the text with the send button, as a click does. Does nothing while it cannot send.
+
+### `pressEnter(): Promise<void>`
+
+Sends the text with `Enter` in the field, as the keyboard does.
+
+### `stop(): Promise<void>`
+
+Stops the running reply with the stop button. Does nothing unless a reply is running.
+
+### `isRunning(): Promise<boolean>`
+
+Whether a reply is running, so the button stops instead of sending.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the composer is disabled (its text field is).
+
+### `canAct(): Promise<boolean>`
+
+Whether the button can send (or stop) now: not disabled and, to send, with text.
+
+### `getButtonLabel(): Promise<string>`
+
+The button's name, "Send" or "Stop" by default.

package/ai/reference/bf-chat-message-role.md

@@ -0,0 +1,27 @@
+# BfChatMessageRole
+
+Who wrote a chat message, the user or the assistant
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+Who wrote a `bf-chat-message`: `user` (a tinted bubble at the inline end) or `assistant` (full
+width, no bubble).
+
+```ts
+import { type BfChatMessageRole } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChatMessageRole = 'user' | 'assistant'
+```
+
+## Values
+
+- `user`
+- `assistant`
+
+## Used by
+
+- [bf-chat-message](../components/chat-message.md)

package/ai/reference/bf-chat-message-status.md

@@ -0,0 +1,28 @@
+# BfChatMessageStatus
+
+How a chat message ended: done, stopped by the user, or failed
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+How a `bf-chat-message` ended: `done` (the default, no status line), `stopped` (the user
+stopped the reply) or `failed` (it did not arrive or was not sent).
+
+```ts
+import { type BfChatMessageStatus } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfChatMessageStatus = 'done' | 'stopped' | 'failed'
+```
+
+## Values
+
+- `done`
+- `stopped`
+- `failed`
+
+## Used by
+
+- [bf-chat-message](../components/chat-message.md)

package/ai/reference/bf-fade-in-directive.md

@@ -0,0 +1,18 @@
+# BfFadeInDirective
+
+Fades an image in once it has loaded instead of popping in
+
+Directive from `@bitforgehq/ui` · since 0.5.0
+
+Fades an image in when it has loaded instead of letting it pop in line by line: put
+`bfFadeIn` on the `<img>`. The image stays transparent until its `load` (or `error`) event,
+then fades in over 260 ms (`duration-slow`), at once under `prefers-reduced-motion: reduce`. An
+image that is already loaded when it renders (from the cache) shows straight away. Reserve its
+space (`width`/`height` attributes or an aspect ratio) so the layout does not move when it
+arrives; for a placeholder while it loads, put a `bf-skeleton` behind it.
+
+```ts
+import { BfFadeInDirective } from '@bitforgehq/ui';
+```
+
+Selector: `img[bfFadeIn]`

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

@@ -0,0 +1,67 @@
+# BfFileInputHarness
+
+Test harness for the file input: drops files and reads the list and rejections
+
+Class from `@bitforgehq/ui/testing` · since 0.5.0
+
+Harness for `bf-file-input`, in both looks. `addFiles()` drops files on the field, so they go
+through the same `accept`, `maxSize` and `maxFiles` rules as a real drop; read the outcome with
+`getFileNames()` and `getRejected()`. It works by file name, so a test never needs the rows.
+
+```ts
+import { BfFileInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfFileInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else `ariaLabel`.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the field (an explicit message, or the first form error once touched).
+
+### `getVariant(): Promise<'field' | 'dropzone'>`
+
+The look of the field.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the field is read-only: it has no pick target.
+
+### `addFiles(files: File[]): Promise<void>`
+
+Drops files on the field, as a user would. On a disabled or read-only field it does nothing,
+like the UI.
+
+| Parameter | Type     | Description        |
+| --------- | -------- | ------------------ |
+| `files`   | `File[]` | The files to drop. |
+
+### `getFileNames(): Promise<string[]>`
+
+The names of the chosen files, in order (rejected files are not included).
+
+### `getRejected(): Promise<{ name: string; message: string }[]>`
+
+The files the last pick or drop refused, each with its reason, until they are dismissed.
+
+### `removeFile(name: string): Promise<void>`
+
+Removes the chosen file with this name, as the row's remove button does. Throws when no
+chosen file has that name or the field cannot be edited.
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `name`    | `string` | The file's name. |

package/ai/reference/bf-file-input-variant.md

@@ -0,0 +1,27 @@
+# BfFileInputVariant
+
+The two looks of a file picker, a compact field or a drop zone
+
+Type from `@bitforgehq/ui` · since 0.5.0
+
+The look of a `bf-file-input`: a compact field with a pick button (`field`), or a drop zone
+(`dropzone`). Both have the same API and behaviour.
+
+```ts
+import { type BfFileInputVariant } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfFileInputVariant = 'field' | 'dropzone'
+```
+
+## Values
+
+- `field`
+- `dropzone`
+
+## Used by
+
+- [bf-file-input](../components/file-input.md)

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-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)