@bitforgehq/ui 0.3.0

package/ai/components/header.md

@@ -0,0 +1,809 @@
+# bf-header
+
+Page header toolbar with a large title that collapses into the toolbar on scroll
+
+`BfHeaderComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfAvatarComponent,
+  BfListComponent,
+  BfListItemComponent,
+  BfToggleComponent,
+} from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+import { formatTodaySubtitle } from '../../today-date';
+
+/** `bf-header` showcase: a large title collapsing over a long list, with a translucent toggle. */
+@Component({
+  selector: 'app-header-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfAvatarComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfToggleComponent,
+  ],
+  template: `
+    <bf-page data-showcase="header">
+      <bf-header title="Header" [subtitle]="subtitle" [translucent]="translucent()">
+        <bf-avatar bfSlot="end" initials="LM" size="sm" variant="ink" />
+      </bf-header>
+      <bf-content>
+        <div class="flex flex-col gap-4 px-4 pt-2 pb-6">
+          <p class="text-caption text-text-muted">
+            Scroll the list: the large title collapses into the toolbar. Translucent lets the list
+            scroll under a blurred header.
+          </p>
+          <bf-list [inset]="false">
+            <bf-list-item>
+              <bf-toggle label="Translucent" labelPosition="start" [(checked)]="translucent" />
+            </bf-list-item>
+            @for (row of rows; track row) {
+              <bf-list-item [title]="'Row ' + row" subtitle="Scroll to collapse the title" />
+            }
+          </bf-list>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HeaderShowcasePage {
+  protected readonly translucent = signal(false);
+  protected readonly rows = Array.from({ length: 30 }, (_, index) => index + 1);
+  protected readonly subtitle = formatTodaySubtitle();
+}
+```
+
+## Overview
+
+The page header: a persistent bar (`start` | title | `end`) and, with `largeTitle` (the
+default), the Meadow Sage large title below it that collapses into the bar's title as the
+page's `bf-content` scrolls. The bar follows the shell mode (`provideBfShell({ mode })`, the
+platform's for `'auto'`): iOS, at least 44 px with a semibold title centred on the bar whatever
+the slots hold (symmetric insets of the wider slot's width plus 8 px, measured with a
+`ResizeObserver`); Material, at least 64 px with a regular title leading after the `start` slot.
+The bar grows with its content at large text sizes: the title wraps to at most two lines (the
+bar is never shorter than the measured title, `--bf-header-title-height`), the `start` slot may
+shrink (a back button drops its text before its chevron; in iOS mode capped by
+`--bf-header-start-max` so the centred title keeps up to half the bar) and the `end` slot never
+does. At
+compact heights (`(max-height: 500px)`, phone landscape) it renders no large title: the title is
+the bar's `h1`, the bar is 44 px in both modes and nothing collapses. Once content scrolls under
+it (the large title fully collapsed; without one, `scrollTop > 0`, overscroll excluded) the
+host gets `data-bf-scrolled`: iOS turns translucent with a blur and a 1 px hairline, Material
+takes a tonal tint. Reads its sibling scroller through the page's `BfPageContext` (set by
+`bf-content`) and, from a passive scroll listener, writes `--bf-header-progress` (0…1, over the
+large title block's rendered height, bounded to 44–200 px (a taller title collapses faster), of the scroll position clamped to the
+scrollable range, so overscroll never moves it, and 0 on a page that cannot scroll that far) on
+its host and the large title block's height (its natural height, measured once and on resize,
+times `1 − progress`), so at progress 1 the header is exactly the toolbar; scrolling schedules
+no Angular change detection. Solid, it also writes the collapsed height as
+`--bf-header-collapse` on the scroller, which `bf-content` adds to its bottom padding: the
+scroller grows by what the header gives up, so its scroll range stays the same through the
+collapse and the short-page rule reads one stable value. When a scroll ends part-way
+(`scrollend`, or 120 ms without a `scroll` event) with nothing pressed on the scroller, it snaps
+the scroller to fully expanded or fully collapsed, whichever is nearer, like UIKit. Solid
+(default), it sits in the page's flow above the content; `translucent`, it is drawn over the
+content and `bf-content` pads its scroller by the header's height (`--bf-header-height`).
+
+The page header: a persistent bar with `start`/`end` slots and, by default, the Meadow Sage large
+title below it that collapses into the bar's title as the page's `bf-content` scrolls. The bar
+follows the shell mode — a bar of at least 44 px with a centred title in iOS mode, at least 64 px
+with a leading title in Material mode — grows with large text, and changes its surface once
+content scrolls under it. It reads its
+sibling scroller through the page's `BfPageContext` (set by `bf-content`) and writes
+`--bf-header-progress` and `data-bf-scrolled` on its own host from a passive scroll listener, so
+the collapse is pure CSS and scrolling never schedules Angular change detection.
+
+## When to use
+
+Use `bf-header` at the top of every `bf-page` in the Capacitor shell: the bar with its start and end actions and the collapsing large title. Use a plain `h1` and a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s instead on a desktop web page, and [bf-back-button](https://bitforge-ui.web.app/components/back-button) in its `start` slot on a pushed page.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A large-title header with a subtitle and an avatar.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-basic',
+  imports: [
+    BfAvatarComponent,
+    BfContentComponent,
+    BfHeaderComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfPageComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Today" subtitle="Wed, 23 Sep">
+        <bf-avatar bfSlot="end" initials="LM" size="sm" />
+      </bf-header>
+      <bf-content>
+        <bf-list>
+          <bf-list-item title="Review the Atlas deck" />
+          <bf-list-item title="Call Bloom" />
+        </bf-list>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HeaderBasicExampleComponent {}
+```
+
+## iOS and Material bars
+
+The mode is the shell's (`provideBfShell({ mode })`, the platform's for `'auto'`: iOS on iOS,
+Material elsewhere), the same one the stack outlet uses for its transitions; the host carries it
+as `data-bf-mode`.
+
+|                | iOS mode                                      | Material mode                                                                    |
+| -------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| Bar height     | at least 44 px (`min-h-11`), grows            | at least 64 px (`min-h-16`), grows                                               |
+| Bar title      | `text-heading`, semibold, centred on the bar  | `text-heading`, regular, leading after `start` (16 px from the edge without one) |
+| Scrolled under | `bg-bg/85`, `backdrop-blur-xl`, 1 px hairline | `surface-muted` tint, no blur, no hairline                                       |
+| Large title    | left-aligned, collapses on scroll             | the same                                                                         |
+
+The bar title sizes are the closest steps of the Meadow Sage type scale: UIKit's 17 pt semibold
+and Material's 22 dp regular title both map to the 18 px `text-heading`, so the modes differ in
+weight and alignment rather than size.
+
+In iOS mode the title is centred on the bar itself, not in the space left between the slots: the
+header measures both slot containers (a `ResizeObserver`) and gives the title symmetric insets of
+the wider slot's width plus 8 px (`--bf-header-title-inset` on the host, measured from the bar's
+edges), so a back button on one side and an avatar on the other never push it off centre. A title
+that does not fit wraps to at most two lines (see [Large text and compact heights](#large-text-and-compact-heights)).
+
+## Detail pages
+
+Turn off `largeTitle` for a pushed page and put `bf-back-button` in `start`: the toolbar title is
+the page's only heading, so nothing collapses.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfBackButtonComponent,
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+import { Share } from 'lucide';
+
+/**
+ * A detail page's header: a back button, a compact title and a share action.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-detail',
+  imports: [
+    BfBackButtonComponent,
+    BfContentComponent,
+    BfHeaderComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+    BfPageComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Task" [largeTitle]="false">
+        <bf-back-button bfSlot="start" />
+        <bf-icon-button bfSlot="end" variant="text" label="Share">
+          <bf-icon [icon]="shareIcon" />
+        </bf-icon-button>
+      </bf-header>
+      <bf-content>
+        <p class="text-body p-4">Review the Atlas deck before the call.</p>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HeaderDetailExampleComponent {
+  protected readonly shareIcon = Share;
+}
+```
+
+## Subtitle eyebrow
+
+`subtitle` renders as a small caption above the large title (e.g. a date); it is dropped along
+with the large title block when `largeTitle` is false.
+
+```ts
+import { Component } from '@angular/core';
+import { BfHeaderComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A header with a subtitle eyebrow above the title.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-subtitle',
+  imports: [BfHeaderComponent],
+  template: `<bf-header title="Today" subtitle="Wed, 23 Sep" />`,
+})
+export class HeaderSubtitleExampleComponent {}
+```
+
+## Start and end slots
+
+`start` (usually `bf-back-button`, or nothing on a root page) and `end` (actions, an avatar)
+are `bfSlot="start"` / `bfSlot="end"` content, projected into the bar on either side of the
+title:
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfHeaderComponent } from '@bitforgehq/ui/mobile';
+import { Plus } from 'lucide';
+
+/**
+ * A header with an action in its end slot.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-slots',
+  imports: [BfHeaderComponent, BfIconButtonComponent, BfIconComponent],
+  template: `
+    <bf-header title="Inbox">
+      <bf-icon-button bfSlot="end" variant="text" label="Compose">
+        <bf-icon [icon]="plusIcon" />
+      </bf-icon-button>
+    </bf-header>
+  `,
+})
+export class HeaderSlotsExampleComponent {
+  protected readonly plusIcon = Plus;
+}
+```
+
+The slots follow each platform's bar conventions:
+
+- **Both modes**: one leading control in `start` — the back button, or a menu or close control.
+- **iOS**: text buttons (`bf-button variant="text"`) for state actions such as Done, Edit and
+  Cancel; plain glyph icon buttons (`bf-icon-button variant="text"`) otherwise; at most two
+  trailing actions in `end`.
+- **Material**: icon buttons only (`bf-icon-button variant="text"`, 24 px glyphs), at most three
+  trailing actions; move the rest into an overflow menu.
+
+Pick per mode with `injectShellMode()` from `@bitforgehq/ui/mobile` (`'ios'` or `'md'`, the same
+resolution the header uses; `resolveShellMode(config, platform)` is the pure form):
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent, BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfBackButtonComponent, BfHeaderComponent, injectShellMode } from '@bitforgehq/ui/mobile';
+import { Pencil } from 'lucide';
+
+/**
+ * A header action that follows the shell mode.
+ *
+ * `injectShellMode()` reads the resolved mode once: iOS shows the state action as text, Material
+ * as an icon button.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-mode',
+  imports: [
+    BfBackButtonComponent,
+    BfButtonComponent,
+    BfHeaderComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <bf-header title="Tasks" [largeTitle]="false">
+      <bf-back-button bfSlot="start" />
+      @if (ios) {
+        <bf-button bfSlot="end" variant="text" size="sm">Edit</bf-button>
+      } @else {
+        <bf-icon-button bfSlot="end" variant="text" label="Edit">
+          <bf-icon [icon]="pencilIcon" />
+        </bf-icon-button>
+      }
+    </bf-header>
+  `,
+})
+export class HeaderModeExampleComponent {
+  protected readonly ios = injectShellMode() === 'ios';
+  protected readonly pencilIcon = Pencil;
+}
+```
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent, BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfBackButtonComponent, BfHeaderComponent } from '@bitforgehq/ui/mobile';
+import { Pencil } from 'lucide';
+
+/**
+ * The same action in the two modes.
+ *
+ * iOS mode: a state action as text. Material mode: the same action as an icon button.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-modes',
+  imports: [
+    BfBackButtonComponent,
+    BfButtonComponent,
+    BfHeaderComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <!-- iOS mode: a state action as text -->
+    <bf-header title="Tasks" [largeTitle]="false">
+      <bf-back-button bfSlot="start" />
+      <bf-button bfSlot="end" variant="text" size="sm">Edit</bf-button>
+    </bf-header>
+
+    <!-- Material mode: the same action as an icon button -->
+    <bf-header title="Tasks" [largeTitle]="false">
+      <bf-back-button bfSlot="start" />
+      <bf-icon-button bfSlot="end" variant="text" label="Edit">
+        <bf-icon [icon]="pencilIcon" />
+      </bf-icon-button>
+    </bf-header>
+  `,
+})
+export class HeaderModesExampleComponent {
+  protected readonly pencilIcon = Pencil;
+}
+```
+
+## Custom title content
+
+Leave `title` empty to project your own title markup instead of plain text — it lands in
+whichever `h1` is active (the large title's when `largeTitle` is true, the toolbar's otherwise):
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfHeaderComponent } from '@bitforgehq/ui/mobile';
+
+/** A workspace picker in the title's place. */
+@Component({
+  selector: 'app-workspace-switcher',
+  imports: [BfSelectComponent],
+  template: `
+    <bf-select size="sm" ariaLabel="Workspace" [options]="workspaces" [(value)]="workspace" />
+  `,
+})
+export class WorkspaceSwitcherComponent {
+  protected readonly workspaces: BfSelectOption[] = [
+    { value: 'studio', label: 'Studio' },
+    { value: 'home', label: 'Home' },
+  ];
+  protected readonly workspace = signal<string | null>('studio');
+}
+
+/**
+ * A header with custom title content.
+ *
+ * Without a `title`, the default slot takes the title's place.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-custom-title',
+  imports: [BfHeaderComponent, WorkspaceSwitcherComponent],
+  template: `
+    <bf-header>
+      <app-workspace-switcher />
+    </bf-header>
+  `,
+})
+export class HeaderCustomTitleExampleComponent {}
+```
+
+## The scroll-collapsing large title
+
+With `largeTitle` (the default), the large title collapses into the toolbar as the page's
+`bf-content` scrolls: the header attaches a passive listener to the scroller registered in
+`BfPageContext` and maps the scroll over the large title's own rendered height (the block with its
+eyebrow and bottom padding, about 70 px at the default text size; at least 44 px, and 56 px until
+it is measured) to `--bf-header-progress` (0 expanded, 1 collapsed), so the collapse ends exactly
+when the title has scrolled away. The range is at most 200 px: a taller title (three lines at the
+largest text sizes) collapses its whole height over 200 px of scroll, so a little faster than it
+scrolls. Inside the collapsing clip the large title fades (`1 − progress`) and rises 8 px
+(`progress × 8px`), so it reads as sliding under the bar rather than being cut off; the bar's title
+fades in (`progress`); and the large title block's height shrinks from its natural height to 0 —
+so at progress 1 the header is exactly the bar (plus the top safe area). All of it follows the
+scroll position directly, with no transition. The natural height is measured
+once the header renders and again only when it resizes (a `ResizeObserver`), never per scroll
+frame, and scrolling schedules no Angular change detection. Used outside a `bf-page` (no
+`BfPageContext` in the injector, e.g. a docs demo), the header simply never collapses.
+
+The collapse behaves like a UIKit large title:
+
+- **Overscroll never moves it.** The progress is computed from the scroll position clamped to the
+  scrollable range (`0` to `scrollHeight − clientHeight`), so a rubber-band past the top or the
+  bottom of the page (the negative or too-large `scrollTop` WebKit reports while bouncing) leaves
+  the header where it was.
+- **The scroll range never changes under it.** A solid header shrinks by the large title's
+  collapsed height, which makes `bf-content`'s scroller that much taller. The header writes the
+  same amount as `--bf-header-collapse` on the scroller (`largeHeight × progress` in px, `0px` at
+  rest, removed on destroy), and `bf-content` adds it to its bottom padding, so the page gains
+  exactly the scroll it would otherwise lose and `scrollHeight − clientHeight` stays the rest
+  range through the whole collapse. A translucent header is drawn over the scroller, which never
+  resizes, so it keeps the compensation at `0px`. While the soft keyboard is up,
+  `bfKeyboardAssist`'s inline bottom padding replaces the compensation (no snap runs then).
+- **Short pages never collapse.** A page whose rest range is under the collapse range (in iOS mode even a
+  page with nothing to scroll overflows by 1 px, so WebKit rubber-bands it) keeps its large title
+  expanded — it could never collapse fully, so it must not stop half-way. A page with a longer
+  rest range collapses fully and stays collapsed, even when the content itself (without the
+  compensation) scrolls less than the collapse range once the header has shrunk.
+- **It snaps on scroll end.** When a scroll ends part-way (`scrollend` where the engine fires it,
+  otherwise 120 ms without a `scroll` event) and no finger or pointer is down on the scroller, the
+  header scrolls the page to fully expanded (`0`, below half-way) or fully collapsed (the collapse
+  range), with
+  a smooth scroll (instant under `prefers-reduced-motion`). It waits while a finger holds the page
+  and snaps once it lifts and the momentum has settled (a tap that did not scroll never snaps); its own scroll never triggers another
+  snap, and it does not snap while the soft keyboard is up (`bfKeyboardAssist` owns the scroll
+  then) or on a page that is not the visible one.
+
+## Scroll-under appearance
+
+Once content scrolls under the bar the host gets `data-bf-scrolled`, removed again when it
+leaves. With a large title that is when the title has fully collapsed (the end of the collapse
+range, with 0.5 px of tolerance for a fractional snap landing): like UIKit, the large title belongs
+to the scroll-edge appearance, so the bar changes as soon as it is gone, including after a snap to
+collapsed (a page too short to collapse never gets it). Without a large title (`largeTitle` false) it is as soon as the
+page leaves its top (`scrollTop > 0`, read clamped so a rubber-band past the top does not count,
+on pages of any length). The bar signals it the platform's way:
+
+- **iOS**: opaque `bg-bg` at rest; scrolled under, translucent `bg-bg/85` with `backdrop-blur-xl`
+  and a 1 px `border` hairline along the bottom of the whole header (under the collapsed large
+  title block too). The hairline is the host's `::after`, so it never changes the header's height.
+- **Material**: never a hairline or blur; scrolled under, the surface takes the `surface-muted`
+  tint, with a 150 ms colour transition (`motion-safe` only).
+
+## Large text and compact heights
+
+The header keeps its content at the largest text sizes (iOS Dynamic Type up to 235 %, Android
+font scale 2.0):
+
+- **The bar grows.** Its height is a minimum (`min-h-11` in iOS mode, `min-h-16` in Material
+  mode), so larger text and taller slot content make it taller instead of clipping. The iOS title
+  box is absolutely positioned to stay centred, so the header measures the title
+  (`--bf-header-title-height`, in the same `ResizeObserver` pass as the slot insets) and keeps the
+  bar at least that tall.
+- **The bar title wraps** to at most two lines (`line-clamp-2`, breaking a long word anywhere)
+  instead of truncating; the iOS title centres each line.
+- **The `start` slot may shrink, the `end` slot never does**, so actions stay whole. A
+  `bf-back-button` in `start` lets its text truncate and then disappear before the chevron, as
+  UIKit drops the back title when space is short. In iOS mode, where the centred title sits out of
+  the row's flow, the header caps the slot (`--bf-header-start-max`) only when the title does not
+  fit on one line beside the slots at their full width: the title may then claim up to half the
+  bar, and only a back button's text gives way. The cap never goes below the slot's other content
+  (two icon buttons stay whole) or one 44 px hit area, so a custom back label such as "Projects"
+  stays whole beside a short title and truncates only beside a long or large one. A title
+  projected as content (no `title` input) is not measured, so it gets no cap.
+- **The large title is capped at 200 %** (80 px text on 88 px lines, `min(var(--text-display),
+80px)`), in px because Dynamic Type scales the root and so every rem; it still wraps, and the
+  collapse follows its real height.
+
+```ts
+import { Component } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfBackButtonComponent,
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+} from '@bitforgehq/ui/mobile';
+import { Share } from 'lucide';
+
+/**
+ * A long title wraps to two lines and the bar grows with it; the back text gives way first.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-long-title',
+  imports: [
+    BfBackButtonComponent,
+    BfContentComponent,
+    BfHeaderComponent,
+    BfIconButtonComponent,
+    BfIconComponent,
+    BfPageComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Prepare the quarterly review for the studio" [largeTitle]="false">
+        <bf-back-button bfSlot="start" label="Today" />
+        <bf-icon-button bfSlot="end" variant="text" label="Share">
+          <bf-icon [icon]="shareIcon" />
+        </bf-icon-button>
+      </bf-header>
+      <bf-content>
+        <p class="text-body p-4">Collect the numbers from every project before Friday.</p>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HeaderLongTitleExampleComponent {
+  protected readonly shareIcon = Share;
+}
+```
+
+At compact heights (`(max-height: 500px)`: phone landscape, split screen) there is no room for a
+large title. The header then renders none: the title is the bar's `h1`, the bar is at least 44 px
+in both modes, and nothing collapses or snaps. The header follows the media query live
+(`matchMedia`, the listener removed with the header), so rotating back to portrait brings the
+large title back. With `bf-tabs`, the tab bar slims down too, so at least 60 % of the height is
+content.
+
+## Translucent
+
+```ts
+import { Component } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A translucent header the content scrolls under.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-header-translucent',
+  imports: [
+    BfContentComponent,
+    BfHeaderComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfPageComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Today" [translucent]="true" />
+      <bf-content>
+        <bf-list>
+          @for (row of rows; track row) {
+            <bf-list-item [title]="'Task ' + row" />
+          }
+        </bf-list>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HeaderTranslucentExampleComponent {
+  protected readonly rows = Array.from({ length: 30 }, (_, i) => i + 1);
+}
+```
+
+By default (solid) the header sits in the page's column above `bf-content`, on an opaque `bg-bg`.
+With `translucent` it is taken out of the flow instead — `absolute top-0 inset-x-0 z-(--bf-z-sticky)` over the
+content, with the same per-mode scroll-under surface — and `bf-content` fills the whole page. The header
+publishes its expanded height through `BfPageContext`, and `bf-content` writes it as
+`--bf-header-height` on its scroller and pads its top by it (`pt-(--bf-header-height,0px)`, also
+as `scroll-padding-top`), so the first row starts below the header and content scrolls under the
+bar (under the blur in iOS mode). Without a `bf-page` (no `BfPageContext`) nothing pads the content, so use `translucent` only
+inside one.
+
+## Desktop
+
+`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page, give the page a plain `h1` and put its actions in a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s and a [bf-menu-button](https://bitforge-ui.web.app/components/menu-button); the large title and the scroll-under surface are phone patterns. Under the shell, a browser window shorter than 500 px gets the compact bar (no large title), as a phone in landscape does.
+
+## Theming
+
+- Background: `bg` at rest in both modes; scrolled under, `bg/85` with `backdrop-blur-xl` (iOS) or
+  `surface-muted` (Material), on the host.
+- Hairline: iOS only, 1 px `border` under the whole header while scrolled under.
+- Type: large title `text-display`, capped at 80/88 px; bar title `text-heading` (semibold in iOS mode, regular in
+  Material mode); the `subtitle` eyebrow `text-caption`.
+- Text: large title and bar title in `text`; the `subtitle` eyebrow in `text-muted`.
+- Spacing: the large title block is inset by the 16 px screen gutter (`px-gutter`), so it lines up
+  with page content padded the same way. The toolbar is padded by the top safe area
+  (`pt-safe-top`) while the page's `BfPageContext.safeAreaTop` is true; a page-sheet `bf-modal`
+  sets it to false, since its card already sits below the status bar, so the header adds no
+  second status-bar band there.
+- Variables it writes: `--bf-header-progress` (0…1), `--bf-header-title-inset` (px),
+  `--bf-header-title-height` (px) and, in iOS mode, `--bf-header-start-max` (px) on its host, `--bf-header-collapse` (px) on the page's scroller.
+- Attributes it writes on its host: `data-bf-mode` (`ios` or `md`) and `data-bf-scrolled` (while
+  content is under the bar), usable for app-level styling.
+
+## Accessibility
+
+Exactly one `h1` is ever rendered — the large title's when `largeTitle` is true, the toolbar's
+otherwise — and it carries `data-bf-page-title`, the element `bf-stack-outlet` focuses after a
+push so a screen reader announces where navigation landed. With `largeTitle`, the toolbar shows a
+second, `aria-hidden="true"` mirror of the title purely for the visual collapse; it carries no
+semantics of its own. `prefers-reduced-motion` drops the large title's upward translate, the Material tint's colour
+transition and makes the scroll-end snap instant; the fade and the height collapse follow the
+scroll position directly (direct manipulation, not an animation). The centred iOS title box is
+`pointer-events-none` so it never covers a slot; custom content projected into the toolbar `h1`
+stays interactive. At the largest text sizes nothing in the bar clips (WCAG 1.4.4): the bar grows,
+the title wraps and the back text gives way before any action.
+
+### Keyboard
+
+The header has no keys of its own: its slots set the order in which Tab reaches the page actions.
+The title is not in the tab order; after a push, `bf-stack-outlet` focuses it with
+`tabindex="-1"`.
+
+| Key                                              | Action                                                                     |
+| ------------------------------------------------ | -------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the start slot's controls, then the end slot's, in DOM order |
+
+## Inputs
+
+| Name          | Type      | Default | Description                                                                                                                                                                             |
+| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`  | `''`    | The page title, rendered in the toolbar and, with `largeTitle`, in the large title block.                                                                                               |
+| `subtitle`    | `string`  | `''`    | Eyebrow line above the large title (e.g. a date); rendered only with `largeTitle`.                                                                                                      |
+| `largeTitle`  | `boolean` | `true`  | Renders the collapsing large title block below the toolbar; never at compact heights (`(max-height: 500px)`), where the title is the bar's `h1`.                                        |
+| `translucent` | `boolean` | `false` | Draws the header over the content (`absolute`) instead of in the page's flow, so content scrolls under its scroll-under surface; `bf-content` pads its scroller by the header's height. |
+
+## Slots
+
+- `start`: Toolbar buttons at the start, such as `bf-back-button`.
+- `default`: The toolbar title, when the `title` input is empty.
+- `end`: Toolbar buttons at the end.
+
+## Notes
+
+### Do
+
+- Give every page exactly one `bf-header` (or another element carrying `data-bf-page-title`) so
+  push focus has somewhere to land.
+- Turn off `largeTitle` on pushed detail pages; keep it on tab roots.
+- Put `bf-back-button` in `start` on any page that isn't a tab root.
+- iOS: use text buttons for Done, Edit and Cancel and plain glyph icons otherwise, at most two in
+  `end`. Material: use icon buttons only, at most three in `end`.
+
+### Don't
+
+- Don't put a text button in a Material bar or a filled icon button in an iOS bar, and don't put
+  more than one control in `start`.
+- Don't put more than one `h1` in a page's header — the toolbar mirror is `aria-hidden` on
+  purpose, not a second heading.
+- Don't expect the collapse to run without a `bf-content` inside the same `bf-page`; the header
+  reads the scroller `bf-content` registers in `BfPageContext`.
+
+## Migration notes
+
+### 0.3.0
+
+JSDoc of `header.component.ts` for the API reference: `@slot` docs for `start`, `default`, `end`. No
+behaviour change.
+
+The toolbar pads the top safe area (`pt-safe-top`) only while the page's
+`BfPageContext.safeAreaTop()` is true; inside a page-sheet `bf-modal` (false) it adds none
+(Migration 29).
+
+**Behaviour:** large text (F-051). The bar has a minimum height instead of a fixed one
+(`min-h-11` in iOS mode, `min-h-16` in Material mode) and grows with its content; the header
+measures the bar title as `--bf-header-title-height` (the same `ResizeObserver` pass as the slot
+insets) and keeps the bar at least that tall, since the centred iOS title box is absolutely
+positioned. The bar title wraps to at most two lines (`line-clamp-2 wrap-anywhere`, centred in iOS
+mode) instead of truncating. The `start` slot may shrink (`min-w-0 shrink`) and the `end` slot
+never does (`shrink-0`), so actions stay whole. In iOS mode, where the centred title is taken out
+of the row's flow, the `start` slot is capped by `--bf-header-start-max` only when the title does
+not fit on one line beside the slots at their full width: the title may then claim up to half the
+bar, and only a back button's text (`bf-back-button`'s `[data-bf-back-text]`) gives way. The cap
+is never below the slot's other content or 44 px, so two start buttons stay whole, and the title
+inset reads the slot's `scrollWidth` too. It is measured from the bar's width, a hidden one-line
+copy of the title and the slot's full and minimum widths, so it never depends on the capped slot
+itself. A projected title (no `title` input) gets no cap. The large title's font and line height are capped
+at 200 % (`min(var(--text-display), 80px)`, `min(var(--text-display--line-height), 88px)`), in px
+because iOS Dynamic Type scales the root.
+
+**Behaviour:** the collapse range is the large title block's rendered height, bounded to 44–200 px
+(was a fixed 56 px, while the iOS large title renders about 70 px; a block taller than 200 px
+collapses its whole height over 200 px of scroll), re-read whenever it resizes; the snap goes to
+it; `data-bf-scrolled` switches on at full collapse, as before, now at that height (with 0.5 px of
+tolerance for a fractional snap landing). See Migration 31.
+
+**Behaviour:** compact heights (F-054). Under `(max-height: 500px)` (phone landscape, split
+screen; read with `matchMedia` and followed live, the listener removed on destroy) the header
+renders no large title: the title is the bar's `h1`, the bar is at least 44 px in both modes and
+nothing collapses or snaps.
+
+**Behaviour:** without a large title (`largeTitle` false, or a compact height) the scroll never
+moves `--bf-header-progress` and never snaps; a detail page used to snap to 0 or 56 px when a
+scroll stopped in its first 56 px.
+
+### 0.2.0
+
+New `bf-header`: a 44 px toolbar (`pt-safe-top`, `start` | title | `end` slots, `bfSlot="start"` /
+`bfSlot="end"`) and, with `largeTitle` (default `true`), a Meadow Sage large title
+(`text-display`) below it with an optional `subtitle` eyebrow (`text-caption text-text-muted`)
+above the title. Exactly one `h1` carries `data-bf-page-title`, the focus target `bf-stack-outlet`
+moves to after a push — the large title's when `largeTitle` is true, the toolbar's otherwise; with
+`largeTitle`, the toolbar shows a second, `aria-hidden="true"` `span` mirror of the title for the
+visual collapse only. `title` empty projects the default-slot content into whichever `h1` is
+active instead. Reads its sibling scroller from the page's `BfPageContext` (set by `bf-content`)
+through an `effect`: once non-null it attaches a passive `scroll` listener that maps the first
+56 px of scroll to `--bf-header-progress` (0…1, 3 decimals, written to the host only when it
+changes) and detaches on scroller change or destroy. That variable drives the large title's
+opacity and an 8 px upward translate, the toolbar mirror's fade-in and a `divider` hairline that
+fades in with it; the same listener sets the large title block's height to its natural height (measured
+after render and on `ResizeObserver` changes, never per frame) times `1 − progress`, so at
+progress 1 the header is exactly the toolbar. Scrolling schedules no Angular change detection;
+`prefers-reduced-motion` drops the translate. Solid (default), the header is in the page's flow on
+`bg-bg`; `translucent` draws it over the content (`absolute inset-x-0 top-0 z-(--bf-z-sticky)`,
+`bg-bg/85 backdrop-blur`) and publishes its expanded height in `BfPageContext.headerHeight`, which
+`bf-content` pads its scroller by. The large title block is inset by the 16 px screen gutter
+(`px-gutter`, was `px-5`), so it lines up with page content padded the same way.
+
+Fixed: the large title no longer sits half-collapsed or collapses during a rubber-band. The
+progress is computed from `scrollTop` clamped to `[0, scrollHeight − clientHeight]`, so overscroll
+past either end never moves the header, and stays 0 on a page that cannot scroll the full 56 px
+(such as a short iOS page, whose body overflows by only 1 px). When a scroll ends part-way
+(`scrollend`, or 120 ms without a `scroll` event, whichever comes first) with no touch or pointer
+down on the scroller (passive `touchstart`/`touchend`/`touchcancel` and
+`pointerdown`/`pointerup`/`pointercancel` listeners), the header scrolls the scroller to 0 below
+half-way, else to 56 px (`behavior: 'smooth'`, `'instant'` under `prefers-reduced-motion`). The
+snap's own scroll never schedules another, and it is skipped while `BfKeyboardService.visible()`
+is true, on a page hidden by `visibility` (`checkVisibility({ visibilityProperty: true })`) and
+after destroy; its timer is cleared on scroller change and destroy. A mouse released outside the
+scroller is heard on the `document` (`pointerup`/`pointercancel`, listened to only while a press
+is tracked), and a press released without a scroll in between (a tap) schedules no snap.
+
+Fixed: on a page whose rest scroll range lies between 56 px and 56 px plus the large title's
+height, the header flipped between open and part-collapsed on every frame (measured on a search
+page at 393 × 800: `scrollTop/max@progress` `40/72@0 → 35/35@0.714 → 40/72@0 …`): the collapse made
+the scroller taller, the range fell under 56 and the short-page rule reset the progress. The header
+now writes the collapsed height (`largeHeight × progress` in px, the exact height the block gave
+up; `0px` at rest, when translucent or without a large title) as `--bf-header-collapse` on the
+page's scroller together with `--bf-header-progress`, and removes it on destroy (or from a
+replaced scroller); `bf-content` pads the scroller's bottom by it, so `scrollHeight − clientHeight`
+stays the rest range and the short-page rule and the clamp read one stable value.
+
+Fixed: the centred toolbar title sat in the space left between the `start` and `end` slots, so a
+back button or an avatar pushed it off the bar's centre. It is now laid out over the whole toolbar
+row (`absolute`, `pointer-events-none`, truncating) with symmetric insets: the header measures both
+slot containers with its `ResizeObserver` and writes `--bf-header-title-inset` (the 8 px row
+padding + the wider slot's width + 8 px; 16 px without slots) on its host, which the title box
+uses for `left` and `right`.
+
+Changed: the bar follows the shell mode (`provideBfShell({ mode })`, the platform's for `'auto'`,
+resolved like `bf-stack-outlet`; the host carries `data-bf-mode`). iOS: a 44 px bar with the
+title (`text-heading font-semibold`, the closest step to UIKit's 17 pt semibold) centred on it.
+Material: a 64 px bar with the title (`text-heading font-normal`, 18 px, the closest step to
+Material's 22 dp regular title) leading after the `start` slot, 16 px from the edge without one,
+never centred. The large title stays left-aligned and collapses the same way in both modes.
+
+Changed: scroll-under appearance. The scroll listener also sets `data-bf-scrolled` on the host
+while content is under the bar: with a large title once it has fully collapsed (progress 1; like
+UIKit, the large title is part of the scroll-edge bar, so a page too short to collapse never gets
+it), without one (`largeTitle` false) while `scrollTop` (clamped, so a rubber-band past the top does
+not count) is above 0, on any page length. iOS: opaque `bg-bg` at rest; scrolled under, `bg-bg/85` with `backdrop-blur-xl` and a 1 px
+`border`-coloured hairline under the whole header (the host's `::after`, so the header's height
+never changes; it replaces the `divider` hairline that faded in with the collapse). Material: no
+hairline ever; scrolled under, a `surface-muted` tint with a 150 ms colour transition
+(`motion-safe`) and no blur. `translucent` keeps its meaning (drawn over the content, which
+`bf-content` pads) and now takes the same per-mode surface instead of a permanent
+`bg-bg/85 backdrop-blur`.
+
+Changed: the large title's exit is spelled in utilities instead of component CSS (the header has
+no `styles` any more): inside the collapsing clip the block fades (`opacity: 1 − progress`) and
+rises 8 px (`translateY(−8px × progress)`, `motion-safe` only, so reduced motion keeps the fade
+and drops the rise), and the toolbar mirror fades in (`opacity: progress`), all read from
+`--bf-header-progress`, never transitioned.