@bitforgehq/ui 0.3.0

package/ai/components/alert.md

@@ -0,0 +1,376 @@
+# bf-alert
+
+Inline status message in four tones with a title and an optional dismiss button
+
+`BfAlertComponent` from `@bitforgehq/ui` · Feedback · since 0.1.0
+
+## Example
+
+```ts
+import { Component, ElementRef, signal, viewChild } from '@angular/core';
+import { BfAlertComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/** Focuses the native button inside a `bf-button` host (a type guard, not an assertion). */
+function focusButtonIn(host: unknown): void {
+  if (host instanceof HTMLElement) {
+    host.querySelector('button')?.focus();
+  }
+}
+
+/**
+ * The bf-alert overview.
+ *
+ * Live demo of `bf-alert`: "Save" inserts an `announce` success alert (a new one per press, so
+ * each is heard), and dismissing the `urgent` danger alert moves focus to "Save".
+ */
+@Component({
+  selector: 'app-example-alert-overview',
+  imports: [BfAlertComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap gap-2">
+        <bf-button #saveButton size="sm" (clicked)="save()">Save</bf-button>
+        @if (!showDangerAlert()) {
+          <bf-button variant="tonal" size="sm" (clicked)="showDangerAlert.set(true)">
+            Show again
+          </bf-button>
+        }
+      </div>
+      @for (id of saves(); track id) {
+        <bf-alert variant="success" title="Saved" announce>Your changes are live.</bf-alert>
+      }
+      @if (showDangerAlert()) {
+        <bf-alert
+          variant="danger"
+          title="Sync failed"
+          urgent
+          [dismissible]="true"
+          (dismissed)="dismiss()"
+        >
+          Check your connection and try again.
+        </bf-alert>
+      }
+    </div>
+  `,
+})
+export class AlertOverviewExampleComponent {
+  readonly showDangerAlert = signal(true);
+  /** Holds only the latest save; a new id replaces the alert, so each press is announced. */
+  readonly saves = signal<readonly number[]>([]);
+  private readonly saveButton = viewChild.required('saveButton', {
+    read: ElementRef,
+  });
+  private nextSave = 0;
+
+  save(): void {
+    this.saves.set([this.nextSave++]);
+  }
+
+  /** The dismiss button is about to disappear; hand focus to the control that caused the alert. */
+  dismiss(): void {
+    this.showDangerAlert.set(false);
+    focusButtonIn(this.saveButton().nativeElement);
+  }
+}
+```
+
+## Overview
+
+Inline message for the outcome of an action or the state of a screen, in a polite `status`
+region (`urgent` makes it an assertive `alert`; `announce` makes an inserted alert heard).
+
+Alerts report the outcome of an action or the state of a screen inline, in the flow of the page. Every alert is a polite live region (`role="status"`); `urgent` makes it interrupt assistive tech (`role="alert"`), and `announce` makes an alert inserted after an action be heard. For a message that needs no permanent home, use a toast instead.
+
+## When to use
+
+Use `bf-alert` for a message that belongs to a place on the page and stays until the state changes: a failed sync above a list, a warning at the top of a form. Use [BfDesktopToastService](https://bitforge-ui.web.app/api/bf-desktop-toast-service) instead for a passing confirmation ("Saved"), and [BfDialogService](https://bitforge-ui.web.app/api/bf-dialog-service) `confirm()` when the user must answer before going on.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfAlertComponent } from '@bitforgehq/ui';
+
+/** An info alert with a title and a message. */
+@Component({
+  selector: 'app-example-alert-basic',
+  imports: [BfAlertComponent],
+  template: `<bf-alert title="Saved">Your changes are live.</bf-alert>`,
+})
+export class AlertBasicExampleComponent {}
+```
+
+## Variants
+
+`neutral` (default) is a plain note; `success`, `warning` and `danger` carry meaning through color. `danger` also gets a visible border. The variant does not change the `role`: add `urgent` to a danger alert that must interrupt (see Announcements).
+
+```ts
+import { Component } from '@angular/core';
+import { BfAlertComponent } from '@bitforgehq/ui';
+
+/** The success, warning and danger alerts. */
+@Component({
+  selector: 'app-example-alert-variants',
+  imports: [BfAlertComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-alert variant="success" title="Saved">Your changes are live.</bf-alert>
+      <bf-alert variant="warning" title="Storage almost full">You have 200 MB left.</bf-alert>
+      <bf-alert variant="danger" title="Sync failed">Check your connection and try again.</bf-alert>
+    </div>
+  `,
+})
+export class AlertVariantsExampleComponent {}
+```
+
+## Announcements
+
+Screen readers announce a live region's changes, not a region that appears with its text already
+in it, so an alert rendered after an action ("Saved") is often missed. Set `announce` on such an
+alert: its region renders empty first and fills on the next frame, which is a change screen
+readers announce. `announce` is read once, when the alert is created; to announce again, render
+a new alert (for example with `@for (id of saves(); track id)` holding only the latest id).
+
+`urgent` switches the region from `status` (polite: read when the screen reader is idle) to
+`alert` (assertive: read at once, interrupting). Use it only for an error that needs attention
+now; it is not tied to `variant`. The two combine: `urgent announce` for an error that appears
+after an action.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfAlertComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * Alerts that announce themselves when they appear.
+ *
+ * Save shows a polite "Saved" alert; Fail sync an urgent one. Both render after an action, so
+ * both set `announce`.
+ */
+@Component({
+  selector: 'app-example-alert-announce',
+  imports: [BfAlertComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap gap-2">
+        <bf-button (clicked)="save()">Save</bf-button>
+        <bf-button variant="outline" (clicked)="syncError.set(true)">Fail sync</bf-button>
+      </div>
+      @if (saved()) {
+        <bf-alert variant="success" title="Saved" announce>Your changes are live.</bf-alert>
+      }
+      @if (syncError()) {
+        <bf-alert variant="danger" title="Sync failed" urgent announce
+          >Check your connection.</bf-alert
+        >
+      }
+    </div>
+  `,
+})
+export class AlertAnnounceExampleComponent {
+  protected readonly saved = signal(false);
+  protected readonly syncError = signal(false);
+
+  protected save(): void {
+    this.saved.set(true);
+    this.syncError.set(false);
+  }
+}
+```
+
+An alert present when the page loads needs neither: it is read with the page.
+
+## Dismissible
+
+Set `dismissible` to show a close button and handle `dismissed` to remove the alert from your state; the component never hides itself. The button sits outside the `status`/`alert` region so assistive tech reads the message without the control interrupting it. Its accessible name is `dismissLabel` (default `provideBfLabels()`'s `dismiss`, "Dismiss") followed by the title, "Dismiss: Sync failed", so two dismissible alerts on a page have distinct buttons; without a `title` it is the label alone.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfAlertComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/**
+ * A dismissible alert with a Retry action.
+ *
+ * `dismissed` removes it from the state; the component never hides itself.
+ */
+@Component({
+  selector: 'app-example-alert-dismissible',
+  imports: [BfAlertComponent, BfButtonComponent],
+  template: `
+    @if (error()) {
+      <bf-alert
+        variant="danger"
+        title="Sync failed"
+        [dismissible]="true"
+        (dismissed)="error.set(false)"
+      >
+        Check your connection.
+        <bf-button bfSlot="actions" variant="text" size="sm" (clicked)="retry()">Retry</bf-button>
+      </bf-alert>
+    } @else {
+      <bf-button variant="outline" (clicked)="error.set(true)">Show the error again</bf-button>
+    }
+  `,
+})
+export class AlertDismissibleExampleComponent {
+  protected readonly error = signal(true);
+
+  protected retry(): void {
+    this.error.set(false);
+  }
+}
+```
+
+## Focus after dismissal
+
+The dismiss button disappears with the alert, and focus would fall back to the page's start. The
+widget cannot know where focus belongs, so move it in your `dismissed` handler: to the next alert's
+dismiss button, or to the control that caused the alert.
+
+```ts
+import { Component, ElementRef, signal, viewChild } from '@angular/core';
+import { BfAlertComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/** Focuses the native button inside a `bf-button` host (a type guard, not an assertion). */
+function focusButtonIn(host: unknown): void {
+  if (host instanceof HTMLElement) {
+    host.querySelector('button')?.focus();
+  }
+}
+
+/**
+ * Moving focus after a dismissal.
+ *
+ * The dismiss button leaves with the alert, so the `dismissed` handler moves focus back to the
+ * Save button that caused it.
+ */
+@Component({
+  selector: 'app-example-alert-focus',
+  imports: [BfAlertComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      @if (error(); as message) {
+        <bf-alert
+          variant="danger"
+          title="Save failed"
+          [dismissible]="true"
+          (dismissed)="clearError()"
+        >
+          {{ message }}
+        </bf-alert>
+      }
+      <bf-button #saveButton (clicked)="error.set('The server did not answer.')">Save</bf-button>
+    </div>
+  `,
+})
+export class AlertFocusExampleComponent {
+  private readonly saveButton = viewChild.required('saveButton', {
+    read: ElementRef,
+  });
+  protected readonly error = signal<string | null>('The server did not answer.');
+
+  protected clearError(): void {
+    this.error.set(null);
+    focusButtonIn(this.saveButton().nativeElement);
+  }
+}
+```
+
+## Desktop
+
+The message itself has no hover or pointer state; it is not interactive. The dismiss button fades on hover with the pointer cursor and shows its focus ring on keyboard focus only. It is 32 px with a 44 px hit area at every size. Alerts span their container, so on a wide desktop page put them in the content column, not across the full viewport.
+
+## Theming
+
+Consumes tokens by variant, background then text:
+
+- `neutral`: `surface-sunken` / `text`
+- `success`: `success-soft` / `success`
+- `warning`: `warning-soft` / `warning`
+- `danger`: `danger-soft` / `danger`, with a visible `danger-border` border
+- Dismiss button focus ring: `ring`; its shape is `rounded-control` (`--radius-control`)
+
+## Accessibility
+
+The message region's `role` is `status` (polite, an implicit `aria-live="polite"`) in every variant and `alert` (assertive) with `urgent` ([APG alert pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alert/)); only a change inside a live region is announced, so `announce` renders the region empty and fills it a frame later, which is how an alert inserted after an action meets [WCAG 4.1.3 Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages) without moving focus. The dismiss button sits outside that region so it doesn't get read as part of the message; its accessible name is `dismissLabel` (else `provideBfLabels()`'s `dismiss`, "Dismiss") plus ": " and the `title`, so every dismiss button on a page is told apart. After a dismissal the host moves focus (see Focus after dismissal); the widget never does. Title and body break long words anywhere, and while `dismissible` the text column reserves the button's width, so no text runs under the ×. Its focus-visible ring uses the `ring` token.
+
+### Keyboard
+
+| Key                                 | Action                                                                                          |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves focus to the dismiss button (with `dismissible`)                                          |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Activates the dismiss button: emits `dismissed`; your handler removes the alert and moves focus |
+
+## Inputs
+
+| Name           | Type                                                                 | Default     | Description                                                                                                                                                                            |
+| -------------- | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`      | `BfAlertVariant` (`'neutral' \| 'success' \| 'warning' \| 'danger'`) | `'neutral'` | Meaning of the message.                                                                                                                                                                |
+| `title`        | `string`                                                             | `''`        | Bold first line.                                                                                                                                                                       |
+| `dismissible`  | `boolean`                                                            | `false`     | Shows a dismiss button that emits `dismissed`; the host decides whether to hide the alert.                                                                                             |
+| `urgent`       | `boolean`                                                            | `false`     | `role="alert"` (assertive) instead of `status`; for errors that need attention now.                                                                                                    |
+| `announce`     | `boolean`                                                            | `false`     | Renders the live region empty and fills it on the next frame, so an alert inserted after an action is announced; read once, when the alert is created.                                 |
+| `dismissLabel` | `string`                                                             | `''`        | Accessible name of the dismiss button (empty falls back to `provideBfLabels()`'s `dismiss`, "Dismiss"); with a `title` it becomes the label, a colon and the title ("Dismiss: Saved"). |
+
+## Outputs
+
+| Name        | Payload | Description                                 |
+| ----------- | ------- | ------------------------------------------- |
+| `dismissed` | `void`  | Emitted when the dismiss button is pressed. |
+
+## Slots
+
+- `icon`: An icon before the text, such as a `bf-icon`.
+- `default`: The message, under the title.
+- `actions`: Buttons under the message, such as Retry.
+
+## Notes
+
+### Do
+
+- Pass a `title`; it is the first thing scanned and read aloud.
+- Use `danger` only for something the user must act on now, and add `urgent` when it must interrupt.
+- Set `announce` on an alert you render in response to an action.
+
+### Don't
+
+- Don't stack more than one alert at a time; resolve or dismiss the first.
+- Don't use `bf-alert` for a message that disappears on its own; that is a toast.
+- Don't make every alert `urgent`; an assertive region cuts off whatever the user is hearing.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** `dismissLabel` defaults to `''` and falls back to `provideBfLabels()`'s `dismiss`
+("Dismiss"); the rendered English default is unchanged.
+
+**Behaviour:** the dismiss button uses `rounded-control` (`--radius-control`).
+
+**Behaviour:** the role no longer follows the variant: the region is `role="status"` (polite)
+unless the new `urgent` input makes it `role="alert"` (assertive), in any variant. Migration: add
+`urgent` to danger alerts that must interrupt (see Migration 15).
+
+New `announce` input: the live region renders empty and fills on the next frame, so an alert
+inserted after an action is announced (APG alert, WCAG 4.1.3); it is read once, at creation.
+
+**Behaviour:** with a `title` the dismiss button is named `<dismissLabel>: <title>` ("Dismiss:
+Sync failed"), so two dismissible alerts have distinct buttons (see Migration 16). The docs show
+moving focus in the `dismissed` handler; the widget never moves it.
+
+JSDoc of `alert.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon`, `default`, `actions`. No behaviour change.
+
+### 0.2.0
+
+The body text is `text-label` (15 px, was 14) like other body copy; the dismiss glyph is
+`text-heading font-normal` (18 px, was 20; the glyph keeps its regular weight).
+
+Fixed: the dismiss button shows a pointer cursor.
+
+Fixed: the title and body break long words anywhere (`wrap-anywhere`), and a dismissible alert's text
+column reserves the dismiss button's width (`pe-10`, was `pr-12` without word breaking), so a long
+word no longer runs under the ×. The dismiss button is placed with `end-3` (was `right-3`).
+
+### 0.1.0
+
+New `bf-alert`: an inline `role="status"` (`role="alert"` for `danger`) message with `neutral` (default), `success`, `warning` and `danger` variants, an `icon` slot, a `title`, and an `actions` slot. `dismissible` shows a close button that emits `dismissed`; the component itself never hides. The dismiss button now renders as a sibling of the `role="status"`/`role="alert"` element (both wrapped in an outer `div`) instead of inside it, so assistive tech reading the status/alert region doesn't also announce the dismiss control as part of the message; the visual position (absolute, top-right) is unchanged. Added `dismissLabel` (default `"Dismiss"`) to customize the button's accessible name. The 32 px dismiss button now extends its hit area to 44 px with `after:-inset-1.5`, a self-contained control so the `::after` extension is the right tool here (unlike a control over projected content).

package/ai/components/avatar.md

@@ -0,0 +1,146 @@
+# bf-avatar
+
+Round avatar showing a photo or initials, in three sizes and four color variants
+
+`BfAvatarComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-avatar overview.
+ *
+ * Live demo of `bf-avatar`: the three sizes and the four background variants.
+ */
+@Component({
+  selector: 'app-example-avatar-overview',
+  imports: [BfAvatarComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="flex flex-wrap items-center gap-3">
+        <bf-avatar initials="JK" size="sm" />
+        <bf-avatar initials="AR" size="md" />
+        <bf-avatar initials="LM" size="lg" />
+      </div>
+      <div class="flex flex-wrap items-center gap-3">
+        <bf-avatar initials="TI" variant="tint" />
+        <bf-avatar initials="IN" variant="ink" />
+        <bf-avatar initials="WA" variant="warning" />
+        <bf-avatar initials="NE" variant="neutral" />
+      </div>
+    </div>
+  `,
+})
+export class AvatarOverviewExampleComponent {}
+```
+
+## Overview
+
+Round avatar showing a photo or initials.
+
+Avatars identify people in lists, headers and profile screens. Without an image they show initials on a tinted circle.
+
+## When to use
+
+Use `bf-avatar` to identify a person or an account next to their name: a list row, a comment, a profile header. Use [bf-icon](https://bitforge-ui.web.app/components/icon) instead for things that are not people (a file type, a project), and [bf-badge](https://bitforge-ui.web.app/components/badge) for a status shown beside the avatar.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent } from '@bitforgehq/ui';
+
+/** An avatar with initials and one with an image. */
+@Component({
+  selector: 'app-example-avatar-basic',
+  imports: [BfAvatarComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <bf-avatar initials="LM" />
+      <bf-avatar src="apple-touch-icon.png" alt="Bitforge" />
+    </div>
+  `,
+})
+export class AvatarBasicExampleComponent {}
+```
+
+## Sizes and variants
+
+`sm` 30 px in dense rows, `md` 40 px in lists, `lg` 84 px on profile screens. Variants tint (default), ink, warning, neutral let a list distinguish people.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent } from '@bitforgehq/ui';
+
+/** Avatar sizes and colour variants. */
+@Component({
+  selector: 'app-example-avatar-sizes',
+  imports: [BfAvatarComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <bf-avatar initials="JK" size="sm" variant="neutral" />
+      <bf-avatar initials="AR" variant="warning" />
+      <bf-avatar initials="LM" size="lg" variant="ink" />
+    </div>
+  `,
+})
+export class AvatarSizesExampleComponent {}
+```
+
+Pass `alt` when the avatar is the only place the person's name appears; otherwise it is decorative and hidden from assistive tech.
+
+## Theming
+
+Consumes tokens by variant, background then text/initials color:
+
+- `tint` (default): `primary-soft` / `primary-strong`
+- `ink`: `text` / `bg`
+- `warning`: `warning-soft` / `warning`
+- `neutral`: `neutral-soft` / `neutral`
+
+The circle is never smaller than 4.5ex of its initials (`min-w-[4.5ex] min-h-[4.5ex]`; `ex` follows the rendered font), so a text zoom that grows the initials but not the layout (Android's font size setting) grows the circle with them instead of cutting them off; at the default size and with iOS Dynamic Type every size step is larger (sm 30 px against 26.7 px with Manrope), so nothing changes.
+
+## Accessibility
+
+With `alt` set, the host gets `role="img"` and `aria-label` carrying it, so the avatar is announced as one image with the person's name; the inner `<img>` itself has an empty `alt` to avoid a second announcement. Without `alt`, the host is `aria-hidden` and both the image and the initials span are decorative.
+
+## Inputs
+
+| Name       | Type                                                            | Default  | Description                                                                                                                                               |
+| ---------- | --------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `initials` | `string`                                                        | `''`     | One or two letters shown when there is no image.                                                                                                          |
+| `src`      | `string`                                                        | `''`     | Image URL; when set, the image replaces the initials.                                                                                                     |
+| `alt`      | `string`                                                        | `''`     | Accessible name; when unset the avatar is decorative and hidden from assistive tech.                                                                      |
+| `size`     | `BfAvatarSize` (`'sm' \| 'md' \| 'lg'`)                         | `'md'`   | Diameter: sm 30 px, md 40 px (default), lg 84 px; at least 4.5ex of the initials, so a text zoom (Android font scale) grows the circle with its initials. |
+| `variant`  | `BfAvatarVariant` (`'tint' \| 'ink' \| 'warning' \| 'neutral'`) | `'tint'` | Background treatment for the initials.                                                                                                                    |
+
+## Notes
+
+### Do
+
+- Pass `alt` with the person's name when you pass `src`.
+
+### Don't
+
+- Don't use avatars for icons; use an icon tile.
+
+## Migration notes
+
+### 0.3.0
+
+JSDoc of `avatar.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** the circle is at least 4.5ex of its initials (`min-w-[4.5ex] min-h-[4.5ex]`), so at
+Android font scale 2.0 (a text zoom that doubles the rendered initials, and `ex` with them, but not
+em, rem or px lengths) it grows with
+them instead of cutting them off, e.g. the `sm` avatar in a header's `end` slot (F-051). At the
+default size and with iOS Dynamic Type every size is larger than that minimum (with Manrope: sm
+30 px against 26.7, md 40 against 31.5, lg 84 against 63), so nothing changes.
+
+### 0.1.0
+
+New `bf-avatar`: a round avatar showing a photo (`src`/`alt`) or initials on a tinted circle. `size` is `sm` (30 px), `md` (40 px, default) or `lg` (84 px); `variant` is `tint` (default), `ink`, `warning` or `neutral`. The host now carries `role="img"`/`aria-label` only when `alt` is set; without `alt` the host is `aria-hidden="true"` and decorative, instead of always announcing itself with the initials as a fallback name. The inner `<img>` now always has `alt=""` so the image itself is hidden from the accessibility tree and the host's `aria-label` is the single source of the accessible name.