@bitforgehq/ui 0.3.0

package/ai/components/refresher.md

@@ -0,0 +1,377 @@
+# bf-refresher
+
+Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull
+
+`BfRefresherComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+  BfRefresherComponent,
+} from '@bitforgehq/ui/mobile';
+
+/** How long the showcase's fake reload takes, so the spinner is visible. */
+export const SHOWCASE_REFRESH_MS = 800;
+
+/** `bf-refresher` showcase: pull the list down to "reload", which adds a row at the top. */
+@Component({
+  selector: 'app-refresher-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfRefresherComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-page data-showcase="refresher">
+      <bf-header title="Refresher" [largeTitle]="false" />
+      <bf-content>
+        <bf-refresher (refreshRequested)="onRefresh($event.complete)" />
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            Pull the list down past the disc's threshold and let go: it spins, and a new row arrives
+            at the top.
+          </p>
+          <bf-list [inset]="false">
+            @for (row of rows(); track row) {
+              <bf-list-item [title]="row" />
+            }
+          </bf-list>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class RefresherShowcasePage {
+  private readonly destroyRef = inject(DestroyRef);
+
+  protected readonly rows = signal<readonly string[]>(['Message 3', 'Message 2', 'Message 1']);
+
+  /** The pending fake-reload timer, so it can be cancelled if the page is destroyed mid-refresh. */
+  private reloadTimeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  constructor() {
+    this.destroyRef.onDestroy(() => {
+      if (this.reloadTimeoutId !== undefined) {
+        clearTimeout(this.reloadTimeoutId);
+      }
+    });
+  }
+
+  async onRefresh(complete: () => void): Promise<void> {
+    try {
+      await new Promise<void>((resolve) => {
+        this.reloadTimeoutId = setTimeout(resolve, SHOWCASE_REFRESH_MS);
+      });
+      this.rows.update((rows) => [`Message ${rows.length + 1}`, ...rows]);
+    } finally {
+      this.reloadTimeoutId = undefined;
+      complete();
+    }
+  }
+}
+```
+
+## Overview
+
+Pull-to-refresh, placed as the first child of `bf-content`. It tracks Pointer Events on the
+page's scroller (read from `BfPageContext`, or its nearest scrolling ancestor when used without one)
+only while the scroller is at `scrollTop === 0`: the disc resists the pull (half the pointer's
+travel, capped) from a resting position above the clipped content to a 64 px threshold, ticks
+`BfHapticsService.impact('light')` once on crossing it, and on release past the threshold
+parks at the top with a spinner and emits `refreshRequested` — call `complete()` on the event to animate
+the disc away and reset. A press by itself changes nothing: only once a pointermove clears an
+8 px downward slop (out-vertical'ing any horizontal travel) does it claim the gesture and
+capture the pointer on the scroller, so a plain click on the content underneath (a row, a
+button) still reaches it. For touch, a non-passive `touchmove` guard (attached only while a
+press is tracked) keeps the browser from taking a downward drag at the top as a pan, which
+would cancel the pointer stream; upward drags still scroll the list. The disc itself is
+`aria-hidden`; a permanent, visually hidden `role="status"` region announces
+`provideBfLabels()`'s `refreshing` ("Refreshing"). `prefers-reduced-motion` still follows the
+pointer 1:1 during the pull (direct manipulation is not motion); only the settle, park and `complete()` animations
+become instant.
+
+That pull is the Material (and mouse/pen) mode. A touch in iOS mode (`BfPlatformService.mode()`)
+is the bounce mode instead: the refresher claims nothing (no capture, no `preventDefault`, no
+guard), the scroller rubber-bands natively, and while the finger is down a negative `scrollTop`
+shows the disc inside the gap the bounce opens, at its resting −48 px, with opacity and scale
+(0.6 → 1) following `−scrollTop / 64` once it passes 8 px; one light haptic at 64 px. Lifting the
+finger at 64 px or more parks the disc and emits `refreshRequested`, like `UIRefreshControl`; a bounce
+with no finger down (a fling's overshoot) never shows it. The host carries `data-bf-refresher`
+while enabled, so `bfOverscrollStretch` leaves the top edge to it.
+
+Pull-to-refresh. `bf-refresher` goes inside `bf-content`, as its first child: it tracks Pointer
+Events on the page's scroller and, only while the scroller is at the very top, resists a downward
+pull into a 40 px disc above the content. A plain press changes nothing — only once a move clears
+an 8 px downward slop does it claim the gesture, and only then does it capture the pointer on the
+scroller (so the gesture keeps tracking even if the pointer strays outside the scroller mid-drag)
+and the disc becomes visible. Pull past the 64 px threshold and release, and it parks the disc at
+the top with a spinner and emits `refreshRequested` — call `complete()` on the event once the reload is
+done to animate the disc away and reset.
+
+## When to use
+
+Use `bf-refresher` as the first child of a [bf-content](https://bitforge-ui.web.app/components/content) whose content the user reloads on a phone: an inbox, a feed. Use a Refresh [bf-button](https://bitforge-ui.web.app/components/button) instead on desktop, and add one next to the refresher for keyboard and switch-control users.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+  BfRefresherComponent,
+} from '@bitforgehq/ui/mobile';
+
+/**
+ * Pull to refresh.
+ *
+ * `refreshRequested` hands over `complete`; call it once the reload has finished.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-refresher-basic',
+  imports: [
+    BfContentComponent,
+    BfHeaderComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfPageComponent,
+    BfRefresherComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Inbox" />
+      <bf-content>
+        <bf-refresher (refreshRequested)="onRefresh($event.complete)" />
+        <bf-list>
+          @for (message of messages(); track message) {
+            <bf-list-item [title]="message" />
+          }
+        </bf-list>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class RefresherBasicExampleComponent {
+  protected readonly messages = signal(['Welcome']);
+
+  async onRefresh(complete: () => void): Promise<void> {
+    await this.reload();
+    complete();
+  }
+
+  /** Stands in for the inbox state's reload. */
+  private async reload(): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, 800));
+    this.messages.update((messages) => [`New message ${messages.length}`, ...messages]);
+  }
+}
+```
+
+## iOS: riding the native bounce
+
+In iOS mode (`BfPlatformService.mode() === 'ios'`) a touch works like `UIRefreshControl`. The
+refresher claims nothing — no pointer capture, no `preventDefault`, no `touchmove` guard — so the
+content rubber-bands natively (`bf-content` keeps even a short page scrollable by 1 px, so it always
+bounces). While a finger is down it watches the scroller's `scroll` events: once the bounce opens
+more than 8 px above the content, the disc shows inside that gap, at its resting position just
+above the content and moving with it, with opacity and scale (0.6 → 1) following the pull up to the
+64 px threshold, where one light haptic ticks. Lift the finger at 64 px or more and the disc
+settles onto the content top while the content snaps back, and `refreshRequested` emits; lift it earlier and
+the disc hides. A bounce with no finger down — the overshoot of a fling — never shows the disc.
+
+This follows the engine (`BfPlatformService.mode()`, iOS only on native iOS), not
+`provideBfShell({ mode })`: the bounce mode claims nothing and relies on WebKit reporting a negative
+`scrollTop` while it rubber-bands. Chrome never reports a negative `scrollTop`, so an Android app
+forced into `mode: 'ios'` keeps the material pull; with the shell mode, its pull-to-refresh would
+stop working.
+
+## Android and mouse: the material pull
+
+Everywhere else — Material mode, and a mouse or pen in iOS mode (the desktop docs preview) — the
+refresher drives the pull itself, as described above: the slop, the pointer capture, the resisted
+disc and the park.
+
+## Clicks pass through
+
+A tap or click that never moves past the slop is left completely alone — the row or button
+underneath it still receives its own `click`. `bf-refresher` only starts intercepting the pointer
+once a move proves it's a downward pull, not a press on the content beneath it.
+
+## Touch
+
+In Material mode a phone's scroller is `touch-pan-y`, so the browser would take a downward drag as
+its own pan and cancel the pointer stream. While a press is tracked, `bf-refresher` adds a non-passive
+`touchmove` listener to the scroller that prevents a downward drag at the top (and every move once
+the pull is claimed); upward drags are never prevented, so the list scrolls as usual. The row under
+the finger losing its implicit pointer capture when the scroller claims the pull does not end it.
+
+## The `complete()` contract
+
+`refreshRequested` emits once per completed pull, with a `BfRefresherRefreshEvent`
+(`{ complete: () => void }`); the 0.2 name `refresh` still emits the same event until 0.4.0. The disc stays parked
+with its spinner spinning — and further pulls are ignored — until `complete()` is called; call it
+whether the reload succeeded or failed, or the disc never leaves the top. `complete()` animates the
+disc back to its resting position above the content and only then does another pull start working
+again.
+
+## Disabling
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfContentComponent, BfPageComponent, BfRefresherComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A refresher that is off while the page is read-only.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-refresher-disabled',
+  imports: [BfContentComponent, BfPageComponent, BfRefresherComponent],
+  template: `
+    <bf-page>
+      <bf-content>
+        <bf-refresher [disabled]="isReadOnly()" />
+        <p class="text-body p-4">An archived project cannot be refreshed.</p>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class RefresherDisabledExampleComponent {
+  protected readonly isReadOnly = signal(true);
+}
+```
+
+`disabled` stops pull tracking entirely; the disc never moves and `refreshRequested` never emits. It has no
+effect on a pull already in progress — flip it before the next `pointerdown`.
+
+## Reduced motion
+
+The disc still follows the pointer 1:1 (resisted) during the pull under
+`prefers-reduced-motion: reduce` — direct manipulation tied to the pointer's own position isn't
+motion. What changes is the parts driven by the Web Animations API: parking the disc when a pull
+completes, `complete()`'s dismissal, and settling back on a pull that didn't reach the threshold
+all become instant jumps instead of animated transitions. The `refreshing` state and the `refreshRequested`
+event fire exactly the same either way.
+
+## Desktop
+
+A mouse can drag the pull (the Material pull runs for a mouse or pen), but desktop users do not expect pull-to-refresh and a wheel or trackpad scroll never starts it. On desktop, offer a Refresh [bf-button](https://bitforge-ui.web.app/components/button) in the toolbar that calls the same reload.
+
+## Theming
+
+- Disc: `bg-surface`, `shadow-raised`, `rounded-full`, 40 × 40 px; `visibility: hidden` at rest so
+  its shadow never bleeds above the content, shown only once a pull is claimed (or, on iOS, once
+  the bounce opens more than 8 px).
+- Host: carries `data-bf-refresher` while enabled, so `bf-content`'s Android edge stretch leaves
+  the top edge to the refresher.
+- Spinner: `bf-spinner` inherits `currentColor`; set `text-primary` on an ancestor to color it,
+  the same as any other spinner usage.
+- No background or border of its own beyond the disc — it never changes the scroller's
+  `overscroll-behavior`.
+
+## Accessibility
+
+A visually hidden `role="status"` region with `aria-live="polite"` is always in the accessibility
+tree: empty at rest, it reads `provideBfLabels()`'s `refreshing` ("Refreshing") while a refresh runs, so the change is announced. The
+disc and its spinner are `aria-hidden="true"` — purely visual, with no status of their own. The pull gesture itself has no
+keyboard equivalent — wire a manual refresh action (e.g. a toolbar button calling the same reload
+method) for keyboard and switch-control users.
+
+## Inputs
+
+| Name       | Type      | Default | Description                                                                      |
+| ---------- | --------- | ------- | -------------------------------------------------------------------------------- |
+| `disabled` | `boolean` | `false` | Disables pull tracking; the disc never moves and `refreshRequested` never emits. |
+
+## Outputs
+
+| Name               | Payload                   | Description                                                                                                                        |
+| ------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `refreshRequested` | `BfRefresherRefreshEvent` | Emitted when a pull past the threshold is released; call `complete()` to end it.                                                   |
+| `refresh`          | `BfRefresherRefreshEvent` | Emitted with the same event as `refreshRequested`, together with it. **Deprecated** (0.3.0 use refreshRequested; removed in 0.4.0) |
+
+## Methods
+
+### `complete(): void`
+
+Ends a refresh: animates the disc away (skipped under reduced motion) and resets state.
+
+## Notes
+
+### Do
+
+- Place exactly one `bf-refresher` as the first child of `bf-content`.
+- Always call `complete()` from the `refreshRequested` handler, including on a failed reload.
+- Leave `overscroll-behavior` alone; `bf-refresher` depends on `bf-content`'s `overscroll-contain`.
+
+### Don't
+
+- Don't put `bf-refresher` anywhere the page can scroll away from the top on load — a pull only
+  starts at `scrollTop === 0`.
+- Don't provide a second way to trigger the same pull gesture; give keyboard users a real button
+  instead of relying on the pull.
+
+## Migration notes
+
+### 0.3.0
+
+**Deprecated:** `refresh` → `refreshRequested`, typed with the new exported
+`BfRefresherRefreshEvent` (`{ complete: () => void }`, was an inline object type). Both outputs
+emit the same event object for each completed pull until `refresh` is removed in 0.4.0 (see
+Migration 23).
+
+**Behaviour:** the status region announces `provideBfLabels()`'s `refreshing` ("Refreshing").
+
+### 0.2.0
+
+New `bf-refresher`: pull-to-refresh, placed as the first child of `bf-content`. It tracks Pointer
+Events on the page's scroller (read from `BfPageContext`, falling back to its own parent element)
+only while `scrollTop === 0`. A press by itself changes nothing; only once a move clears an 8 px
+downward slop (out-vertical'ing any horizontal travel) does it claim the gesture, capture the
+pointer on the scroller, and start resisting the drag at `delta * 0.5` (capped at 72 px) into a
+40 px `bg-surface shadow-raised rounded-full` disc holding a `bf-spinner`, from a resting −48 px
+up to a 64 px threshold — so a plain click on the content underneath (a row, a button) still
+reaches it. Crossing the threshold ticks `BfHapticsService.impact('light')` once; releasing past
+it sets `refreshing` (a readonly signal), parks the disc at 0 and emits `refresh` with `{
+complete: () => void }` — releasing before the threshold animates the disc back to rest instead.
+`complete()` animates the disc away and clears `refreshing`, after which the next pull starts
+working again; `disabled` stops tracking pulls entirely, and further pulls are ignored while
+already `refreshing`. The park/settle/`complete()` transitions use the Web Animations API;
+`prefers-reduced-motion` only skips those — the disc still tracks the pointer 1:1 during the pull
+itself, since direct manipulation isn't motion. For touch, a non-passive `touchmove` guard,
+attached only while a press is tracked, prevents a downward drag at the top (and every move once
+claimed) so the browser does not take it as a pan and cancel the pointer stream; upward drags keep
+scrolling. Only the scroller's own `lostpointercapture` ends a pull, not the bubbling one from the
+row that held the touch's implicit capture. The disc (with its spinner) is `aria-hidden` and
+`visibility: hidden` until a pull is claimed (so its shadow never bleeds above the content); a
+separate, permanent visually hidden `role="status" aria-live="polite"` region is empty at rest and
+reads "Refreshing" while a refresh runs. It never touches the scroller's `overscroll-behavior`.
+
+Changed: on iOS a touch rides the native bounce. In iOS mode (`BfPlatformService.mode()`) a touch
+press (`pointerType === 'touch'`, or a `touchstart`, tracked with passive listeners) is not
+claimed — no pointer capture, no `preventDefault`, no `touchmove` guard — so the scroller
+rubber-bands natively. While a finger is down, passive `scroll` events with a negative `scrollTop`
+show the disc at its resting −48 px, inside the gap the bounce opens, once `−scrollTop > 8`, with
+`opacity` = progress and `scale(0.6 + 0.4 × progress)` (progress = `min(1, −scrollTop / 64)`) and
+one light haptic at 1. Lifting the last finger at `−scrollTop ≥ 64` sets `refreshing`, settles the
+disc to 0 and emits `refresh`; otherwise the disc hides. A negative `scrollTop` with no finger down
+(a fling's overshoot) never shows it. Material mode and a mouse or pen in iOS mode keep the pull
+unchanged. The host carries `data-bf-refresher` while not `disabled`. A pen press in iOS mode,
+which also fires touch events, never starts a bounce, so its trailing `touchend` cannot hide the
+parked disc; the bounce writes the disc's styles only when it shows, changes or hides, not on
+every scroll; and a scroller change or destroy mid-bounce resets the disc's `opacity`, `transform`
+and `visibility`.