@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/ai/components/file-input.md

@@ -0,0 +1,498 @@
+# bf-file-input
+
+File picker field that lists picked or dropped files and checks type, size and count
+
+`BfFileInputComponent` from `@bitforgehq/ui` · Forms · since 0.5.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-file-input overview.
+ *
+ * Live demo of `bf-file-input`: the field look taking several PDFs and images for an invoice, bound
+ * to a signal with a line that says what is chosen; then the drop zone look for receipts.
+ */
+@Component({
+  selector: 'app-example-file-input-overview',
+  imports: [BfFileInputComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <bf-file-input
+        label="Invoice attachments"
+        helpText="PDF, PNG or JPEG, up to 10 MB each"
+        accept=".pdf,image/png,image/jpeg"
+        multiple
+        [maxSize]="10 * 1024 * 1024"
+        [(value)]="attachments"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <bf-file-input variant="dropzone" label="Receipts" accept="image/*,.pdf" multiple />
+    </div>
+  `,
+})
+export class FileInputOverviewExampleComponent {
+  readonly attachments = signal<File[]>([]);
+
+  readonly status = computed(() => {
+    const files = this.attachments();
+    return files.length === 0
+      ? 'No attachments yet.'
+      : `Attached: ${files.map((file) => file.name).join(', ')}.`;
+  });
+}
+```
+
+## Overview
+
+File picker field: a tonal "Choose file" button inside a field box that also takes dropped
+files, with the chosen files listed under it (thumbnail, name, size, remove button). `accept`,
+`maxSize` and `maxFiles` decide what is added; a file that breaks one is listed in red with the
+reason until the next pick and emitted through `rejected`, and never enters the value. The value
+is always a `File[]` (one file at most while `multiple` is off). It only picks: uploading the
+files is the app's job. Bind `[(value)]` directly or `[formField]` from a signal form.
+
+A file picker field: a tonal "Choose file" button inside a field box that also takes dropped files, or a dashed drop zone with the same API. The chosen files are listed under it with a thumbnail (images) or the file extension, the name, the size and a remove button. `accept`, `maxSize` and `maxFiles` decide what is added; the value is always a `File[]`. It only picks files: uploading them is the app's job.
+
+## When to use
+
+Use `bf-file-input` for documents and attachments: a signed contract, the scans for an invoice, a CSV to import. Use [bf-image-input](https://bitforge-ui.web.app/components/image-input) instead for one picture that should be seen while it is chosen (a profile picture, a logo), and [bf-input](https://bitforge-ui.web.app/components/input) for a link to a file that already lives somewhere else.
+
+## Basic usage
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-file-input overview.
+ *
+ * Live demo of `bf-file-input`: the field look taking several PDFs and images for an invoice, bound
+ * to a signal with a line that says what is chosen; then the drop zone look for receipts.
+ */
+@Component({
+  selector: 'app-example-file-input-overview',
+  imports: [BfFileInputComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <bf-file-input
+        label="Invoice attachments"
+        helpText="PDF, PNG or JPEG, up to 10 MB each"
+        accept=".pdf,image/png,image/jpeg"
+        multiple
+        [maxSize]="10 * 1024 * 1024"
+        [(value)]="attachments"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <bf-file-input variant="dropzone" label="Receipts" accept="image/*,.pdf" multiple />
+    </div>
+  `,
+})
+export class FileInputOverviewExampleComponent {
+  readonly attachments = signal<File[]>([]);
+
+  readonly status = computed(() => {
+    const files = this.attachments();
+    return files.length === 0
+      ? 'No attachments yet.'
+      : `Attached: ${files.map((file) => file.name).join(', ')}.`;
+  });
+}
+```
+
+`value` is a `File[]`, empty while nothing is chosen. `(changed)` emits the new list right after the user adds or removes a file; a programmatic write to `value` does not emit.
+
+## One file or several
+
+Without `multiple`, a new pick or drop replaces the chosen file, so the value holds one file at most. With `multiple`, picks and drops are added to the list (a file picked twice is listed twice), and each row has its own remove button.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * One file or several.
+ *
+ * Without `multiple` a new pick replaces the chosen file; with it, picks and drops are added to the
+ * list, and each file can be removed on its own.
+ */
+@Component({
+  selector: 'app-example-file-input-multiple',
+  imports: [BfFileInputComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <bf-file-input label="Signed contract" accept=".pdf" [(value)]="contract" />
+      <bf-file-input label="Supporting documents" multiple [(value)]="documents" />
+    </div>
+  `,
+})
+export class FileInputMultipleExampleComponent {
+  protected readonly contract = signal<File[]>([]);
+  protected readonly documents = signal<File[]>([]);
+}
+```
+
+## Drop zone
+
+`variant="dropzone"` swaps the field box for a dashed area with an upload badge: the whole area is the control, so a click, <kbd>Enter</kbd> or <kbd>Space</kbd> opens the picker, and files can be dropped on it. Under a coarse pointer it says "Tap to choose" and takes less padding. Use it where picking files is the main task of the page (an import, a claim form); keep the compact field in a longer form.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * The drop zone look.
+ *
+ * `variant="dropzone"` makes the whole dashed area the control: click it, press Enter or Space, or
+ * drop files on it. Under touch it says "Tap to choose". The list, rules and value are the same as
+ * the field look's.
+ */
+@Component({
+  selector: 'app-example-file-input-dropzone',
+  imports: [BfFileInputComponent],
+  template: `
+    <bf-file-input
+      variant="dropzone"
+      label="Expense receipts"
+      helpText="Photos or PDFs of your receipts"
+      accept="image/*,.pdf"
+      multiple
+      [(value)]="receipts"
+    />
+  `,
+})
+export class FileInputDropzoneExampleComponent {
+  protected readonly receipts = signal<File[]>([]);
+}
+```
+
+## Rules and rejected files
+
+- `accept` takes the native syntax: MIME types (`application/pdf`), wildcards (`image/*`) and extensions (`.pdf`), comma-separated. The native picker filters with it, and dropped files are checked against it too, so a drop cannot get around it. Empty accepts every file.
+- `maxSize` is the largest file in bytes (`5 * 1024 * 1024` for 5 MB); the message shows it formatted ("Too large, max 5 MB").
+- `maxFiles` (with `multiple`) caps the whole list, counting the files already chosen.
+
+A file is checked for type, then size, then count. A file that breaks a rule never enters the value and never makes the field invalid: it is listed in red under the chosen files with the reason, until the next pick or drop or until the user dismisses it, and the screen reader hears "contract.exe was not added: Not an accepted type". `(rejected)` emits once per pick or drop with the refused files, each a `BfRejectedFile` with the `file`, the `reason` (`'type'`, `'size'` or `'count'`) and the `message` shown. The messages come from `provideBfLabels()` (`fileRejectedType`, `fileRejectedSize(max)`, `fileRejectedCount(max)`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFileInputComponent, type BfRejectedFile } from '@bitforgehq/ui';
+
+/**
+ * Accepted types, size and count.
+ *
+ * `accept`, `maxSize` (bytes) and `maxFiles` decide what is added. A file that breaks one never
+ * enters the value: it is listed in red with the reason until the next pick, and `rejected` emits it
+ * with its `reason` (`type`, `size` or `count`) and message.
+ */
+@Component({
+  selector: 'app-example-file-input-rules',
+  imports: [BfFileInputComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-file-input
+        label="Invoice scans"
+        helpText="PDF, PNG or JPEG, up to 5 MB each, at most 3 files"
+        accept=".pdf,image/png,image/jpeg"
+        multiple
+        [maxSize]="5 * 1024 * 1024"
+        [maxFiles]="3"
+        [(value)]="scans"
+        (rejected)="onRejected($event)"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        {{ lastRejected() }}
+      </p>
+    </div>
+  `,
+})
+export class FileInputRulesExampleComponent {
+  protected readonly scans = signal<File[]>([]);
+  protected readonly lastRejected = signal('Nothing rejected yet.');
+
+  protected onRejected(files: BfRejectedFile[]): void {
+    this.lastRejected.set(
+      `Rejected: ${files.map((item) => `${item.file.name} (${item.reason})`).join(', ')}.`,
+    );
+  }
+}
+```
+
+## Uploading
+
+The field never uploads: it hands the app the `File` objects the user chose. Send them when the user submits, with the app's own upload code: a data service that posts a `FormData` through `HttpClient`, a signed URL, or a storage SDK. Progress, retries and the server's answer belong to that code. With `name` set, the hidden native input carries the chosen files too, so a plain HTML form post includes them.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * Handing the files to your upload.
+ *
+ * The field only picks files. On Send, the app puts the `File[]` into a `FormData` and passes it to
+ * its own upload code; here a stand-in reports what it would send.
+ */
+@Component({
+  selector: 'app-example-file-input-upload',
+  imports: [BfButtonComponent, BfFileInputComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-file-input
+        label="Invoice attachments"
+        accept=".pdf,image/*"
+        multiple
+        class="self-stretch"
+        [(value)]="attachments"
+      />
+      <bf-button [disabled]="attachments().length === 0" (click)="send()">Send</bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class FileInputUploadExampleComponent {
+  protected readonly attachments = signal<File[]>([]);
+  protected readonly status = signal('Nothing sent yet.');
+
+  protected async send(): Promise<void> {
+    const body = new FormData();
+    for (const file of this.attachments()) {
+      body.append('attachments', file, file.name);
+    }
+    const sent = await this.upload(body);
+    this.status.set(`Sent ${sent} file(s).`);
+    this.attachments.set([]);
+  }
+
+  /** Your upload goes here: `HttpClient.post('/api/invoices/114/attachments', body)` in a data
+   * service, a signed URL or a storage SDK. This stand-in only counts the files it was given. */
+  private upload(body: FormData): Promise<number> {
+    return Promise.resolve(body.getAll('attachments').length);
+  }
+}
+```
+
+## With Signal Forms
+
+Bind the field with `[formField]` instead of `[(value)]`; touched, invalid, errors, disabled, readonly and required flow in, and the first error shows once the user has left the pick button. `required()` treats an empty list as filled (it checks for `''`, `false` and `null`), so it gives the label its marker only. Add a rule for the missing file:
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  FormField,
+  FormRoot,
+  form,
+  required,
+  requiredError,
+  validate,
+} from '@angular/forms/signals';
+import { BfButtonComponent, BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * A required file on Signal Forms.
+ *
+ * The value is a `File[]`, and `required()` does not count an empty list as empty: it gives the
+ * label its marker, and a `validate()` rule reports the missing file. `[formRoot]` runs the
+ * submission on submit.
+ */
+@Component({
+  selector: 'app-example-file-input-signal-forms',
+  imports: [FormField, FormRoot, BfButtonComponent, BfFileInputComponent],
+  template: `
+    <form [formRoot]="claim" class="flex flex-col items-start gap-3">
+      <bf-file-input
+        label="Signed contract"
+        accept=".pdf"
+        class="self-stretch"
+        [formField]="claim.contract"
+      />
+      <bf-button type="submit">Send claim</bf-button>
+    </form>
+  `,
+})
+export class FileInputSignalFormsExampleComponent {
+  private readonly model = signal<{ contract: File[] }>({ contract: [] });
+  protected readonly claim = form(
+    this.model,
+    (p) => {
+      required(p.contract);
+      validate(p.contract, ({ value }) =>
+        value().length === 0 ? requiredError({ message: 'Attach the signed contract' }) : undefined,
+      );
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+The rule there is `validate(p.contract, ({ value }) => value().length === 0 ? requiredError({ message: 'Attach the signed contract' }) : undefined)` next to `required(p.contract)`. Rejected files are not errors of the field; read them from `(rejected)` when the form needs to know.
+
+## Read-only and disabled
+
+`readonly` keeps the chosen files listed with no pick button, drop or remove buttons; with `multiple` the box shows the count ("2 files"), without it the file name. `disabled` greys the field out, ignores drops and takes the pick button out of the tab order.
+
+```ts
+import { Component } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/**
+ * Read-only and disabled.
+ *
+ * Read-only keeps the files listed with no pick button, drop or remove (with `multiple` the box
+ * shows the count); disabled greys the field out and takes it out of the tab order.
+ */
+@Component({
+  selector: 'app-example-file-input-states',
+  imports: [BfFileInputComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <bf-file-input label="Submitted documents" multiple readonly [value]="submitted" />
+      <bf-file-input label="Contract" disabled helpText="Unlocked once the quote is approved" />
+    </div>
+  `,
+})
+export class FileInputStatesExampleComponent {
+  protected readonly submitted = [
+    new File([new Uint8Array(182 * 1024)], 'invoice-2026-114.pdf', { type: 'application/pdf' }),
+    new File([new Uint8Array(96 * 1024)], 'delivery-note.pdf', { type: 'application/pdf' }),
+  ];
+}
+```
+
+## Sizes
+
+`sm` 32 px, `md` 40 px (default), `lg` 48 px for the field box, the same `BfSize` scale as `bf-input`, so a file field lines up with the text fields of a form; the pick button inside is 24, 28 or 36 px. Unset, `size` follows `provideBfDefaults()`'s `fieldSize`. The drop zone keeps one size.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfFileInputComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg file input sizes. */
+@Component({
+  selector: 'app-example-file-input-sizes',
+  imports: [BfFileInputComponent],
+  template: `
+    <div data-sizes class="flex flex-col gap-3">
+      <bf-file-input size="sm" label="Logo" accept="image/*" [(value)]="logo" />
+      <bf-file-input label="Price list" accept=".pdf,.xlsx" [(value)]="priceList" />
+      <bf-file-input size="lg" label="Company register extract" [(value)]="extract" />
+    </div>
+  `,
+})
+export class FileInputSizesExampleComponent {
+  protected readonly logo = signal<File[]>([]);
+  protected readonly priceList = signal<File[]>([]);
+  protected readonly extract = signal<File[]>([]);
+}
+```
+
+## Phones
+
+On a phone the pick button (or a tap on the drop zone) opens the platform's own picker, which on iOS and Android usually offers the photo library, the camera and the files app, filtered by `accept`. Dropping is a desktop gesture; under a coarse pointer the drop zone asks the user to tap instead. Under a coarse pointer the pick button and each remove button reach 44 px through an invisible extension.
+
+## Desktop
+
+Files dragged over the field box or the drop zone highlight it (`primary` border, `selected` background) and are added on drop, through the same rules as a pick. The pick button darkens on hover; the drop zone takes `surface-muted` on hover. The field box shows the `primary` border and the focus ring while the pick button has focus. Long file names are truncated with an ellipsis, the full name in a tooltip.
+
+## Theming
+
+- Field box: `border-strong` border (`danger-border` on error), `surface` background; while dragging, `primary` border and `selected` background. Read-only and disabled: `surface-muted` background, disabled with a `surface-sunken` border and `text-disabled` text.
+- Pick button: `primary-soft` background with `primary-strong` text (hover `primary-soft-hover`), as the tonal `bf-button`. Hint text: `text-muted`.
+- Drop zone: a 2 px dashed `border-strong` border on `surface`, `rounded-card`; the badge `primary-soft` with a `primary-strong` arrow. Under forced colours its border is `CanvasText` (`Highlight` while dragging, `GrayText` disabled).
+- File rows: `border` border on `surface`, `rounded-tile`; the thumbnail `surface-sunken` with `text-subtle` extension; the size `text-muted`. Rejected rows: the name and reason in `danger`.
+- Label, help and error text come from the `bf-field` wrapper (see its Theming section).
+
+## Accessibility
+
+The pick button is a native `<button>` named by the label and its own text ("Contract, Choose file") and described by the text beside it (the file name or the drop hint), the help and the error paragraph; `aria-invalid` and `aria-errormessage` are set once the field is touched and invalid. The drop zone is a `role="button"` element with `tabindex="0"`, named the same way ("Contract, Drag a file here or browse"). The native `<input type="file">` is visually hidden and out of the tab order. `required` gives the label its marker; there is no `aria-required`, which is not allowed on a button. Each remove button is named "Remove invoice.pdf", each rejected row's button "Dismiss setup.exe". A polite live region announces what happened ("2 files added", "invoice.pdf removed", "setup.exe was not added: Not an accepted type"). After a remove, focus moves to the next remove button, else the previous one, else the pick button. Without a visible `label`, give `ariaLabel` or `ariaLabelledby`: it takes the label's place at the start of the name, and the visible text still follows, so a speech-input user can say "Choose file". `focus()` focuses the pick button; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                              | Where                  | Action                                                                    |
+| ------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Field                  | Moves through the pick button (or drop zone) and each row's remove button |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Pick button, drop zone | Opens the native file picker                                              |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Remove button          | Removes the file and moves focus to the next row                          |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Dismiss button         | Hides the rejected file and returns focus to the pick button              |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                                                                           |
+| ---------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`        | `BfFileInputVariant` (`'field' \| 'dropzone'`)              | `'field'`   | The look: `field` (a compact field with a pick button, the default) or `dropzone`.                                                                                                                                    |
+| `multiple`       | `boolean`                                                   | `false`     | Allows several files: new picks and drops are added to the list. Off, a new file replaces the one chosen.                                                                                                             |
+| `accept`         | `string`                                                    | `''`        | The accepted file types, in the native `accept` syntax: MIME types, `type/*` wildcards and `.ext` extensions, comma-separated (`'.pdf,image/*'`). Empty accepts every file. Dropped files are checked against it too. |
+| `maxSize`        | `number \| undefined`                                       | `undefined` | Largest file size in bytes; a larger file is rejected. Unset allows any size.                                                                                                                                         |
+| `maxFiles`       | `number \| undefined`                                       | `undefined` | Most files in the value with `multiple`, counting those already chosen; files past it are rejected. Unset allows any number.                                                                                          |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step of the field box: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                                                                             |
+| `label`          | `string`                                                    | `''`        | Visible label above the control.                                                                                                                                                                                      |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when no visible label is rendered, read before the control's visible text ("Attachments, Choose files"). Ignored when `label` is set.                                                                 |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered, read before the control's visible text. Ignored when `label` is set.                                                                   |
+| `helpText`       | `string`                                                    | `''`        | Helper text under the control.                                                                                                                                                                                        |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                                                                                       |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control: no picking, dropping or removing, and the pick button is not focusable. Set by `[formField]`; do not bind it yourself.                                                                          |
+| `readonly`       | `boolean`                                                   | `false`     | Makes the control read-only: the files stay listed, with no pick button, drop or remove. Set by `[formField]`; do not bind it yourself.                                                                               |
+| `required`       | `boolean`                                                   | `false`     | Marks the control required (label marker). Set by `[formField]`; do not bind it yourself.                                                                                                                             |
+| `invalid`        | `boolean`                                                   | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                                                                      |
+| `touched`        | `boolean`                                                   | `false`     | Whether the user has left the field; errors show only once touched. Set by `[formField]`; do not bind it yourself.                                                                                                    |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms; the first message is shown once touched. Set by `[formField]`; do not bind it yourself.                                                                                          |
+| `name`           | `string`                                                    | `''`        | Native name attribute; set, the hidden native file input carries the chosen files, so a plain HTML form post includes them. Set by `[formField]`; do not bind it yourself.                                            |
+| `id`             | `string`                                                    | `generated` | Control id (the pick button's); generated when not set.                                                                                                                                                               |
+| `value`          | `File[]`                                                    | `[]`        | The chosen files; two-way bindable and bound by `[formField]`. Empty while nothing is chosen, at most one file while `multiple` is off. Two-way: `[(value)]`.                                                         |
+
+## Outputs
+
+| Name       | Payload            | Description                                                                                             |
+| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `changed`  | `File[]`           | Emitted with the new files right after the user adds or removes one, not on a model write.              |
+| `rejected` | `BfRejectedFile[]` | Emitted once per pick or drop in which at least one file broke a rule, with those files.                |
+| `focused`  | `FocusEvent`       | Emitted when the pick button gains focus.                                                               |
+| `blurred`  | `FocusEvent`       | Emitted when the pick button loses focus.                                                               |
+| `touch`    | `void`             | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the pick button; Signal Forms calls it from `focusBoundControl()`. Read-only has no
+pick button, so nothing is focused.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Set `accept` and `maxSize` to what the server takes, so the user hears about a wrong file at once.
+- Upload on submit, from the `File[]` the field holds.
+- Use the drop zone where picking files is the page's main task.
+
+### Don't
+
+- Don't rely on `required()` alone; add the `validate()` rule for an empty list.
+- Don't bind both `[(value)]` and `[formField]`.
+- Don't use it for one picture the user should see; use `bf-image-input`.
+
+## Migration notes
+
+### 0.5.0
+
+New: `bf-file-input`, a file picker field. The `field` look (the default) is a tonal "Choose
+file" button inside a field box that also takes dropped files; `variant="dropzone"` is a dashed
+area that is the control as a whole (click, Enter, Space or a drop). The chosen files are listed
+under it with a thumbnail (images) or the extension, the name, the size and a remove button. The
+value is a `File[]` (one file at most without `multiple`), bound with `[(value)]` or
+`[formField]`. `accept` (MIME types, `type/*` and `.ext`, checked on drops too), `maxSize`
+(bytes) and `maxFiles` decide what is added; a file that breaks one never enters the value and
+never sets `invalid`: it shows as a red row with the reason until the next pick and is emitted
+through `rejected` (new types `BfRejectedFile`: `file`, `reason`, `message`; and
+`BfRejectedFileReason`: `'type' | 'size' | 'count'`). It only picks; uploading stays with the app. New type `BfFileInputVariant`, new label
+keys `fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`,
+`fileInputRemove`, `fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`,
+`fileInputRemoved`, `fileInputCount`, `fileRejectedType`, `fileRejectedSize` and
+`fileRejectedCount`. `@bitforgehq/ui/testing`: new `BfFileInputHarness` (`addFiles()` drops files
+through the same rules, `getFileNames()`, `getRejected()`, `removeFile()`, `getVariant()`).

package/ai/components/header.md

@@ -380,7 +380,7 @@ whichever `h1` is active (the large title's when `largeTitle` is true, the toolb
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 import { BfHeaderComponent } from '@bitforgehq/ui/mobile';
 
 /** A workspace picker in the title's place. */