@bitforgehq/ui 0.4.0 → 0.5.0-next.3

package/ai/components/image-input.md

@@ -0,0 +1,368 @@
+# bf-image-input
+
+Single-image picker with a round or square preview tile and replace or remove
+
+`BfImageInputComponent` from `@bitforgehq/ui` · Forms · since 0.5.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-image-input overview.
+ *
+ * Live demo of `bf-image-input`: a round profile picture bound to a signal, limited to PNG and JPEG
+ * up to 2 MB, with a line that names the picked image; then a square company logo.
+ */
+@Component({
+  selector: 'app-example-image-input-overview',
+  imports: [BfImageInputComponent],
+  template: `
+    <div class="flex flex-col gap-5">
+      <bf-image-input
+        label="Profile picture"
+        helpText="PNG or JPEG, up to 2 MB"
+        accept="image/png,image/jpeg"
+        [maxSize]="2 * 1024 * 1024"
+        [(value)]="avatar"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <bf-image-input label="Company logo" shape="square" helpText="Shown on your invoices" />
+    </div>
+  `,
+})
+export class ImageInputOverviewExampleComponent {
+  readonly avatar = signal<File | null>(null);
+
+  readonly status = computed(() => {
+    const file = this.avatar();
+    return file ? `Picked: ${file.name}.` : 'No picture picked.';
+  });
+}
+```
+
+## Overview
+
+Single-image picker for an avatar, logo or cover: a round or square tile that shows the image
+(or a camera glyph while empty), with the label, help text and Upload/Replace and Remove buttons
+beside it. Clicking the tile or Upload opens the native picker; an image dropped on the tile is
+taken too. `src` shows an image the app already has until the user picks a new one or removes
+it. A pick that breaks `accept` or `maxSize` keeps the current image, shows the reason under the
+buttons and is emitted through `rejected`. It only picks: uploading is the app's job. Bind
+`[(value)]` directly or `[formField]` from a signal form.
+
+A single-image picker for an avatar, a logo or a cover: a round or square tile that shows the image (or a camera glyph while empty), with the label, help text and Upload (Replace once there is an image) and Remove buttons beside it. Clicking the tile or Upload opens the native picker; an image dropped on the tile is taken too. `src` shows the image the app already has. It only picks: uploading is the app's job.
+
+## When to use
+
+Use `bf-image-input` for one picture the user should see while choosing it: a profile picture, a company logo, a cover image. Use [bf-file-input](https://bitforge-ui.web.app/components/file-input) instead for documents, for several files, or for images that are attachments rather than a picture of something (scans, receipts). To only show a person's picture, use [bf-avatar](https://bitforge-ui.web.app/components/avatar).
+
+## Basic usage
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-image-input overview.
+ *
+ * Live demo of `bf-image-input`: a round profile picture bound to a signal, limited to PNG and JPEG
+ * up to 2 MB, with a line that names the picked image; then a square company logo.
+ */
+@Component({
+  selector: 'app-example-image-input-overview',
+  imports: [BfImageInputComponent],
+  template: `
+    <div class="flex flex-col gap-5">
+      <bf-image-input
+        label="Profile picture"
+        helpText="PNG or JPEG, up to 2 MB"
+        accept="image/png,image/jpeg"
+        [maxSize]="2 * 1024 * 1024"
+        [(value)]="avatar"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <bf-image-input label="Company logo" shape="square" helpText="Shown on your invoices" />
+    </div>
+  `,
+})
+export class ImageInputOverviewExampleComponent {
+  readonly avatar = signal<File | null>(null);
+
+  readonly status = computed(() => {
+    const file = this.avatar();
+    return file ? `Picked: ${file.name}.` : 'No picture picked.';
+  });
+}
+```
+
+`value` is the picked `File`, `null` while none is picked. `accept` defaults to `image/*`. `(changed)` emits the new image (or `null` after Remove) right after a user change; a programmatic write does not emit.
+
+## Shapes and sizes
+
+`shape="round"` (the default) is a circle for a person; `shape="square"` a rounded square for a logo or a cover. The tile is 64, 96 or 128 px for `sm`, `md` and `lg`; unset, `size` follows `provideBfDefaults()`'s `fieldSize` (`md` by default). The square's radius grows with the tile.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * Round and square tiles.
+ *
+ * `shape="round"` (the default) for a person's picture, `shape="square"` for a logo or a cover.
+ */
+@Component({
+  selector: 'app-example-image-input-shapes',
+  imports: [BfImageInputComponent],
+  template: `
+    <div class="flex flex-col gap-5">
+      <bf-image-input label="Profile picture" [(value)]="avatar" />
+      <bf-image-input label="Team logo" shape="square" [(value)]="logo" />
+    </div>
+  `,
+})
+export class ImageInputShapesExampleComponent {
+  protected readonly avatar = signal<File | null>(null);
+  protected readonly logo = signal<File | null>(null);
+}
+```
+
+## An image the app already has
+
+Bind `[(src)]` to the URL of the saved picture. The tile shows it while `value` is null; a pick shows the new image instead, and Remove clears both `value` and `src`. So on save the app can tell three cases apart:
+
+- `value` set: the user picked a new picture; upload it.
+- `value` null and `src` null: the user removed the picture; delete it.
+- `value` null and `src` unchanged: keep the current picture.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * An image the app already has.
+ *
+ * `[(src)]` shows the current picture until the user picks a new one or removes it. Remove sets
+ * both `value` and `src` to null, so on save the app can tell the three cases apart: a new picture
+ * (`value` set), removed (both null), or keep (`value` null, `src` unchanged).
+ */
+@Component({
+  selector: 'app-example-image-input-existing',
+  imports: [BfImageInputComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-image-input label="Profile picture" [(value)]="picked" [(src)]="currentUrl" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ onSave() }}</p>
+    </div>
+  `,
+})
+export class ImageInputExistingExampleComponent {
+  /** The URL the server returned for the saved picture. */
+  private readonly savedUrl = 'apple-touch-icon.png';
+  protected readonly currentUrl = signal<string | null>(this.savedUrl);
+  protected readonly picked = signal<File | null>(null);
+
+  /** What a save would do. */
+  protected readonly onSave = computed(() => {
+    const file = this.picked();
+    if (file) {
+      return `On save: upload ${file.name}.`;
+    }
+    return this.currentUrl() === null
+      ? 'On save: delete the current picture.'
+      : 'On save: keep the current picture.';
+  });
+}
+```
+
+## Rules and rejected images
+
+`accept` (native syntax, `image/png,image/jpeg`) and `maxSize` (bytes) decide what is taken; a dropped image is checked against them too. A refused image never enters the value and never makes the field invalid: the current image stays, the reason shows in a line under the buttons ("Too large, max 2 MB") until the next pick or Remove, and `(rejected)` emits a `BfRejectedFile[]` (`file`, `reason` `'type'` or `'size'`, `message`). If several images are dropped at once, the first acceptable one is taken and the others are rejected with the reason `'count'`.
+
+## Uploading
+
+The control never uploads: it hands the app the `File` the user picked. Upload it on save with the app's own code (a `FormData` posted through `HttpClient` in a data service, a signed URL, a storage SDK), then set `src` to the URL the server returns and `value` back to `null`. Cropping and resizing, when needed, also happen in the app before the upload. With `name` set, the hidden native input carries the picked image, so a plain HTML form post includes it.
+
+## With Signal Forms
+
+Bind `[formField]` to a `File | null` field. The saved picture (`src`) counts as filled, but `required()` sees only the null `value` and would report the field empty. So set the label's marker with the `REQUIRED` metadata, `metadata(p.avatar, REQUIRED, () => true)`, and add a rule that reads the `src` the app holds: `validate(p.avatar, ({ value }) => value() === null && !this.avatarUrl() ? requiredError({ message: 'Add a profile picture' }) : undefined)`. Without a `src`, `required(p.avatar)` alone is enough.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  FormField,
+  FormRoot,
+  REQUIRED,
+  form,
+  metadata,
+  requiredError,
+  validate,
+} from '@angular/forms/signals';
+import { BfButtonComponent, BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * A required picture on Signal Forms.
+ *
+ * The picture the app already has (`src`) fills the field, but `required()` sees only the null
+ * `value` and would report it missing. So the `REQUIRED` metadata gives the label its marker, and a
+ * `validate()` rule reports a missing picture only while there is neither a picked image nor a
+ * `src`.
+ */
+@Component({
+  selector: 'app-example-image-input-signal-forms',
+  imports: [FormField, FormRoot, BfButtonComponent, BfImageInputComponent],
+  template: `
+    <form [formRoot]="profile" class="flex flex-col items-start gap-4">
+      <bf-image-input label="Profile picture" [formField]="profile.avatar" [(src)]="avatarUrl" />
+      <bf-button type="submit">Save profile</bf-button>
+    </form>
+  `,
+})
+export class ImageInputSignalFormsExampleComponent {
+  /** The saved picture's URL; Remove sets it to null. */
+  protected readonly avatarUrl = signal<string | null>('apple-touch-icon.png');
+  private readonly model = signal<{ avatar: File | null }>({ avatar: null });
+  protected readonly profile = form(
+    this.model,
+    (p) => {
+      metadata(p.avatar, REQUIRED, () => true);
+      validate(p.avatar, ({ value }) =>
+        value() === null && !this.avatarUrl()
+          ? requiredError({ message: 'Add a profile picture' })
+          : undefined,
+      );
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Read-only and disabled
+
+`readonly` shows the image in a plain tile, with no buttons and no drop. `disabled` greys the tile and buttons out, ignores drops and takes them out of the tab order.
+
+```ts
+import { Component } from '@angular/core';
+import { BfImageInputComponent } from '@bitforgehq/ui';
+
+/**
+ * Read-only and disabled.
+ *
+ * Read-only shows the picture in a plain tile with no buttons and takes no drop; disabled greys
+ * the tile and buttons out and takes them out of the tab order.
+ */
+@Component({
+  selector: 'app-example-image-input-states',
+  imports: [BfImageInputComponent],
+  template: `
+    <div class="flex flex-col gap-5">
+      <bf-image-input label="Company logo" shape="square" readonly src="apple-touch-icon.png" />
+      <bf-image-input label="Profile picture" disabled helpText="Managed by your organisation" />
+    </div>
+  `,
+})
+export class ImageInputStatesExampleComponent {}
+```
+
+## Phones
+
+On a phone the tile and Upload open the platform's own picker, which usually offers the photo library and the camera, filtered by `accept`. Dropping is a desktop gesture. Under a coarse pointer the Upload and Remove buttons reach 44 px through an invisible extension; the tile is at least 64 px.
+
+## Desktop
+
+An image dragged over the tile highlights it (`primary` border, `selected` background) and is taken on drop. The tile takes `surface-muted` on hover, with the pointer cursor; the buttons are `bf-button`'s text variant. The tile shows the focus ring on keyboard focus, and the label takes the focus colour while the tile or a button has focus.
+
+## Theming
+
+- Tile: 2 px border, dashed `border-strong` while empty and solid `border` with an image; `danger-border` on error; `primary` with a `selected` background while dragging. Empty glyph: `text-subtle`. Read-only: `surface-muted`. Disabled: `surface-sunken` border, `surface-muted` background, `text-disabled` glyph. Under forced colours the border is `CanvasText` (`Highlight` while dragging, `GrayText` disabled).
+- Round tiles are `rounded-full`; square ones `rounded-tile`, `rounded-field` or `rounded-card` with the size.
+- Upload / Replace: the text `bf-button`. Remove: `danger` text, `danger-soft` on hover. The rejection line: `danger`.
+- Label, help and error text come from the `bf-field` wrapper (see its Theming section).
+
+## Accessibility
+
+The tile is a native `<button>` named "Choose image" (`imageInputChoose`; `ariaLabel` replaces it while there is no visible label) and described by the label, the help and the error paragraph, so a screen reader hears "Choose image, Profile picture". `aria-invalid` and `aria-errormessage` are set once touched and invalid. Upload / Replace and Remove are native buttons described by the label, so "Remove" says what it removes. The preview image is decorative (`alt=""`): the label names what it shows. 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. The rejection reason shows at once under the buttons, and a polite live region announces it. After Remove, focus returns to the tile. `focus()` focuses the tile; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                              | Where        | Action                                                           |
+| ------------------------------------------------ | ------------ | ---------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Control      | Moves through the tile, Upload / Replace and Remove              |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Tile, Upload | Opens the native file picker                                     |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Remove       | Clears the picked and the existing image; focus goes to the tile |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                              |
+| ---------------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `shape`          | `BfImageInputShape` (`'round' \| 'square'`)                 | `'round'`   | The tile's shape: `round` (a circle, the default) or `square` (a rounded square).                                                                                        |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Tile size: sm 64, md 96, lg 128 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                                                  |
+| `accept`         | `string`                                                    | `'image/*'` | The accepted file types, in the native `accept` syntax (`'image/png,image/jpeg'`); dropped files are checked against it too.                                             |
+| `maxSize`        | `number \| undefined`                                       | `undefined` | Largest file size in bytes; a larger image is rejected. Unset allows any size.                                                                                           |
+| `label`          | `string`                                                    | `''`        | Visible label beside the tile.                                                                                                                                           |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name of the tile when no visible label is rendered, in place of "Choose image". Ignored when `label` is set.                                                  |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the tile when no visible label is rendered. Ignored when `label` is set.                                                               |
+| `helpText`       | `string`                                                    | `''`        | Helper text under the label.                                                                                                                                             |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                                          |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control: the tile and buttons are disabled and drops are ignored. Set by `[formField]`; do not bind it yourself.                                            |
+| `readonly`       | `boolean`                                                   | `false`     | Makes the control read-only: the image shows in a plain tile, with no buttons or drop. Set by `[formField]`; do not bind it yourself.                                    |
+| `required`       | `boolean`                                                   | `false`     | Marks the control required (label marker). A `value` or a `src` fills it; see the docs for a validator that counts `src`. 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 picked image, so a plain HTML form post includes it. Set by `[formField]`; do not bind it yourself. |
+| `id`             | `string`                                                    | `generated` | Control id (the tile's); generated when not set.                                                                                                                         |
+| `value`          | `File \| null`                                              | `null`      | The picked image; two-way bindable and bound by `[formField]`. Null while none is picked. Two-way: `[(value)]`.                                                          |
+| `src`            | `string \| null`                                            | `null`      | URL of an image the app already has (the current avatar), shown while `value` is null. Remove sets it to null; two-way bindable. Two-way: `[(src)]`.                     |
+
+## Outputs
+
+| Name       | Payload            | Description                                                                                                                     |
+| ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `changed`  | `File \| null`     | Emitted with the new image (or null after Remove) right after a user change, not on a model write.                              |
+| `rejected` | `BfRejectedFile[]` | Emitted once per pick or drop in which a file broke a rule, with those files.                                                   |
+| `focused`  | `FocusEvent`       | Emitted when the tile gains focus.                                                                                              |
+| `blurred`  | `FocusEvent`       | Emitted when the tile loses focus.                                                                                              |
+| `touch`    | `void`             | Emitted on blur of the tile or a button so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the tile; Signal Forms calls it from `focusBoundControl()`. Read-only has no button, so
+nothing is focused.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Bind `[(src)]` to the saved picture, and compare `value` and `src` on save to know what changed.
+- Set `accept` and `maxSize` to what the server takes.
+- Use `square` for logos and covers, `round` for people.
+
+### Don't
+
+- Don't use it for several files or documents; use `bf-file-input`.
+- Don't bind both `[(value)]` and `[formField]`.
+- Don't count on `required()` while a `src` can fill the field; use the `validate()` rule.
+
+## Migration notes
+
+### 0.5.0
+
+New: `bf-image-input`, a single-image picker for an avatar, logo or cover: a `round` or `square`
+tile (`shape`, new type `BfImageInputShape`; 64, 96 or 128 px with `size`) that shows the image or
+a camera glyph, with Upload/Replace and Remove beside it. The value is a `File | null`. `src`, a
+two-way `model()`, shows the image the app already has; Remove clears both `value` and `src`, so
+the app can tell a new picture (`value` set), a removed one (both null) and an unchanged one
+(`src` kept, `value` null) apart. `accept` (default `image/*`) and `maxSize` refuse an image
+without touching the current one: the reason shows under the buttons and `rejected` emits it. It
+only picks; uploading stays with the app. New label keys `imageInputChoose`, `imageInputUpload`,
+`imageInputReplace` and `imageInputRemove`. `@bitforgehq/ui/testing`: new `BfImageInputHarness`
+(`addFile()`, `hasPreview()`, `getPreviewSrc()`, `remove()`, `getRejectedMessage()`).