@bitforgehq/ui 0.3.3 → 0.5.0-next.3

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)

package/ai/reference/bf-labels.md

@@ -12,80 +12,111 @@ import { type BfLabels } from '@bitforgehq/ui';
 
 ## Properties
 
-| Name                    | Type                                          | Default                                                                          | Description                                                                                                    |
-| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `loading`               | `string`                                      | `'Loading'`                                                                      | bf-spinner's accessible name (a loading bf-button's spinner is decorative and has none).                       |
-| `dismiss`               | `string`                                      | `'Dismiss'`                                                                      | bf-alert's dismiss button.                                                                                     |
-| `tabBar`                | `string`                                      | `'Main'`                                                                         | bf-tab-bar's navigation name.                                                                                  |
-| `tabBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | bf-tab's announcement of a numeric badge.                                                                      |
-| `back`                  | `string`                                      | `'Back'`                                                                         | bf-back-button's label.                                                                                        |
-| `ok`                    | `string`                                      | `'OK'`                                                                           | BfAlertDialogService's default button.                                                                         |
-| `cancel`                | `string`                                      | `'Cancel'`                                                                       | BfActionSheetService's cancel row.                                                                             |
-| `actions`               | `string`                                      | `'Actions'`                                                                      | An action sheet's name when it has no title.                                                                   |
-| `sheet`                 | `string`                                      | `'Sheet'`                                                                        | bf-sheet's name without an ariaLabel or heading.                                                               |
-| `modal`                 | `string`                                      | `'Modal'`                                                                        | bf-modal's name without an ariaLabel or heading.                                                               |
-| `refreshing`            | `string`                                      | `'Refreshing'`                                                                   | bf-refresher's status while refreshing.                                                                        |
-| `close`                 | `string`                                      | `'Close'`                                                                        | bf-dialog's and bf-side-panel's close button, and bf-sheet's screen-reader Close.                              |
-| `expand`                | `string`                                      | `'Expand'`                                                                       | bf-sheet's grabber button below the top snap point: the next press expands the sheet.                          |
-| `collapse`              | `string`                                      | `'Collapse'`                                                                     | bf-sheet's grabber button at the top snap point: the next press collapses the sheet.                           |
-| `sheetPosition`         | `(position: number, count: number) => string` | `` (position, count) => `Sheet at ${position} of ${count}` ``                    | bf-sheet's snap position (1-based), announced politely when it changes and part of the grabber button's name.  |
-| `dialog`                | `string`                                      | `'Dialog'`                                                                       | A dialog's or side panel's name without an ariaLabel, a title or a heading.                                    |
-| `notifications`         | `string`                                      | `'Notifications'`                                                                | The desktop toast stack's region name.                                                                         |
-| `tableSelectAll`        | `string`                                      | `'Select all rows'`                                                              | bf-table's header checkbox, which selects or clears every row.                                                 |
-| `tableSortBy`           | `string`                                      | `'Sort by'`                                                                      | The label of a stacked bf-table's sort select.                                                                 |
-| `tableSortNone`         | `string`                                      | `'Not sorted'`                                                                   | A stacked bf-table's first sort option: rows in the order given, no column sorted.                             |
-| `tableSortAscending`    | `(column: string) => string`                  | `` (column) => `${column}, ascending` ``                                         | A stacked bf-table's sort option for a column in ascending order.                                              |
-| `tableSortDescending`   | `(column: string) => string`                  | `` (column) => `${column}, descending` ``                                        | A stacked bf-table's sort option for a column in descending order.                                             |
-| `theme`                 | `string`                                      | `'Theme'`                                                                        | bf-theme-switch's and bf-theme-menu-button's name without a label.                                             |
-| `themeSystem`           | `string`                                      | `'System'`                                                                       | The theme choice that follows the system's colour scheme.                                                      |
-| `themeLight`            | `string`                                      | `'Light'`                                                                        | The theme choice that forces the light colour scheme.                                                          |
-| `themeDark`             | `string`                                      | `'Dark'`                                                                         | The theme choice that forces the dark colour scheme.                                                           |
-| `breadcrumb`            | `string`                                      | `'Breadcrumb'`                                                                   | bf-breadcrumb's navigation name.                                                                               |
-| `breadcrumbExpand`      | `(count: number) => string`                   | ``(count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`)`` | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides.                              |
-| `navigation`            | `string`                                      | `'Main'`                                                                         | bf-sidebar's and bf-top-nav's navigation name.                                                                 |
-| `navBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | a[bfNavItem]'s announcement of its count badge.                                                                |
-| `sidebarCollapse`       | `string`                                      | `'Collapse sidebar'`                                                             | bf-sidebar-toggle's name and tooltip while the sidebar is expanded.                                            |
-| `sidebarExpand`         | `string`                                      | `'Expand sidebar'`                                                               | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.                                        |
-| `skipToContent`         | `string`                                      | `'Skip to main content'`                                                         | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.                   |
-| `pagination`            | `string`                                      | `'Pagination'`                                                                   | bf-pagination's navigation name.                                                                               |
-| `previousPage`          | `string`                                      | `'Previous page'`                                                                | bf-pagination's button to the previous page.                                                                   |
-| `nextPage`              | `string`                                      | `'Next page'`                                                                    | bf-pagination's button to the next page.                                                                       |
-| `pageOf`                | `(page: number, count: number) => string`     | `` (page, count) => `Page ${page} of ${count}` ``                                | bf-pagination's compact position text, such as "Page 3 of 12".                                                 |
-| `goToPage`              | `(page: number) => string`                    | `` (page) => `Page ${page}` ``                                                   | bf-pagination's name of one page button, such as "Page 3".                                                     |
-| `tabGroup`              | `string`                                      | `'Tabs'`                                                                         | bf-tab-group's tablist name.                                                                                   |
-| `calendarPreviousMonth` | `string`                                      | `'Previous month'`                                                               | bf-calendar's button that shows the previous month.                                                            |
-| `calendarNextMonth`     | `string`                                      | `'Next month'`                                                                   | bf-calendar's button that shows the next month.                                                                |
-| `calendarChooseMonth`   | `string`                                      | `'Choose month'`                                                                 | bf-calendar's title button in the day view, which opens the month view; read after the visible month and year. |
-| `calendarChooseYear`    | `string`                                      | `'Choose year'`                                                                  | bf-calendar's title button in the month view, which opens the year view; read after the visible year.          |
-| `statTrendUp`           | `string`                                      | `'Up'`                                                                           | bf-stat's hidden direction word before an upward delta, so colour is never the only signal.                    |
-| `statTrendDown`         | `string`                                      | `'Down'`                                                                         | bf-stat's hidden direction word before a downward delta.                                                       |
-| `statTrendFlat`         | `string`                                      | `'No change'`                                                                    | bf-stat's hidden direction word before an unchanged (flat) delta.                                              |
-| `comboboxEmpty`         | `string`                                      | `'No results'`                                                                   | bf-combobox's and bf-multi-combobox's list row when no option matches the typed text.                          |
-| `comboboxRemove`        | `(label: string) => string`                   | `` (label) => `Remove ${label}` ``                                               | bf-multi-combobox's remove button on a picked value's tag.                                                     |
-| `dateInputDay`          | `string`                                      | `'Day'`                                                                          | The day part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("dd").        |
-| `dateInputMonth`        | `string`                                      | `'Month'`                                                                        | The month part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("mm").      |
-| `dateInputYear`         | `string`                                      | `'Year'`                                                                         | The year part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("yyyy").     |
-| `dateInputOpenCalendar` | `string`                                      | `'Choose date'`                                                                  | The button of bf-date-input and bf-datetime-input that opens the calendar, and the panel's name.               |
-| `dateInputInvalid`      | `string`                                      | `'Enter a valid date'`                                                           | The error of bf-date-input and bf-datetime-input while the date is incomplete or does not exist (31 February). |
-| `dateInputUnavailable`  | `string`                                      | `'This date is not available'`                                                   | The error of bf-date-input and bf-datetime-input for a typed date that `disabledDate` rules out.               |
-| `timeInputHour`         | `string`                                      | `'Hour'`                                                                         | The hour part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("hh").       |
-| `timeInputMinute`       | `string`                                      | `'Minute'`                                                                       | The minute part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("mm").     |
-| `timeInputSecond`       | `string`                                      | `'Second'`                                                                       | The second part of bf-time-input with `seconds`; its first letter is the part's placeholder ("ss").            |
-| `timeInputDayPeriod`    | `string`                                      | `'AM/PM'`                                                                        | The AM/PM part of bf-time-input and bf-datetime-input under a 12-hour clock.                                   |
-| `timeInputOpenList`     | `string`                                      | `'Choose time'`                                                                  | The button of bf-time-input that opens the list of times, and the list's name.                                 |
-| `timeInputInvalid`      | `string`                                      | `'Enter a valid time'`                                                           | The error of bf-time-input and bf-datetime-input while the time is incomplete.                                 |
-| `timeInputMin`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or later` ``                                          | The error of bf-time-input and bf-datetime-input below `min`, given the limit as the locale writes it.         |
-| `timeInputMax`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or earlier` ``                                        | The error of bf-time-input and bf-datetime-input above `max`, given the limit as the locale writes it.         |
-| `chart`                 | `string`                                      | `'Chart'`                                                                        | The name of a chart from `@bitforgehq/ui/charts` that has no `label` (and no `bf-chart-card` title).           |
-| `chartLegend`           | `string`                                      | `'Legend'`                                                                       | The name of a chart's legend, the group of buttons that show and hide its series.                              |
-| `chartValues`           | `string`                                      | `'Data points, arrow keys move between them'`                                    | The name of a chart's plot, the focusable area whose arrow keys move between the values.                       |
-| `chartShowData`         | `string`                                      | `'Show data'`                                                                    | A chart's button that shows its data as a table.                                                               |
-| `chartHideData`         | `string`                                      | `'Hide data'`                                                                    | A chart's button that hides its data table again.                                                              |
-| `chartCategory`         | `string`                                      | `'Category'`                                                                     | The first column header of a chart's data table.                                                               |
-| `chartValue`            | `string`                                      | `'Value'`                                                                        | The value column header of a bf-donut-chart's data table.                                                      |
-| `chartEmpty`            | `string`                                      | `'No data to show'`                                                              | bf-chart-card's text when it has no data and no `empty` slot.                                                  |
-| `chartError`            | `string`                                      | `'The data could not be loaded'`                                                 | bf-chart-card's text when its data failed to load and it has no `error` slot.                                  |
-| `validation`            | `BfValidationMessages`                        | required                                                                         | Default error text per validator kind (see `BfValidationMessages`).                                            |
+| Name                    | Type                                          | Default                                                                                 | Description                                                                                                    |
+| ----------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `loading`               | `string`                                      | `'Loading'`                                                                             | bf-spinner's accessible name (a loading bf-button's spinner is decorative and has none).                       |
+| `dismiss`               | `string`                                      | `'Dismiss'`                                                                             | bf-alert's dismiss button.                                                                                     |
+| `tabBar`                | `string`                                      | `'Main'`                                                                                | bf-tab-bar's navigation name.                                                                                  |
+| `tabBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                         | bf-tab's announcement of a numeric badge.                                                                      |
+| `back`                  | `string`                                      | `'Back'`                                                                                | bf-back-button's label.                                                                                        |
+| `ok`                    | `string`                                      | `'OK'`                                                                                  | BfAlertDialogService's default button.                                                                         |
+| `cancel`                | `string`                                      | `'Cancel'`                                                                              | BfActionSheetService's cancel row.                                                                             |
+| `actions`               | `string`                                      | `'Actions'`                                                                             | An action sheet's name when it has no title.                                                                   |
+| `sheet`                 | `string`                                      | `'Sheet'`                                                                               | bf-sheet's name without an ariaLabel or heading.                                                               |
+| `modal`                 | `string`                                      | `'Modal'`                                                                               | bf-modal's name without an ariaLabel or heading.                                                               |
+| `refreshing`            | `string`                                      | `'Refreshing'`                                                                          | bf-refresher's status while refreshing.                                                                        |
+| `close`                 | `string`                                      | `'Close'`                                                                               | bf-dialog's and bf-side-panel's close button, and bf-sheet's screen-reader Close.                              |
+| `expand`                | `string`                                      | `'Expand'`                                                                              | bf-sheet's grabber button below the top snap point: the next press expands the sheet.                          |
+| `collapse`              | `string`                                      | `'Collapse'`                                                                            | bf-sheet's grabber button at the top snap point: the next press collapses the sheet.                           |
+| `sheetPosition`         | `(position: number, count: number) => string` | `` (position, count) => `Sheet at ${position} of ${count}` ``                           | bf-sheet's snap position (1-based), announced politely when it changes and part of the grabber button's name.  |
+| `dialog`                | `string`                                      | `'Dialog'`                                                                              | A dialog's or side panel's name without an ariaLabel, a title or a heading.                                    |
+| `notifications`         | `string`                                      | `'Notifications'`                                                                       | The desktop toast stack's region name.                                                                         |
+| `tableSelectAll`        | `string`                                      | `'Select all rows'`                                                                     | bf-table's header checkbox, which selects or clears every row.                                                 |
+| `tableSortBy`           | `string`                                      | `'Sort by'`                                                                             | The label of a stacked bf-table's sort select.                                                                 |
+| `tableSortNone`         | `string`                                      | `'Not sorted'`                                                                          | A stacked bf-table's first sort option: rows in the order given, no column sorted.                             |
+| `tableSortAscending`    | `(column: string) => string`                  | `` (column) => `${column}, ascending` ``                                                | A stacked bf-table's sort option for a column in ascending order.                                              |
+| `tableSortDescending`   | `(column: string) => string`                  | `` (column) => `${column}, descending` ``                                               | A stacked bf-table's sort option for a column in descending order.                                             |
+| `theme`                 | `string`                                      | `'Theme'`                                                                               | bf-theme-switch's and bf-theme-menu-button's name without a label.                                             |
+| `themeSystem`           | `string`                                      | `'System'`                                                                              | The theme choice that follows the system's colour scheme.                                                      |
+| `themeLight`            | `string`                                      | `'Light'`                                                                               | The theme choice that forces the light colour scheme.                                                          |
+| `themeDark`             | `string`                                      | `'Dark'`                                                                                | The theme choice that forces the dark colour scheme.                                                           |
+| `breadcrumb`            | `string`                                      | `'Breadcrumb'`                                                                          | bf-breadcrumb's navigation name.                                                                               |
+| `breadcrumbExpand`      | `(count: number) => string`                   | ``(count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`)``        | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides.                              |
+| `navigation`            | `string`                                      | `'Main'`                                                                                | bf-sidebar's and bf-top-nav's navigation name.                                                                 |
+| `navBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                         | a[bfNavItem]'s announcement of its count badge.                                                                |
+| `sidebarCollapse`       | `string`                                      | `'Collapse sidebar'`                                                                    | bf-sidebar-toggle's name and tooltip while the sidebar is expanded.                                            |
+| `sidebarExpand`         | `string`                                      | `'Expand sidebar'`                                                                      | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.                                        |
+| `skipToContent`         | `string`                                      | `'Skip to main content'`                                                                | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.                   |
+| `pagination`            | `string`                                      | `'Pagination'`                                                                          | bf-pagination's navigation name.                                                                               |
+| `previousPage`          | `string`                                      | `'Previous page'`                                                                       | bf-pagination's button to the previous page.                                                                   |
+| `nextPage`              | `string`                                      | `'Next page'`                                                                           | bf-pagination's button to the next page.                                                                       |
+| `pageOf`                | `(page: number, count: number) => string`     | `` (page, count) => `Page ${page} of ${count}` ``                                       | bf-pagination's compact position text, such as "Page 3 of 12".                                                 |
+| `goToPage`              | `(page: number) => string`                    | `` (page) => `Page ${page}` ``                                                          | bf-pagination's name of one page button, such as "Page 3".                                                     |
+| `tabGroup`              | `string`                                      | `'Tabs'`                                                                                | bf-tab-group's tablist name.                                                                                   |
+| `calendarPreviousMonth` | `string`                                      | `'Previous month'`                                                                      | bf-calendar's button that shows the previous month.                                                            |
+| `calendarNextMonth`     | `string`                                      | `'Next month'`                                                                          | bf-calendar's button that shows the next month.                                                                |
+| `calendarChooseMonth`   | `string`                                      | `'Choose month'`                                                                        | bf-calendar's title button in the day view, which opens the month view; read after the visible month and year. |
+| `calendarChooseYear`    | `string`                                      | `'Choose year'`                                                                         | bf-calendar's title button in the month view, which opens the year view; read after the visible year.          |
+| `statTrendUp`           | `string`                                      | `'Up'`                                                                                  | bf-stat's hidden direction word before an upward delta, so colour is never the only signal.                    |
+| `statTrendDown`         | `string`                                      | `'Down'`                                                                                | bf-stat's hidden direction word before a downward delta.                                                       |
+| `statTrendFlat`         | `string`                                      | `'No change'`                                                                           | bf-stat's hidden direction word before an unchanged (flat) delta.                                              |
+| `comboboxEmpty`         | `string`                                      | `'No results'`                                                                          | bf-combobox's and bf-multi-combobox's list row when no option matches the typed text.                          |
+| `comboboxRemove`        | `(label: string) => string`                   | `` (label) => `Remove ${label}` ``                                                      | bf-multi-combobox's remove button on a picked value's tag.                                                     |
+| `dateInputDay`          | `string`                                      | `'Day'`                                                                                 | The day part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("dd").        |
+| `dateInputMonth`        | `string`                                      | `'Month'`                                                                               | The month part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("mm").      |
+| `dateInputYear`         | `string`                                      | `'Year'`                                                                                | The year part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("yyyy").     |
+| `dateInputOpenCalendar` | `string`                                      | `'Choose date'`                                                                         | The button of bf-date-input and bf-datetime-input that opens the calendar, and the panel's name.               |
+| `dateInputInvalid`      | `string`                                      | `'Enter a valid date'`                                                                  | The error of bf-date-input and bf-datetime-input while the date is incomplete or does not exist (31 February). |
+| `dateInputUnavailable`  | `string`                                      | `'This date is not available'`                                                          | The error of bf-date-input and bf-datetime-input for a typed date that `disabledDate` rules out.               |
+| `timeInputHour`         | `string`                                      | `'Hour'`                                                                                | The hour part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("hh").       |
+| `timeInputMinute`       | `string`                                      | `'Minute'`                                                                              | The minute part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("mm").     |
+| `timeInputSecond`       | `string`                                      | `'Second'`                                                                              | The second part of bf-time-input with `seconds`; its first letter is the part's placeholder ("ss").            |
+| `timeInputDayPeriod`    | `string`                                      | `'AM/PM'`                                                                               | The AM/PM part of bf-time-input and bf-datetime-input under a 12-hour clock.                                   |
+| `timeInputOpenList`     | `string`                                      | `'Choose time'`                                                                         | The button of bf-time-input that opens the list of times, and the list's name.                                 |
+| `timeInputInvalid`      | `string`                                      | `'Enter a valid time'`                                                                  | The error of bf-time-input and bf-datetime-input while the time is incomplete.                                 |
+| `timeInputMin`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or later` ``                                                 | The error of bf-time-input and bf-datetime-input below `min`, given the limit as the locale writes it.         |
+| `timeInputMax`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or earlier` ``                                               | The error of bf-time-input and bf-datetime-input above `max`, given the limit as the locale writes it.         |
+| `chart`                 | `string`                                      | `'Chart'`                                                                               | The name of a chart from `@bitforgehq/ui/charts` that has no `label` (and no `bf-chart-card` title).           |
+| `chartLegend`           | `string`                                      | `'Legend'`                                                                              | The name of a chart's legend, the group of buttons that show and hide its series.                              |
+| `chartValues`           | `string`                                      | `'Data points, arrow keys move between them'`                                           | The name of a chart's plot, the focusable area whose arrow keys move between the values.                       |
+| `chartShowData`         | `string`                                      | `'Show data'`                                                                           | A chart's button that shows its data as a table.                                                               |
+| `chartHideData`         | `string`                                      | `'Hide data'`                                                                           | A chart's button that hides its data table again.                                                              |
+| `chartCategory`         | `string`                                      | `'Category'`                                                                            | The first column header of a chart's data table.                                                               |
+| `chartValue`            | `string`                                      | `'Value'`                                                                               | The value column header of a bf-donut-chart's data table.                                                      |
+| `chartEmpty`            | `string`                                      | `'No data to show'`                                                                     | bf-chart-card's text when it has no data and no `empty` slot.                                                  |
+| `chartError`            | `string`                                      | `'The data could not be loaded'`                                                        | bf-chart-card's text when its data failed to load and it has no `error` slot.                                  |
+| `listItemUnread`        | `string`                                      | `'Unread'`                                                                              | bf-list-item's visually hidden state text before the title of an `unread` row.                                 |
+| `fileInputChoose`       | `(multiple: boolean) => string`               | `(multiple) => (multiple ? 'Choose files' : 'Choose file')`                             | bf-file-input's button text.                                                                                   |
+| `fileInputDropHint`     | `(multiple: boolean) => string`               | `(multiple) => (multiple ? 'or drop them here' : 'or drop it here')`                    | bf-file-input's hint beside the button.                                                                        |
+| `fileInputDropzone`     | `(multiple: boolean) => string`               | `(multiple) => (multiple ? 'Drag files here or browse' : 'Drag a file here or browse')` | bf-file-input's drop zone text.                                                                                |
+| `fileInputTapToChoose`  | `(multiple: boolean) => string`               | `(multiple) => (multiple ? 'Tap to choose files' : 'Tap to choose a file')`             | bf-file-input's text under touch input.                                                                        |
+| `fileInputRemove`       | `(name: string) => string`                    | `` (name) => `Remove ${name}` ``                                                        | The accessible name of bf-file-input's remove button for a file.                                               |
+| `fileInputDismiss`      | `(name: string) => string`                    | `` (name) => `Dismiss ${name}` ``                                                       | The accessible name of bf-file-input's button that dismisses a rejected file.                                  |
+| `fileInputAdded`        | `(count: number) => string`                   | ``(count) => (count === 1 ? '1 file added' : `${count} files added`)``                  | bf-file-input's live announcement after files are added.                                                       |
+| `fileInputNotAdded`     | `(name: string, reason: string) => string`    | `` (name, reason) => `${name} was not added: ${reason}` ``                              | bf-file-input's live announcement for a rejected file.                                                         |
+| `fileInputRemoved`      | `(name: string) => string`                    | `` (name) => `${name} removed` ``                                                       | bf-file-input's live announcement after a file is removed.                                                     |
+| `fileInputCount`        | `(count: number) => string`                   | ``(count) => (count === 1 ? '1 file' : `${count} files`)``                              | bf-file-input's read-only box text for the number of chosen files.                                             |
+| `fileRejectedType`      | `string`                                      | `'Not an accepted type'`                                                                | The message of a file rejected for its type.                                                                   |
+| `fileRejectedSize`      | `(max: string) => string`                     | `` (max) => `Too large, max ${max}` ``                                                  | The message of a file rejected for its size; `max` is the formatted limit.                                     |
+| `fileRejectedCount`     | `(max: number) => string`                     | `` (max) => `Too many files, max ${max}` ``                                             | The message of a file rejected because the file limit is reached.                                              |
+| `imageInputChoose`      | `string`                                      | `'Choose image'`                                                                        | bf-image-input's accessible name for the empty drop target.                                                    |
+| `imageInputUpload`      | `string`                                      | `'Upload'`                                                                              | bf-image-input's text for choosing the first image.                                                            |
+| `imageInputReplace`     | `string`                                      | `'Replace'`                                                                             | bf-image-input's text for replacing the image.                                                                 |
+| `imageInputRemove`      | `string`                                      | `'Remove'`                                                                              | bf-image-input's text for removing the image.                                                                  |
+| `chatThread`            | `string`                                      | `'Conversation'`                                                                        | bf-chat-thread's accessible name (its `role="log"`) when no `label` is set.                                    |
+| `chatJumpToLatest`      | `string`                                      | `'Jump to latest'`                                                                      | bf-chat-thread's button that scrolls back to the newest message and follows it again.                          |
+| `chatMessageStopped`    | `string`                                      | `'Stopped'`                                                                             | bf-chat-message's status line for a reply the user stopped.                                                    |
+| `chatMessageFailed`     | `string`                                      | `'Something went wrong'`                                                                | bf-chat-message's status line for a message that failed.                                                       |
+| `chatComposer`          | `string`                                      | `'Message'`                                                                             | bf-chat-composer's text field name when no `label` or `ariaLabel` is set.                                      |
+| `chatSend`              | `string`                                      | `'Send'`                                                                                | bf-chat-composer's send button.                                                                                |
+| `chatStop`              | `string`                                      | `'Stop'`                                                                                | bf-chat-composer's stop button, shown in place of send while a reply runs.                                     |
+| `mediaCardSelect`       | `string`                                      | `'Select'`                                                                              | bf-media-card's select button, read before the card's name ("Select Starfall").                                |
+| `imageLoadFailed`       | `string`                                      | `'The image could not be loaded'`                                                       | bf-media-card's and bf-image-viewer's message for an image that failed to load.                                |
+| `imageViewer`           | `string`                                      | `'Image viewer'`                                                                        | bf-image-viewer's name.                                                                                        |
+| `imageViewerPrevious`   | `string`                                      | `'Previous image'`                                                                      | bf-image-viewer's button that shows the previous image.                                                        |
+| `imageViewerNext`       | `string`                                      | `'Next image'`                                                                          | bf-image-viewer's button that shows the next image.                                                            |
+| `imageViewerPosition`   | `(position: number, count: number) => string` | `` (position, count) => `${position} of ${count}` ``                                    | bf-image-viewer's counter: the shown image's position (1-based) among the images.                              |
+| `validation`            | `BfValidationMessages`                        | required                                                                                | Default error text per validator kind (see `BfValidationMessages`).                                            |
 
 ## Uses
 

package/ai/reference/bf-media-card-aspect.md

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