@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/ai/components/timeline.md

@@ -0,0 +1,201 @@
+# bf-timeline
+
+Dated list of events with who did what and when, on a vertical line
+
+`BfTimelineComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-timeline overview.
+ *
+ * Live demo of `bf-timeline`: the history of a security finding, newest first. A system event has
+ * no actor, the pull request is a link in the event text, the failed CI run is `danger` and the
+ * fix `success`.
+ */
+@Component({
+  selector: 'app-example-timeline-overview',
+  imports: [RouterLink, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="Finding history" class="max-w-xl">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="success">
+        Marked the finding as fixed
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T13:05:00Z" tone="danger">
+        CI failed on the security scan
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-28T11:20:00Z" tone="primary">
+        Linked
+        <a routerLink="." fragment="links-in-events">PR #123</a>
+        to the finding
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-27T16:02:00Z">
+        Assigned the finding to Lena Meier
+      </bf-timeline-event>
+      <bf-timeline-event time="2026-10-27T08:14:00Z">
+        Created by the nightly dependency scan
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineOverviewExampleComponent {}
+```
+
+## Overview
+
+A dated history of events, newest first or oldest first as the consumer orders them: who did
+what and when, each event a `bf-timeline-event` with a marker on a vertical line.
+
+A timeline shows the history of one thing as dated events: who did what, and when. Each event is a [`bf-timeline-event`](https://bitforge-ui.web.app/components/timeline-event) with a coloured marker on a vertical line, its text (which may link the objects it names), then the actor and the time. The timeline shows the events in the order you give them, newest first or oldest first; it never sorts. It works the same in a desktop web app, a narrow side panel and the Capacitor shell.
+
+## When to use
+
+Use `bf-timeline` for a record's history or an audit trail: a finding that was created, assigned, linked to a pull request and fixed; the changes in a CVE side panel; who changed a setting. Use [bf-list](https://bitforge-ui.web.app/components/list) instead for items the user opens or acts on, and for navigation; a timeline is not a stepper through a process either, nor a feed the user scrolls for new items. For the details of one record, use a [bf-description-list](https://bitforge-ui.web.app/components/description-list).
+
+## Events and tones
+
+`actor` names who did it (leave it empty for a system event), `time` says when (a `Date` or an ISO 8601 string), and the content is the event text. `tone` colours the marker: `neutral` (the default) for routine events, `primary` for the current or most important one, `success` (fixed, merged), `warning`, `danger` (CI failed, a regression) and `info`. The colour only supports the text, so say what happened in words ("CI failed"), never by the colour alone. The line runs from each marker to the next and ends at the last event.
+
+## Links in events
+
+The event text is the default slot, so the objects it names can be links: a pull request, a repository, a CVE. Put a plain `<a href>` (or `<a routerLink>`) inline in the text; the event styles every link in its text in `primary-text`, underlined, with a thicker underline on hover and the focus ring on keyboard focus. Keep the link text the object's name ("PR #123"), not "here".
+
+## Time format
+
+The time is formatted with `Intl.DateTimeFormat` in the app's `LOCALE_ID`: a medium date and a short time by default (`28 Oct 2026, 14:30` in `en-GB`, `28.10.2026, 14:30` in `de-CH`), in the browser's time zone. `timeFormat` on the timeline takes any `Intl.DateTimeFormatOptions` for all its events (`{ dateStyle: 'short' }`, or a `timeZone`), and `locale` overrides the language for one timeline. `timeText` on an event shows your own text in place of the formatted time, such as a relative "vor 2 Std."; the `time` element's `datetime` keeps the exact value. An empty or invalid `time` shows no time, and a locale or options the browser refuses fall back to the defaults, so a bad value never throws.
+
+## Audit trail
+
+An audit trail is actor-heavy: every event names a person or a bot. The `end` slot holds a small action for one event, such as a Show diff button: it sits at the inline end while the timeline is wide, and wraps under the text in a narrow side panel or on a phone (once the text would get narrower than 16rem). It takes no space while empty.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+interface AuditEntry {
+  id: string;
+  actor: string;
+  action: string;
+  time: string;
+  ago: string;
+  diff: boolean;
+}
+
+const ENTRIES: readonly AuditEntry[] = [
+  {
+    id: 'severity',
+    actor: 'Lena Meier',
+    action: 'Raised the severity from Medium to High',
+    time: '2026-10-28T14:10:00Z',
+    ago: '2 hours ago',
+    diff: true,
+  },
+  {
+    id: 'policy',
+    actor: 'Policy bot',
+    action: 'Applied the "Critical CVEs block releases" policy',
+    time: '2026-10-28T09:30:00Z',
+    ago: '7 hours ago',
+    diff: true,
+  },
+  {
+    id: 'owner',
+    actor: 'Jonas Keller',
+    action: 'Set the owner to the Platform team',
+    time: '2026-10-27T16:45:00Z',
+    ago: 'Yesterday',
+    diff: false,
+  },
+];
+
+/**
+ * An audit trail with relative times and an action per event.
+ *
+ * Every event names its actor, `timeText` shows a relative time while `datetime` keeps the exact
+ * one, and the `end` slot holds a Show diff button: at the inline end while the timeline is wide,
+ * under the text in a narrow panel.
+ */
+@Component({
+  selector: 'app-example-timeline-audit',
+  imports: [BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <div class="flex max-w-xl flex-col gap-3">
+      <bf-timeline label="Audit trail">
+        @for (entry of entries; track entry.id) {
+          <bf-timeline-event [actor]="entry.actor" [time]="entry.time" [timeText]="entry.ago">
+            {{ entry.action }}
+            @if (entry.diff) {
+              <bf-button bfSlot="end" variant="outline" size="sm" (clicked)="showDiff(entry)">
+                Show diff
+              </bf-button>
+            }
+          </bf-timeline-event>
+        }
+      </bf-timeline>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TimelineAuditExampleComponent {
+  readonly entries = ENTRIES;
+  readonly status = signal('No diff open.');
+
+  /** A real app would open the change in a side panel. */
+  showDiff(entry: AuditEntry): void {
+    this.status.set(`Diff of "${entry.action}" by ${entry.actor}.`);
+  }
+}
+```
+
+## Desktop
+
+The timeline itself is not interactive: no hover, no pointer cursor, no focus stop. Only the links in the event text and the controls in an `end` slot take focus, with their own hover and focus ring. Its spacing does not follow `provideBfDefaults()`: the events keep one rhythm at every density, and it has no `size`. Inside `provideBfShell()` it renders and behaves the same; the `end` slot's buttons bring their own 44 px touch height.
+
+## Theming
+
+- Marker: a 10 px dot (`rounded-control`) in `text-subtle` (neutral), `primary`, `success`, `warning`, `danger` or `info`; `CanvasText` under forced colours.
+- Line: a 1 px `border` line from marker to marker.
+- Text: `text-body` in `text`; links `primary-text`, underlined, `ring` on keyboard focus. Meta line: `text-caption` in `text-muted`.
+- Spacing: 12 px between the marker and the text, 20 px between events.
+
+## Accessibility
+
+The timeline is a list (`role="list"`, named by `label` through `aria-label`) and each event inside it a `listitem`, so a screen reader announces the number of events and the position of each. An event outside a `bf-timeline` claims no role. The marker and the line are `aria-hidden`; the tone is decoration, so the text must say what happened. The time is a `time` element whose `datetime` is the ISO value, and the separator between actor and time is hidden from assistive technology. Links and `end` slot controls are native elements in reading order.
+
+## Inputs
+
+| Name         | Type                         | Default                | Description                                                                                                                                   |
+| ------------ | ---------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`                     | `''`                   | The list's accessible name, such as "History"; empty leaves the list unnamed (a visible heading above it already names the section).          |
+| `timeFormat` | `Intl.DateTimeFormatOptions` | `TIMELINE_TIME_FORMAT` | `Intl.DateTimeFormat` options of every event's time; by default a medium date and a short time (`dateStyle: 'medium'`, `timeStyle: 'short'`). |
+| `locale`     | `string`                     | `''`                   | BCP 47 locale of the times, such as `de-CH`; empty follows the app's `LOCALE_ID`.                                                             |
+
+## Slots
+
+- `default`: The events, each a `bf-timeline-event`, in the order to show them.
+
+## Notes
+
+### Do
+
+- Give the timeline a `label` when no visible heading names it, and keep one order (newest first) across the app.
+- Name the actor and the object in every event; link the object.
+
+### Don't
+
+- Don't use a timeline for navigation or for steps the user still has to take.
+- Don't carry meaning in the tone alone; say "CI failed", not just a red dot.
+
+## Migration notes
+
+### 0.4.0
+
+New: `bf-timeline`, a dated history of events (who did what, and when) for a record's history
+or an audit trail, in both shells. A `role="list"` named by `label`, in the order the consumer
+gives (it never sorts); each event's time is formatted with `Intl.DateTimeFormat` in the app's
+`LOCALE_ID` (`timeFormat`, default a medium date and a short time; `locale` overrides it).

package/ai/components/toggle.md

@@ -130,9 +130,11 @@ export class ToggleListRowExampleComponent {
 }
 ```
 
+In a table of switches (a settings matrix: alert kinds by channel), each cell's toggle is named after its column and row with `ariaLabel`; see [bf-table](https://bitforge-ui.web.app/components/table)'s Toggle cells.
+
 ## Sizes
 
-`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px. The knob travels to the inline end, so it moves left under `dir="rtl"`.
+`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px, and a label-less `sm` switch (40 px wide) also takes a 44 px width, its track centred. The knob travels to the inline end, so it moves left under `dir="rtl"`.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -325,6 +327,14 @@ Focuses the native switch; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.4.0
+
+A label-less `sm` toggle (a table cell) takes a 44 px min-width under a coarse pointer, its track
+centred, so its touch target is 44 × 44 px (it was 40 px wide). Nothing changes under a fine
+pointer or for `md` and `lg`. `@bitforgehq/ui/testing`: new `BfToggleHarness` (`with({ label })`
+by the switch's computed name, `getLabel()`, `isChecked()`, `isDisabled()`, `isReadonly()`,
+`toggle()`, `check()`, `uncheck()`, `getErrorText()`).
+
 ### 0.3.0
 
 New `ariaLabelledby` input: the id of the element that names the switch when no visible `label`

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-action-directive.md

@@ -12,7 +12,9 @@ exposed: the heading stays a heading and the accessible name is the title alone.
 with the nearest card or row, which then draws the pointer, the hover and, while the action has
 keyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give
 secondary controls inside the surface `class="relative z-1"` so they stay clickable above the
-stretched area.
+stretched area. When the surface marks a state that belongs in the name (an `unread` list
+row), the directive names the element `aria-labelledby="<state id> <own id>"`, so the link reads
+"Unread, Account", and restores the element's own `aria-labelledby` when the state goes.
 
 ```ts
 import { BfActionDirective } from '@bitforgehq/ui';

package/ai/reference/bf-badge-emphasis.md

@@ -0,0 +1,27 @@
+# BfBadgeEmphasis
+
+The two badge emphases, the soft tint or the solid strong fill
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+How loud a `bf-badge` is: `soft`, a pale tint with tinted text (the default), or `strong`, a
+solid fill with contrasting text for the one state that must stand out, such as "Critical".
+
+```ts
+import { type BfBadgeEmphasis } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeEmphasis = 'soft' | 'strong'
+```
+
+## Values
+
+- `soft`
+- `strong`
+
+## Used by
+
+- [bf-badge](../components/badge.md)

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)