@bitforgehq/ui 0.3.0

package/ai/components/back-button.md

@@ -0,0 +1,286 @@
+# bf-back-button
+
+Header back button that pops the page stack or falls back to a default route
+
+`BfBackButtonComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfNavController,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+
+/**
+ * `bf-back-button` showcase root. The docs start on the pushed detail page
+ * (`showcase/back-button/detail`) with nothing under it, so its back button has nothing to pop and
+ * replaces the stack with its `defaultHref` — this page; from here, the detail page is pushed and
+ * its back button pops.
+ */
+@Component({
+  selector: 'app-back-button-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-page data-showcase="back-button">
+      <bf-header title="Back button" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            You arrived through the detail page's defaultHref. Open it again: now its back button
+            pops back here.
+          </p>
+          <bf-list [inset]="false">
+            <bf-list-item
+              title="Open the detail page"
+              [interactive]="true"
+              [chevron]="true"
+              (clicked)="open()"
+            />
+          </bf-list>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class BackButtonShowcasePage {
+  private readonly nav = inject(BfNavController);
+
+  open(): void {
+    void this.nav.forward('/showcase/back-button/detail');
+  }
+}
+```
+
+## Overview
+
+Back button for a `bf-header` start slot (or anywhere else in a page): pops the shown stack,
+or replaces it with `defaultHref` when there's nothing to pop back to, e.g. a deep link that
+landed on this page directly. Hidden when neither applies. Its anatomy follows the shell mode:
+iOS, a chevron with the `label` as text; Material, a bare arrow icon button named by `label`.
+
+The back control for a pushed page: pops the stack when there's a page to go back to, or replaces
+it with `defaultHref` when there isn't — the case where a deep link or a tab reset landed on this
+page directly, with nothing pushed underneath it. It hides itself entirely when neither applies,
+and its anatomy follows the shell mode (`provideBfShell({ mode })`, the platform's for `'auto'`):
+
+- **iOS**: a 24 px chevron-left and the `label` as text, in `primary`, as one 44 px tall control —
+  the UIKit back button.
+- **Material**: a bare 24 px arrow-left `bf-icon-button` (`text` variant); the `label` is its
+  accessible name, never shown.
+
+## When to use
+
+Use `bf-back-button` in the `start` slot of a pushed page's [bf-header](https://bitforge-ui.web.app/components/header) in the Capacitor shell. Use the browser's own back button and a breadcrumb instead on a desktop web page, and a [bf-button](https://bitforge-ui.web.app/components/button) link (`a[bfButton]`) for a named way back.
+
+## Basic usage
+
+Put it in a `bf-header`'s `start` slot:
+
+```ts
+import { Component } from '@angular/core';
+import { BfBackButtonComponent, BfHeaderComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A back button in a detail page's header.
+ *
+ * It pops the stack, and hides itself on a page with nothing to go back to.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-back-button-basic',
+  imports: [BfBackButtonComponent, BfHeaderComponent],
+  template: `
+    <bf-header title="Task" [largeTitle]="false">
+      <bf-back-button bfSlot="start" />
+    </bf-header>
+  `,
+})
+export class BackButtonBasicExampleComponent {}
+```
+
+## Default destination
+
+Set `defaultHref` for pages that can be entered without a page underneath them, such as a
+notification deep link:
+
+```ts
+import { Component } from '@angular/core';
+import { BfBackButtonComponent, BfHeaderComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A back button with a default destination.
+ *
+ * On a page opened directly (a deep link), it shows and goes to `defaultHref`.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-back-button-default-href',
+  imports: [BfBackButtonComponent, BfHeaderComponent],
+  template: `
+    <bf-header title="Task" [largeTitle]="false">
+      <bf-back-button bfSlot="start" defaultHref="/tabs/today" />
+    </bf-header>
+  `,
+})
+export class BackButtonDefaultHrefExampleComponent {}
+```
+
+With `defaultHref` set, the button is visible even at the bottom of the stack; clicking it calls
+`nav.root(defaultHref)`, replacing the whole stack with that one page.
+
+## Label
+
+Without a `label` the button reads `provideBfLabels()`'s `back` ("Back"), so translate it once
+app-wide (`provideBfLabels({ back: 'Zurück' })`); pass the previous page's name when it is short (UIKit shows the previous title and falls back to "Back" when it does not fit). In iOS
+mode it is the visible text beside the chevron (truncated past 192 px); in Material mode it only
+names the arrow button for assistive tech.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBackButtonComponent, BfHeaderComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A back button labelled with the previous page.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-back-button-label',
+  imports: [BfBackButtonComponent, BfHeaderComponent],
+  template: `
+    <bf-header title="Atlas rebrand" [largeTitle]="false">
+      <bf-back-button bfSlot="start" label="Projects" />
+    </bf-header>
+  `,
+})
+export class BackButtonLabelExampleComponent {}
+```
+
+## Desktop
+
+`bf-back-button` is part of the Capacitor shell (`provideBfShell()`). On a desktop web page the browser's back button and history already go back; add a breadcrumb or a named link instead. Inside the shell under a mouse, the iOS form darkens to `primary-strong` on hover and the Material form is a `text` icon button; both show the pointer cursor and a focus ring on keyboard focus only.
+
+## Theming
+
+- iOS: `primary-text` text and chevron (`primary-strong` on hover), `text-heading` at regular weight,
+  the focus ring `ring` on a `rounded-field` outline, 44 px tall (`h-11`) and at least 44 px wide
+  (`min-w-hit`). When the bar is short of space (large text sizes, a long title and wide actions)
+  it shrinks inside the header's `start` slot: the text truncates and then disappears before the
+  chevron, down to the 44 px hit area, as UIKit drops the back title. It stays the button's name.
+- Material: the `text` variant of `bf-icon-button`: `text-muted` at rest, `surface-muted` /
+  `text` on hover, no background otherwise; the 44 px hit area and focus ring come from
+  `bf-icon-button` as well.
+
+## Accessibility
+
+Both modes render a native `<button>` with a 44 px minimum hit area; the glyph is decorative
+(`aria-hidden`). In iOS mode the visible `label` text is the button's name; in Material mode
+`label` (else the `back` label, `"Back"`) becomes the icon button's `aria-label`, since the arrow alone gives
+assistive tech no name. It never moves focus itself: after a pop
+`bf-stack-outlet` returns focus to the element that had it on the page below when this page was
+pushed (or to that page's frame), and after the `nav.root(defaultHref)` replacement it focuses the
+new page's title (`data-bf-page-title`, the `bf-header` `h1`).
+
+### Keyboard
+
+| Key                                 | Action                                                                       |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                      | Moves focus to the button                                                    |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Pops the stack, or replaces it with `defaultHref` when nothing is underneath |
+
+## Inputs
+
+| Name          | Type     | Default | Description                                                                                                                                                                        |
+| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultHref` | `string` | `''`    | Destination `nav.root()` navigates to when there's no page to pop back to.                                                                                                         |
+| `label`       | `string` | `''`    | The previous page's name: the text beside the chevron in iOS mode, the arrow button's accessible name in Material mode. Empty falls back to `provideBfLabels()`'s `back` ("Back"). |
+
+## Methods
+
+### `go(): void`
+
+Goes back one page, or to `defaultHref` when the stack has none to go back to.
+
+## Notes
+
+### Do
+
+- Translate `label`, or set it to the previous page's short name — in iOS mode users read it.
+- Set `defaultHref` on any page that can be the first thing a user sees (deep links, tab roots).
+
+### Don't
+
+- Don't pass a long sentence as `label`: iOS truncates it, and the header's centred title gives up
+  the same width on the other side.
+- Don't wire `(clicked)` yourself; `go()` already picks `nav.back()` or `nav.root(defaultHref)`
+  for you.
+- Don't render it on a page that is always at the bottom of a tab's stack without a `defaultHref`
+  — it will simply stay hidden.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `back` ("Back"),
+both as the iOS text and as the Material button's name.
+
+**Behaviour:** the iOS label and chevron use `primary-text` (was `primary`); hover stays
+`primary-strong`.
+
+JSDoc of `back-button.component.ts` for the API reference: docs for the undocumented members and
+methods. No behaviour change.
+
+JSDoc of `back-button.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs. No behaviour change.
+
+**Behaviour:** large text (F-051): the host (`min-w-0 shrink`) and the iOS button (`shrink`, no
+longer `shrink-0`) may shrink inside the header's `start` slot, down to the 44 px hit area: the
+text truncates and then disappears before the chevron, as UIKit drops the back title when space is
+short. The text stays the button's name. It carries `data-bf-back-text`, the part `bf-header`'s iOS
+start-slot cap lets give way.
+
+### 0.3.0
+
+**Behaviour:** when no handler claims the back press (every shown stack at its first page),
+`BfBackButtonService` calls `App.minimizeApp()`, so the app moves to the background and a
+relaunch resumes warm; with `provideBfShell({ backAtRoot: 'exit' })` it calls `App.exitApp()` as
+before. It reads `BF_SHELL_CONFIG` (optional; `'minimize'` without it), and a failure goes to
+`console.error`. See Migration 34.
+
+### 0.2.0
+
+New `bf-back-button`: a `bf-icon-button` (`text` variant, chevron-left) that pops the primary
+stack via `BfNavController.back()`, or replaces it with `defaultHref` via `nav.root()` when there
+is nothing to pop back to (a deep link landing directly on the page). Visible when
+`nav.canGoBack()` or `defaultHref` is set, hidden otherwise. `label` (default `"Back"`) is the
+button's accessible name.
+
+Changed: the anatomy follows the shell mode (resolved like `bf-stack-outlet`). iOS: a native
+button with a 24 px chevron-left and `label` as visible text (`text-heading`, regular) in
+`primary`, one 44 px tall control (`h-11 min-w-hit`, text truncated past 192 px), named by its
+text. Material: a bare 24 px arrow-left `bf-icon-button` (`text` variant) with `label` as its
+`aria-label`. `defaultHref` works the same in both.
+
+New `BfBackButtonService` (`providedIn: 'root'`, registered and started at bootstrap by
+`provideBfShell()`'s environment initializer, together with `BfPlatformService`): the hardware
+back button queue. `register(priority, handler)` returns an unregister function; `dispatch()`
+(public, for tests and 2c's overlays) runs the registered handlers from highest to lowest priority
+until one returns true (on equal priority the newest registration runs first, so stacked overlays
+close top-down), then falls back to `App.exitApp()`; `BfNavController` registers the priority-0
+handler that pops the deepest active stack while any stack has more than one page. On native Android it subscribes to
+`App.addListener('backButton', …)` via `await import('@capacitor/app')` in a try/catch (never a
+static import, so a web or iOS bundle never loads the plugin); nothing is registered on iOS or
+web, where `Escape` closes overlays instead.

package/ai/components/badge.md

@@ -0,0 +1,171 @@
+# bf-badge
+
+Small status label in semantic tones, or a compact numeric pill for counts
+
+`BfBadgeComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-badge overview.
+ *
+ * Live demo of `bf-badge`: four status labels and a count pill.
+ */
+@Component({
+  selector: 'app-example-badge-overview',
+  imports: [BfBadgeComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-3">
+      <bf-badge variant="success">On track</bf-badge>
+      <bf-badge variant="warning">At risk</bf-badge>
+      <bf-badge variant="danger">Blocked</bf-badge>
+      <bf-badge>Draft</bf-badge>
+      <bf-badge [count]="3" />
+    </div>
+  `,
+})
+export class BadgeOverviewExampleComponent {}
+```
+
+## Overview
+
+Status label ("On track", "At risk") or, with `count`, a compact numeric pill for unread counts.
+
+Badges label a status ("On track", "At risk") or, as a count pill, show how many items are waiting. They are read-only; use a `bf-chip` for anything the user can toggle.
+
+## When to use
+
+Use `bf-badge` for a read-only status or count next to what it describes: "At risk" on a project, "3" on an inbox row. Use [bf-chip](https://bitforge-ui.web.app/components/chip) instead when the user can toggle it, and [bf-alert](https://bitforge-ui.web.app/components/alert) when the status needs a sentence of explanation.
+
+## Status labels
+
+The variant carries the meaning: `success`, `warning`, `danger`, `primary` or the default `neutral`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+
+/** Status badges in the four tones. */
+@Component({
+  selector: 'app-example-badge-status',
+  imports: [BfBadgeComponent],
+  template: `
+    <div class="flex flex-wrap items-center gap-2">
+      <bf-badge variant="success">On track</bf-badge>
+      <bf-badge variant="warning">At risk</bf-badge>
+      <bf-badge variant="danger">Blocked</bf-badge>
+      <bf-badge>Draft</bf-badge>
+    </div>
+  `,
+})
+export class BadgeStatusExampleComponent {}
+```
+
+## Count pill
+
+Setting `count` switches to the compact primary pill. Values above 99 render as "99+"; zero renders as "0".
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfBadgeComponent, BfButtonComponent } from '@bitforgehq/ui';
+
+/** A count pill that caps at 99+. */
+@Component({
+  selector: 'app-example-badge-count',
+  imports: [BfBadgeComponent, BfButtonComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <span class="text-body">Inbox</span>
+      <bf-badge [count]="unread()" />
+      <bf-button variant="text" size="sm" (clicked)="unread.set(unread() + 50)">Add 50</bf-button>
+    </div>
+  `,
+})
+export class BadgeCountExampleComponent {
+  protected readonly unread = signal(3);
+}
+```
+
+## Count label
+
+A bare number means little to a screen reader. `countLabel` says what is counted: it renders visually hidden after the number, so the pill reads "99+ unread messages" while it still shows "99+". It is used only with `count`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent } from '@bitforgehq/ui';
+
+/**
+ * A count pill that says what it counts.
+ *
+ * `countLabel` is read after the number ("99+ unread messages") without showing on screen.
+ */
+@Component({
+  selector: 'app-example-badge-count-label',
+  imports: [BfBadgeComponent],
+  template: `
+    <div class="flex items-center gap-3">
+      <span class="text-body">Inbox</span>
+      <bf-badge [count]="120" countLabel="unread messages" />
+    </div>
+  `,
+})
+export class BadgeCountLabelExampleComponent {}
+```
+
+## Theming
+
+Consumes tokens by variant, background then text:
+
+- `neutral` (default): `neutral-soft` / `neutral`
+- `primary`: `primary-soft` / `primary-strong`
+- `success`: `success-soft` / `success`
+- `warning`: `warning-soft` / `warning`
+- `danger`: `danger-soft` / `danger`
+- Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`
+- Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).
+
+## Accessibility
+
+A badge is a plain `<span>` with no role or ARIA attributes; its text is read as part of the surrounding content, so pair it with a label or context that says what it means rather than relying on color alone. A count pill with `countLabel` carries that context itself: a visually hidden (`sr-only`) span after the number, read as one phrase with it ("99+ unread messages").
+
+## Inputs
+
+| Name         | Type                                                                              | Default     | Description                                                                                                                                          |
+| ------------ | --------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`    | `BfBadgeVariant` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger'`) | `'neutral'` | Tint for the label style. Ignored when `count` is set.                                                                                               |
+| `count`      | `number \| undefined`                                                             | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
+| `countLabel` | `string`                                                                          | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
+
+## Slots
+
+- `default`: The badge text, shown when no `count` is set.
+
+## Notes
+
+### Do
+
+- Keep labels to one or two words; badges are scanned, not read.
+- Pair a count pill with a label or icon that says what is being counted, and set `countLabel` so the number is not read alone.
+
+### Don't
+
+- Don't use a badge as a button; it has no interactive states.
+- Don't invent new colors on it; pick the variant that matches the meaning.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** the label and the count pill use `rounded-control` (`--radius-control`, `9999px` by
+default, so they render as before).
+
+JSDoc of `badge.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `default`. No behaviour change.
+
+New `countLabel = input('')` (F-039): with `count` set, it renders visually hidden after the
+number (`<span class="sr-only">`), so the pill reads "99+ unread messages". Ignored without
+`count`.