@bitforgehq/ui 0.3.0

package/ai/components/page.md

@@ -0,0 +1,299 @@
+# bf-page
+
+Frame for one stacked mobile screen that supplies lifecycle events and shared page state
+
+`BfPageComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { BfButtonComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfNavController,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+
+/** `bf-page` showcase: logs this page's lifecycle events and shows its view state. */
+@Component({
+  selector: 'app-page-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfButtonComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-page
+      #page
+      data-showcase="page"
+      (bfViewWillEnter)="log('bfViewWillEnter')"
+      (bfViewDidEnter)="log('bfViewDidEnter')"
+      (bfViewWillLeave)="log('bfViewWillLeave')"
+      (bfViewDidLeave)="log('bfViewDidLeave')"
+    >
+      <bf-header title="Page" [largeTitle]="false" />
+      <bf-content>
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Push a page, then go back: this page stays alive underneath and logs all four lifecycle
+            events.
+          </p>
+          <p data-showcase-result class="text-body">View state: {{ page.viewState() }}</p>
+          <bf-button (clicked)="push()">Push a page</bf-button>
+          <bf-list [inset]="false">
+            @for (entry of events(); track $index) {
+              <bf-list-item [title]="entry" [subtitle]="'Event ' + ($index + 1)" />
+            }
+          </bf-list>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class PageShowcasePage {
+  private readonly nav = inject(BfNavController);
+
+  protected readonly events = signal<readonly string[]>([]);
+
+  log(event: string): void {
+    this.events.update((events) => [...events, event]);
+  }
+
+  push(): void {
+    void this.nav.forward('/showcase/page/next');
+  }
+}
+```
+
+## Overview
+
+The page frame of a mobile app: `bf-stack-outlet` positions one per stacked page and provides
+its `BfViewLifecycle` through the element injector. Everything scrollable inside a page goes
+into `bf-content`; `bf-page` is only the frame, the lifecycle signal and a per-page
+`BfPageContext` (provided for its children, where `bf-content` registers its scroller). The
+page an outlet shows makes its `bf-content` the document's `main` landmark. Used
+standalone (outside an outlet, e.g. in a docs demo) it falls back to a local, inert lifecycle
+instance instead of throwing, and exposes no `main` landmark.
+
+The page frame of a mobile app. `bf-stack-outlet` creates one wrapper frame per stacked page and
+positions `bf-page` to fill it; use one `bf-page` as the root element of every routed page
+component. Everything scrollable inside a page goes into `bf-content` — `bf-page` itself does not
+scroll, it is just the frame, the lifecycle signal and the per-page `BfPageContext`.
+
+## When to use
+
+Use `bf-page` as the root element of every routed page under a [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet), for the frame and the view lifecycle. Use a plain page component instead under a normal `router-outlet` on desktop.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A page of the stack.
+ *
+ * `data-bf-page-title` marks the heading the page is named by.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-page-basic',
+  imports: [BfPageComponent],
+  template: `
+    <bf-page>
+      <h1 data-bf-page-title>Item</h1>
+      <p>Page content</p>
+    </bf-page>
+  `,
+})
+export class PageBasicExampleComponent {}
+```
+
+## Lifecycle
+
+`bf-page` injects the `BfViewLifecycle` the outlet provides for this page and re-exposes it as
+`(bfViewWillEnter)`, `(bfViewDidEnter)`, `(bfViewWillLeave)`, `(bfViewDidLeave)` and as
+`viewState()` (`'entering' | 'active' | 'leaving' | 'inactive'`). Load or refresh data on
+`bfViewDidEnter` rather than the component's constructor, so a page parked in the stack and later
+returned to (a pop landing on it) reloads only if you choose to, and a page pushed back on top of
+itself (rare, but possible with `nav.root()`) reloads correctly.
+
+The events are delivered synchronously as the outlet fires them: a new page — the app's first page,
+a pushed page, the page `nav.root()` creates — gets `bfViewWillEnter` and then `bfViewDidEnter`
+once its transition settles (at once with `[animated]="false"`), and a popped or root-replaced page
+gets `bfViewWillLeave` and `bfViewDidLeave` before it is destroyed. A `bf-page` rendered later than
+its routed component's first render (inside an `@if` or `@defer`) misses the events that fired
+before it existed; read `viewState()` there instead.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * Loading when the page has entered.
+ *
+ * `bfViewDidEnter` fires each time the page becomes the visible one, also on the way back.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-page-lifecycle',
+  imports: [BfPageComponent],
+  template: `
+    <bf-page (bfViewDidEnter)="load()">
+      <p>{{ item()?.name }}</p>
+    </bf-page>
+  `,
+})
+export class PageLifecycleExampleComponent {
+  protected readonly item = signal<{ name: string } | null>(null);
+
+  protected load(): void {
+    this.item.set({ name: 'Atlas rebrand' });
+  }
+}
+```
+
+Used outside a `bf-stack-outlet` — for example in a docs demo, or a unit test that renders the
+page component directly — `bf-page` falls back to a local, inert `BfViewLifecycle` instead of
+throwing; its outputs simply never fire.
+
+## Page context
+
+`bf-page` provides a fresh `BfPageContext` to everything inside it. `bf-content` registers its
+scroll container there (`scroller`, a `signal<HTMLElement | null>`) on init and clears it on
+destroy, so a sibling such as a header can follow the page's scroll without querying the DOM.
+`mainLandmark` (a `signal(true)`) makes that scroller the document's `main` landmark. It stays
+true for the page a `bf-stack-outlet` shows; a `bf-page` outside an outlet (a docs illustration)
+or nested in another page sets it to false, and so does `bf-modal` for its content.
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { BfContentComponent, BfPageComponent, BfPageContext } from '@bitforgehq/ui/mobile';
+
+/** A bar that follows the page's scroller through the page context. */
+@Component({
+  selector: 'app-scroll-hint',
+  template: `<p class="text-caption text-text-muted p-4">{{ hint() }}</p>`,
+})
+export class ScrollHintComponent {
+  private readonly scroller = inject(BfPageContext, { optional: true })?.scroller;
+  protected readonly hint = computed(() =>
+    this.scroller?.() ? 'The page scrolls in bf-content.' : 'No scroller yet.',
+  );
+}
+
+/**
+ * The page context.
+ *
+ * `bf-content` registers its scroller in the page's `BfPageContext`, so a sibling reads it
+ * without querying the DOM.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-page-context',
+  imports: [BfContentComponent, BfPageComponent, ScrollHintComponent],
+  template: `
+    <bf-page>
+      <app-scroll-hint />
+      <bf-content>
+        <p class="p-4">Page content</p>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class PageContextExampleComponent {}
+```
+
+## Desktop
+
+`bf-page` is part of the Capacitor shell (`provideBfShell()`). A desktop web app routes plain page components through `router-outlet` and uses Angular's own lifecycle hooks; `bfViewDidEnter` and the other view events exist only because the stack keeps pages alive.
+
+## Theming
+
+- Background: `bg` (the page's own frame, so a sliding page never shows the page under it through
+  transparent areas).
+- Layout: `absolute inset-0 flex flex-col`, filling whatever frame the outlet gives it (or, used
+  standalone, its containing block).
+
+## Accessibility
+
+`bf-page` itself carries no `tabindex`; on push, the outlet moves focus to the page's title — the
+element marked `data-bf-page-title` (the `bf-header` title once it exists) — or, when there is no
+such element, to the positioned wrapper the outlet creates around the page. Give every page one
+element marked `data-bf-page-title` so a screen reader announces where it landed. The page's
+`bf-content` is the document's `main` landmark while the page is shown; a parked page is
+`aria-hidden`, so exactly one `main` is exposed.
+
+## Outputs
+
+| Name              | Payload | Description                                                 |
+| ----------------- | ------- | ----------------------------------------------------------- |
+| `bfViewWillEnter` | `void`  | Emitted when the page starts entering the top of the stack. |
+| `bfViewDidEnter`  | `void`  | Emitted once the page is active at the top of the stack.    |
+| `bfViewWillLeave` | `void`  | Emitted when the page starts leaving the top of the stack.  |
+| `bfViewDidLeave`  | `void`  | Emitted once the page has left the top of the stack.        |
+
+## Slots
+
+- `default`: The page: a `bf-header` and a `bf-content`.
+
+## Notes
+
+### Do
+
+- Use exactly one `bf-page` as the top-level element of a routed page component.
+- Load data in `bfViewDidEnter`, not the constructor, so a returned-to page can choose whether to
+  reload.
+- Mark the page's heading with `data-bf-page-title` so push focuses it.
+
+### Don't
+
+- Don't put scrollable content directly inside `bf-page`; wrap it in `bf-content`.
+- Don't set a `tabindex` on `bf-page` yourself; the outlet manages focus on its wrapper.
+
+## Migration notes
+
+### 0.3.0
+
+JSDoc of `page-context.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `page.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+`BfPageContext` gains `safeAreaTop` (a `signal(true)`): whether the page reaches the top of the
+screen, so its header and a `fullscreen` content pad the top safe area. `bf-modal`'s page-sheet
+presentation sets it to false.
+
+`BfPageContext` gains `mainLandmark` (a `signal(true)`): whether the page's `bf-content` is the
+`main` landmark. A `bf-page` outside a `bf-stack-outlet` (a docs illustration) or nested in
+another page sets it to false, so the document keeps one `main` (Migration 36).
+
+### 0.2.0
+
+New `bf-page`: the page frame (`absolute inset-0 flex flex-col bg-bg`) that `bf-stack-outlet`
+positions one of per stacked page. Injects the per-page `BfViewLifecycle` the outlet provides
+(falling back to a local, inert instance when used standalone, e.g. in a docs demo) and re-exposes
+it as `viewState` (`computed`) plus outputs `bfViewWillEnter`, `bfViewDidEnter`, `bfViewWillLeave`,
+`bfViewDidLeave`, delivered synchronously through `BfViewLifecycle.on()`: a new page gets
+`bfViewWillEnter` and `bfViewDidEnter` (also the first page, without animation and after
+`nav.root()`), and a popped or root-replaced page gets `bfViewWillLeave` and `bfViewDidLeave` before
+it is destroyed. Carries no `tabindex` itself; the outlet still owns push/pop focus
+management on its own wrapper.
+
+`bf-page` now provides a per-page `BfPageContext` (`providers: [BfPageContext]`) whose `scroller`
+signal (`HTMLElement | null`) is where `bf-content` registers its scroll container on init and
+clears it on destroy, so `bf-header` can follow the page's scroll without querying the DOM. Its
+`headerHeight` signal (px, 0 by default) is where a `translucent` `bf-header` publishes its
+expanded height for `bf-content` to pad by.
+
+Inside `bf-stack-outlet`, the outermost `bf-page` of a stacked page also registers its
+`BfPageContext` with the outlet (a nested `bf-page` leaves it), so the outlet can scroll the page's
+content to the top when its tab is re-selected.

package/ai/components/progress.md

@@ -0,0 +1,215 @@
+# bf-progress
+
+Progress bar in two sizes and four tones for completion, quotas and unknown waits
+
+`BfProgressComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfProgressComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-progress overview.
+ *
+ * Live demo of `bf-progress`: a bar stepped by −10 % / +10 % buttons, a success bar and a `md` warning-tone bar.
+ */
+@Component({
+  selector: 'app-example-progress-overview',
+  imports: [BfProgressComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-progress [value]="value()" label="Atlas rebrand progress" />
+      <div class="flex items-center gap-2">
+        <bf-button variant="tonal" size="sm" [disabled]="value() <= 0" (clicked)="step(-10)">
+          −10 %
+        </bf-button>
+        <bf-button variant="tonal" size="sm" [disabled]="value() >= 100" (clicked)="step(10)">
+          +10 %
+        </bf-button>
+        <span data-status aria-live="polite" class="text-caption text-text-muted"
+          >{{ value() }} %</span
+        >
+      </div>
+      <bf-progress [value]="42" label="Bloom moodboard progress" tone="success" />
+      <bf-progress [value]="20" label="Storage used" size="md" tone="warning" />
+    </div>
+  `,
+})
+export class ProgressOverviewExampleComponent {
+  readonly value = signal(68);
+
+  step(delta: number): void {
+    this.value.update((value) => Math.min(100, Math.max(0, value + delta)));
+  }
+}
+```
+
+## Overview
+
+Progress bar for completion and quotas, determinate by default, or `indeterminate` while the
+amount of work is unknown.
+
+A progress bar for completion ("12 of 18 tasks") and quotas, or, with `indeterminate`, for work whose amount is not known yet.
+
+## When to use
+
+Use `bf-progress` when the share of work done is known: tasks completed, storage used, an upload; use `indeterminate` for a bar-shaped wait whose amount is not known yet (an upload before its size arrives). Use [bf-spinner](https://bitforge-ui.web.app/components/spinner) instead for a short wait of unknown length inside a control, and [bf-badge](https://bitforge-ui.web.app/components/badge) for a plain status without a quantity.
+
+## Basic usage
+
+`value` is the completion in percent, clamped to 0–100. Without `value` (and without `indeterminate`) the bar shows 0 %.
+
+```ts
+import { Component } from '@angular/core';
+import { BfProgressComponent } from '@bitforgehq/ui';
+
+/** A labelled progress bar at 68 %. */
+@Component({
+  selector: 'app-example-progress-basic',
+  imports: [BfProgressComponent],
+  template: `<bf-progress [value]="68" label="Atlas rebrand" />`,
+})
+export class ProgressBasicExampleComponent {}
+```
+
+## Value in words
+
+`valueText` gives assistive tech the value in words (`aria-valuetext`), such as "12 of 18 tasks" instead of "67 %". Show the same words next to the bar for everyone else.
+
+```ts
+import { Component } from '@angular/core';
+import { BfProgressComponent } from '@bitforgehq/ui';
+
+/**
+ * A progress bar that announces its value in words.
+ *
+ * `valueText` becomes `aria-valuetext`: "12 of 18 tasks" instead of "67 %".
+ */
+@Component({
+  selector: 'app-example-progress-value-text',
+  imports: [BfProgressComponent],
+  template: `
+    <div class="flex flex-col gap-1.5">
+      <bf-progress [value]="67" label="Atlas rebrand" valueText="12 of 18 tasks" />
+      <span class="text-caption text-text-muted">12 of 18 tasks</span>
+    </div>
+  `,
+})
+export class ProgressValueTextExampleComponent {}
+```
+
+## Indeterminate
+
+`indeterminate` drops the native value, so assistive tech announces a busy bar without a percentage, and a 40 % stripe runs across the track in the tone's colour. Under reduced motion (`prefers-reduced-motion: reduce`) the stripe stands still at the start: a static 40 % bar. `value` is ignored while `indeterminate` is set; set it back to `false` with the real value once it is known.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfProgressComponent } from '@bitforgehq/ui';
+
+/**
+ * An indeterminate bar that turns determinate.
+ *
+ * While the size of the upload is unknown the bar is `indeterminate`; "Size known" sets the real
+ * value.
+ */
+@Component({
+  selector: 'app-example-progress-indeterminate',
+  imports: [BfButtonComponent, BfProgressComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-progress label="Uploading report.pdf" [indeterminate]="unknown()" [value]="40" />
+      <bf-button variant="outline" size="sm" class="self-start" (clicked)="unknown.set(!unknown())">
+        {{ unknown() ? 'Size known' : 'Size unknown' }}
+      </bf-button>
+    </div>
+  `,
+})
+export class ProgressIndeterminateExampleComponent {
+  protected readonly unknown = signal(true);
+}
+```
+
+## Size and tone
+
+`md` (10 px) suits cards on mobile; the tone follows the meaning of the number.
+
+```ts
+import { Component } from '@angular/core';
+import { BfProgressComponent } from '@bitforgehq/ui';
+
+/** A thicker progress bar in the warning tone. */
+@Component({
+  selector: 'app-example-progress-size-tone',
+  imports: [BfProgressComponent],
+  template: `<bf-progress [value]="41" label="Bloom app" size="md" tone="warning" />`,
+})
+export class ProgressSizeToneExampleComponent {}
+```
+
+## Theming
+
+- Track: `surface-sunken`.
+- Fill by `tone`: `primary-strong` (the `primary` tone, default; ≥ 3:1 on the track for any
+  configured primary), `success`, `warning`, `danger`. The indeterminate stripe uses the same fill
+  (`CanvasText` under forced colours).
+- Motion: the stripe runs with `--animate-progress-indeterminate` (1.4 s, `--ease-md`), and stops
+  under reduced motion.
+
+## Accessibility
+
+Native `<progress>`, which is a `progressbar` without any role attribute, with `aria-label` carrying the required `label`; its `value`/`max` communicate the percentage to assistive tech, and `valueText` replaces it with words (`aria-valuetext`). An `indeterminate` bar renders no `value` attribute, the native indeterminate state; the stripe is `aria-hidden`.
+
+## Inputs
+
+| Name            | Type                                                                 | Default     | Description                                                                                                                                                                      |
+| --------------- | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`         | `number \| undefined`                                                | `undefined` | Completion in percent; clamped to 0–100. Without it (and without `indeterminate`) the bar shows 0 %. Ignored while `indeterminate`.                                              |
+| `indeterminate` | `boolean`                                                            | `false`     | The amount of work is unknown: the native bar carries no value (assistive tech announces it as busy) and a stripe runs across the track, a static 40 % bar under reduced motion. |
+| `valueText`     | `string`                                                             | `''`        | The value in words for assistive tech (`aria-valuetext`), such as "12 of 18 tasks"; the percentage is announced while it is empty.                                               |
+| `label`         | `string`                                                             | required    | Accessible name of the bar ("Atlas rebrand").                                                                                                                                    |
+| `size`          | `BfProgressSize` (`'sm' \| 'md'`)                                    | `'sm'`      | Bar height: sm 8 px (default), md 10 px.                                                                                                                                         |
+| `tone`          | `BfProgressTone` (`'primary' \| 'success' \| 'warning' \| 'danger'`) | `'primary'` | Fill color by meaning.                                                                                                                                                           |
+
+## Notes
+
+### Do
+
+- Always pass `label`; it is what screen readers announce with the percentage.
+- Put the numbers next to it in text ("12 of 18 tasks").
+
+### Don't
+
+- Don't animate the bar on first paint from 0; set the real value immediately.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** the default `primary` tone fills with `primary-strong` (was `primary`), so the fill
+reaches 3:1 on its `surface-sunken` track for any configured primary.
+
+JSDoc of `progress.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** `value` is optional (`input<number | undefined>(undefined)`, was required); without
+it and without `indeterminate` the bar renders 0 %. The redundant `role="progressbar"` attribute on
+the native `<progress>` is dropped (it is a progressbar natively). New `valueText = input('')`,
+rendered as `aria-valuetext` when set (F-039). New `indeterminate` (boolean): the native bar
+renders without `value` (indeterminate for assistive tech) and a 40 % stripe in the tone's fill
+runs across the track (`animate-progress-indeterminate`), standing still at the start under
+`motion-reduce:`. The host is a one-cell `grid` (was `block`) with `overflow-hidden
+rounded-full`, so the stripe shares the track's cell and stays in it.
+
+The indeterminate stripe runs from the inline start: under `dir="rtl"` it takes
+`--animate-progress-indeterminate-rtl` (mirrored keyframes), and stands still under reduced motion
+in both directions.
+
+### 0.2.0
+
+The value's width transition is off under `prefers-reduced-motion`.
+
+### 0.1.0
+
+New `bf-progress`: a determinate `role="progressbar"` for completion and quotas. `value` is clamped to 0–100 and rounded; `size` is `sm` (8 px, default) or `md` (10 px); `tone` (`primary` default, `success`, `warning`, `danger`) colors the fill. `label` is required and becomes the bar's `aria-label`. The native `<progress>` element now carries an explicit `role="progressbar"` attribute (it already had the role implicitly) so consumers and specs can select on it directly. `percent` now guards against a non-finite `value` (e.g. `NaN`), rendering `0` instead of propagating `NaN` into the fill width and `aria-valuenow`.