@bitforgehq/ui 0.3.0

package/ai/components/content.md

@@ -0,0 +1,474 @@
+# bf-content
+
+Page's single scroll container that keeps focused fields clear of the soft keyboard
+
+`BfContentComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, signal, viewChild } from '@angular/core';
+import { BfButtonComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/** `bf-content` showcase: a long scroller reporting its offset, with scroll-to-top buttons. */
+@Component({
+  selector: 'app-content-showcase',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfButtonComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-page data-showcase="content">
+      <bf-header title="Content" [largeTitle]="false">
+        <bf-button bfSlot="end" variant="text" size="sm" (clicked)="toTop()">Top</bf-button>
+      </bf-header>
+      <bf-content [scrollEvents]="true" (scrolled)="scrollTop.set($event.scrollTop)">
+        <div class="flex flex-col gap-4 p-4">
+          <p class="text-caption text-text-muted">
+            The page's only scroller. Scroll down, then tap Top (or the button at the end) to scroll
+            back smoothly.
+          </p>
+          <p data-showcase-result class="text-body">Scrolled {{ scrollTop() }} px</p>
+          <bf-list [inset]="false">
+            @for (row of rows; track row) {
+              <bf-list-item [title]="'Item ' + row" />
+            }
+          </bf-list>
+          <bf-button variant="tonal" (clicked)="toTop()">Back to top</bf-button>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ContentShowcasePage {
+  private readonly content = viewChild.required(BfContentComponent);
+
+  protected readonly scrollTop = signal(0);
+  protected readonly rows = Array.from({ length: 40 }, (_, index) => index + 1);
+
+  toTop(): void {
+    this.content().scrollToTop();
+  }
+}
+```
+
+## Overview
+
+The page's single scroll container: fills the rest of `bf-page` under the header, keeps the
+focused text control clear of the soft keyboard (`bfKeyboardAssist`), pads for the horizontal
+safe areas, for the floating tab bar (`--bf-tab-bar-inset`), for a `translucent` header drawn
+over it (`--bf-header-height`, from `BfPageContext`) and at the bottom for the height a solid
+`bf-header` has collapsed by (`--bf-header-collapse`, written by the header, so the scroll range
+stays the same while the large title collapses), and contains overscroll so the document
+never scrolls. On iOS (`ios.scrollEnabled: false`) it is the only thing that scrolls. The
+projected content sits in a block body inside the scroller: in iOS mode the body is 1 px taller
+than the scroller, so WebKit rubber-bands even a short page; in Material mode the scroller gets
+`bfOverscrollStretch`, the Android edge stretch the WebView does not draw itself, except in iOS
+WebKit (Safari or a home-screen app, platform `web`), which rubber-bands natively. Both follow the
+engine (`BfPlatformService.mode()`), not `provideBfShell({ mode })`. In the page a
+`bf-stack-outlet` shows, the scroller is the document's `main` landmark (`role="main"`; not in a
+`bf-modal`, see `BfPageContext.mainLandmark`). While it overflows and holds nothing focusable,
+it is a tab stop (`tabindex="0"`), so a keyboard can scroll it in Safari too (axe
+`scrollable-region-focusable`); otherwise Tab reaches its controls and the arrow keys scroll it.
+
+The page's single scroll container. `bf-content` fills the rest of a `bf-page` under its header,
+scrolls vertically with `overscroll-behavior: contain`, pads for the left and right safe areas and
+for the floating tab bar, and keeps the focused text control clear of the soft keyboard. On iOS the
+app runs with `ios.scrollEnabled: false`, so the document itself never scrolls: `bf-content` is the
+only scroller, and everything that should scroll — lists, forms, pull-to-refresh — goes inside it.
+
+## When to use
+
+Use `bf-content` as the one scroll container of every `bf-page` in the Capacitor shell, after the page's [bf-header](https://bitforge-ui.web.app/components/header). Use the document's own scrolling instead on a desktop web page, and the [bfKeyboardAssist](https://bitforge-ui.web.app/api/bf-keyboard-assist-directive) directive only for a custom scroller that is not a `bf-content`.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * A page's scrolling content.
+ *
+ * `bf-content` is the page's scroll container, clear of the header and the safe areas.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-content-basic',
+  imports: [BfContentComponent, BfListComponent, BfListItemComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-content>
+        <bf-list>
+          <bf-list-item title="Inbox" />
+          <bf-list-item title="Archive" />
+        </bf-list>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ContentBasicExampleComponent {}
+```
+
+## The only scroller
+
+Use one `bf-content` per page and put every scrollable part of the page inside it. The host is a
+`flex-1 min-h-0` child of `bf-page`'s column, so it takes the height left under a header and its
+inner scroller (`h-full overflow-y-auto`) does the scrolling. With the required
+`capacitor.config` (`ios: { scrollEnabled: false }`), content placed outside `bf-content` does not
+scroll at all on iOS. A horizontal row inside it (a chips row or a carousel with
+`overflow-x-auto`) pans on its own; it needs no directive.
+
+## Fullscreen
+
+Without a header above it, set `fullscreen` so the content starts below the status bar
+(`pt-safe-top`) instead of under it. Inside a page-sheet `bf-modal`, whose card already sits below
+the status bar (`BfPageContext.safeAreaTop` false), `fullscreen` adds no top padding.
+
+```ts
+import { Component } from '@angular/core';
+import { BfContentComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * Content that runs under the status bar.
+ *
+ * `fullscreen` drops the top safe-area padding, for a page without a header.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-content-fullscreen',
+  imports: [BfContentComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-content [fullscreen]="true">
+        <h1 data-bf-page-title class="text-display">Today</h1>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ContentFullscreenExampleComponent {}
+```
+
+## Keyboard assist
+
+`bf-content` applies `bfKeyboardAssist` to its scroller. When the soft keyboard opens it pads the
+scroller by the part the keyboard covers and scrolls the focused `input`, `textarea` or
+`[contenteditable]` until it sits 24 px above the keyboard, after the engine's own focus scroll,
+with one correction once the keyboard has settled. Focus moving to the next field while the
+keyboard is open reveals that one too. Turn it off with `keyboardAssist` for a screen that manages
+the keyboard itself, such as a chat with a composer pinned above the keyboard.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfTextareaComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/** A chat that keeps its composer above the keyboard itself. */
+@Component({
+  selector: 'app-chat-thread',
+  imports: [BfButtonComponent, BfTextareaComponent],
+  template: `
+    <div class="flex h-full flex-col">
+      <ul class="flex flex-1 flex-col gap-2 p-4">
+        @for (message of messages(); track $index) {
+          <li class="bg-surface rounded-card p-3">{{ message }}</li>
+        }
+      </ul>
+      <div class="pb-safe-bottom bg-bg sticky bottom-0 flex items-end gap-2 p-2">
+        <bf-textarea class="flex-1" ariaLabel="Message" [rows]="1" [(value)]="draft" />
+        <bf-button (clicked)="send()">Send</bf-button>
+      </div>
+    </div>
+  `,
+})
+export class ChatThreadComponent {
+  protected readonly messages = signal(['Is the deck ready?']);
+  protected readonly draft = signal('');
+
+  protected send(): void {
+    this.messages.update((messages) => [...messages, this.draft()]);
+    this.draft.set('');
+  }
+}
+
+/**
+ * Content without the keyboard assist.
+ *
+ * `[keyboardAssist]="false"` leaves the keyboard to a screen that handles it itself, such as a
+ * chat with a composer pinned above the keyboard.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-content-keyboard',
+  imports: [BfContentComponent, BfPageComponent, ChatThreadComponent],
+  template: `
+    <bf-page>
+      <bf-content [keyboardAssist]="false">
+        <app-chat-thread />
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ContentKeyboardExampleComponent {}
+```
+
+## Overscroll
+
+The projected content sits in a block body inside the scroller, so an overscroll effect can move
+the body without touching the scroller's own padding.
+
+- **iOS**: WebKit rubber-bands a scroller only when its content overflows. In iOS mode the body is
+  at least 1 px taller than the scroller (`min-h-[calc(100%+1px)]`), so a short page bounces like a
+  native list too; the 1 px of scroll is imperceptible.
+- **Android**: the WebView draws no overscroll effect for an inner scroller. In Material mode the
+  scroller carries `bfOverscrollStretch`, which stretches the body at the top or bottom edge under
+  the finger and springs it back. With an enabled `bf-refresher` on the page, only the bottom edge
+  stretches; the top pull belongs to the refresher.
+- **iOS Safari and home-screen apps**: Capacitor reports platform `web` there, so the mode is
+  Material, but WebKit rubber-bands natively. `bf-content` detects iOS WebKit (an iPhone, iPad or
+  iPod user agent, or an iPad that reports `MacIntel` with touch points) and leaves the stretch
+  off, so it never stacks on the bounce.
+
+The overscroll follows the engine (`BfPlatformService.mode()`, iOS only on native iOS), not
+`provideBfShell({ mode })`: forcing `mode: 'ios'` on Android keeps the stretch and the Material pull,
+and forcing `mode: 'md'` on iOS keeps the bounce. The bounce is WebKit's, and the refresher's iOS
+mode reads it from a negative `scrollTop`; Chrome never reports a negative `scrollTop`, so an
+Android WebView in the iOS look would get neither a bounce nor a working pull-to-refresh.
+
+## Tab bar inset
+
+Inside `bf-tabs`, the floating tab bar sets `--bf-tab-bar-inset` and `bf-content` pads its bottom
+by it (`0px` outside tabs), so the last row scrolls clear of the bar.
+
+## Large-title compensation
+
+A solid `bf-header` above the scroller shrinks as its large title collapses, and the scroller grows
+by the same height. The header writes that height as `--bf-header-collapse` on the scroller, and
+`bf-content` adds it to the bottom padding
+(`pb-[calc(var(--bf-tab-bar-inset,0px)+var(--bf-header-collapse,0px))]`), so the scroll range stays
+the same through the collapse and a page that scrolls just over the 56 px collapse range never
+flips between expanded and collapsed. While the soft keyboard is up, the keyboard assist's inline
+bottom padding takes over.
+
+## Scroll events and scrolling
+
+`scrolled` emits a `BfContentScrollEvent` (`{ scrollTop }`) from a passive listener, but only while `scrollEvents` is true, so
+plain pages add no scroll listener and no change detection while scrolling. `scrollToTop()` and
+`scrollToPoint(x, y)` scroll smoothly by default; `scrollElement` returns the scroll container.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+/**
+ * Scroll events and scrolling to the top.
+ *
+ * `scrollEvents` turns on `scrolled`; the template reference calls `scrollToTop()`.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-content-scroll',
+  imports: [
+    BfButtonComponent,
+    BfContentComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfPageComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-content #content [scrollEvents]="true" (scrolled)="onScroll($event.scrollTop)">
+        <bf-list>
+          @for (row of rows; track row) {
+            <bf-list-item [title]="'Task ' + row" />
+          }
+        </bf-list>
+        @if (scrolledDown()) {
+          <bf-button (clicked)="content.scrollToTop()">Back to top</bf-button>
+        }
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class ContentScrollExampleComponent {
+  protected readonly rows = Array.from({ length: 40 }, (_, i) => i + 1);
+  protected readonly scrolledDown = signal(false);
+
+  protected onScroll(scrollTop: number): void {
+    this.scrolledDown.set(scrollTop > 400);
+  }
+}
+```
+
+## Desktop
+
+`bf-content` is part of the Capacitor shell (`provideBfShell()`). A desktop web app lets the document scroll: put the page in your own layout (a `main` that scrolls with the window) and leave `bf-page`, `bf-content` and `bf-stack-outlet` out. Inside the shell on a desktop browser, wheel, trackpad and keyboard scrolling are the browser's own, the keyboard assist adds nothing (no soft keyboard), and the Android stretch never starts (it follows touch only). Safari does not let the keyboard reach a scroll container with nothing focusable in it, so while the content overflows and holds no control, the scroller is a tab stop itself: <kbd>Tab</kbd> focuses it (with the focus ring) and the arrow keys, <kbd>Page Down</kbd> and <kbd>Space</kbd> scroll it. With a control inside, Tab reaches the control instead and the scroller stays out of the Tab order.
+
+## Theming
+
+- Background: none of its own; it shows `bg` from the surrounding `bf-page`.
+- Spacing: `--spacing-safe-left` / `--spacing-safe-right` (horizontal safe areas),
+  `--spacing-safe-top` when `fullscreen` (not inside a page-sheet modal), and `--bf-tab-bar-inset` plus `--bf-header-collapse`
+  (bottom, set by the tab bar and by a solid `bf-header` while its large title is collapsed, both
+  default `0px`).
+- Focus ring (only while the scroller is a tab stop): `ring` at `ring-4`, inset.
+- Layout: host `block min-h-0 flex-1`; scroller `h-full overflow-y-auto overscroll-contain
+touch-pan-y`; inside it a plain block body wraps the projected content (`min-h-[calc(100%+1px)]`
+  in iOS mode). Add your own padding on the content inside it. The body's height is `auto`, so a
+  child can no longer fill the page with `h-full`: percentage heights (`h-full`, `min-h-full`, and
+  the `flex-1` of a wrapper sized with them) resolve to nothing there. Size such a child from its
+  content or the viewport on your own wrapper (a centred empty state: `min-h-[60dvh]`), not with
+  `h-full`.
+- Page gutter: pad page content with the 16 px screen gutter (`px-gutter` or `p-4`), the inset the
+  header's large title, toasts and alert dialogs use, so text lines up down the screen.
+
+## Accessibility
+
+In the page a `bf-stack-outlet` shows, the scroller is the document's `main` landmark
+(`role="main"`, from `BfPageContext.mainLandmark`), so there is exactly one `main` at any time:
+parked pages are `aria-hidden`, and the content of a `bf-modal` (or of a `bf-page` outside an
+outlet, such as a docs illustration) is no landmark. While the scroller overflows and holds nothing
+focusable it is a tab stop (`tabindex="0"`, axe `scrollable-region-focusable`), so a keyboard can
+scroll it in Safari; once a control appears inside, it leaves the Tab order again. Controls that
+are `hidden`, inside an `inert` or `hidden` subtree or not rendered (`display: none`) do not count,
+and the 1 px the iOS body adds for the rubber band is not overflow. The page's
+heading comes from its content. The keyboard assist keeps the focused control visible above the soft keyboard, so what is
+typed is always on screen, and it never moves focus. `overscroll-contain` keeps a scroll gesture
+from chaining into the document or a parent scroller, and `touch-pan-y` leaves horizontal drags to
+the edge swipe-back. The overscroll is pure feel, with no behaviour of its own: on iOS every page
+bounces, short ones too, and on Android the content stretches at both edges; neither moves focus,
+changes what is read, or prevents a touch, and the Android stretch springs back instantly under
+`prefers-reduced-motion`.
+
+### Keyboard
+
+| Key                                                          | Where                                     | Action                                |
+| ------------------------------------------------------------ | ----------------------------------------- | ------------------------------------- |
+| <kbd>Tab</kbd>                                               | Content with nothing focusable, scrolling | Focuses the scroller                  |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>                    | Scroller or a control inside it           | Scrolls (the browser's own)           |
+| <kbd>Page Up</kbd> / <kbd>Page Down</kbd> / <kbd>Space</kbd> | Scroller                                  | Scrolls by a page (the browser's own) |
+
+## Inputs
+
+| Name             | Type      | Default | Description                                                                                             |
+| ---------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `fullscreen`     | `boolean` | `false` | Extends the content under the status bar: adds the top safe-area padding (no header above).             |
+| `keyboardAssist` | `boolean` | `true`  | Keeps the focused text control clear of the soft keyboard; false for screens that handle it themselves. |
+| `scrollEvents`   | `boolean` | `false` | Emits `scrolled` on every scroll; off by default so plain pages add no listener.                        |
+
+## Outputs
+
+| Name       | Payload                | Description                                                                   |
+| ---------- | ---------------------- | ----------------------------------------------------------------------------- |
+| `scrolled` | `BfContentScrollEvent` | The scroller's `scrollTop` on each scroll, only while `scrollEvents` is true. |
+
+## Slots
+
+- `default`: The page content, in the scroll container.
+
+## Methods
+
+### `scrollToTop(behavior?: ScrollBehavior): void`
+
+Scrolls back to the top (e.g. on a second tap of the active tab).
+
+| Parameter   | Type             | Description                          |
+| ----------- | ---------------- | ------------------------------------ |
+| `behavior?` | `ScrollBehavior` | `smooth` (the default) or `instant`. |
+
+### `scrollToPoint(x: number, y: number, behavior?: ScrollBehavior): void`
+
+Scrolls to the given offset in px.
+
+| Parameter   | Type             | Description                          |
+| ----------- | ---------------- | ------------------------------------ |
+| `x`         | `number`         | The horizontal offset (px).          |
+| `y`         | `number`         | The vertical offset (px).            |
+| `behavior?` | `ScrollBehavior` | `smooth` (the default) or `instant`. |
+
+## Notes
+
+### Do
+
+- Use exactly one `bf-content` per `bf-page`, after the header.
+- Pad the page content with the 16 px gutter (`px-gutter`), so it aligns with the large title.
+- Keep `keyboardAssist` on for any page with text fields.
+- Set `scrollEvents` only when something listens to `scrolled`.
+
+### Don't
+
+- Don't make the document or another wrapper scroll; on iOS it cannot.
+- Don't nest a second vertical scroller inside `bf-content` for the page's main content.
+- Don't add bottom padding for the tab bar yourself; `--bf-tab-bar-inset` already covers it.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfContentScrollEvent` (`{ scrollTop: number }`), the payload of `scrolled` (was an
+inline object type of the same shape).
+
+JSDoc of `content.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs. No
+behaviour change.
+
+**Behaviour:** `--bf-header-height` is written in the render phase (`afterRenderEffect`), and the
+scroller registers in `BfPageContext` once after the first render (`afterNextRender`) instead of
+from an `effect`; it is still cleared on destroy. Internal timing only, no API change.
+
+`fullscreen` pads the top safe area only while the page's `BfPageContext.safeAreaTop()` is true;
+inside a page-sheet `bf-modal` (false) it adds no top padding (Migration 29).
+
+**Behaviour:** in the page a `bf-stack-outlet` shows, the scroller is the `main` landmark
+(`role="main"`, while `BfPageContext.mainLandmark()` is true). While it overflows and holds nothing
+focusable it is a tab stop (`tabindex="0"`, with an inset focus ring), so a keyboard can scroll it
+in Safari and WKWebView (which never focus a scroll container on their own; Chromium does); a
+control appearing inside takes it out of the Tab order again (re-checked per frame on resize and
+content changes, including `hidden` and `inert` toggles). Hidden, inert and unrendered controls do
+not count, and overflow means more than 2 px (the iOS body's 1 px rubber-band extra is not
+overflow). See Migration 36.
+
+### 0.2.0
+
+New `bf-content`: the page's single scroll container (host `block min-h-0 flex-1`, scroller
+`h-full overflow-y-auto overscroll-contain touch-pan-y pl-safe-left pr-safe-right` with
+`padding-bottom: var(--bf-tab-bar-inset, 0px)`, plus `pt-safe-top` when `fullscreen`, otherwise
+`padding-top` and `scroll-padding-top` of `var(--bf-header-height, 0px)`, a variable it writes on
+its scroller from `BfPageContext.headerHeight` while a `translucent` header is drawn over it). It applies
+`bfKeyboardAssist` to its scroller (`keyboardAssist`, default `true`), emits `scrolled`
+(`{ scrollTop }`) from a passive listener only while `scrollEvents` is true, offers
+`scrollToTop(behavior = 'smooth')`, `scrollToPoint(x, y, behavior)` and a `scrollElement` getter,
+and registers its scroller in the page's `BfPageContext`.
+
+Changed: the projected content now sits in a plain block body inside the scroller. In iOS mode
+(`BfPlatformService.mode()`) the body is `min-h-[calc(100%+1px)]`, so the scroller always overflows
+by 1 px and WebKit rubber-bands short pages too (it only bounces an overflowing scroller); in
+Material mode the scroller carries `bfOverscrollStretch`, the Android edge stretch the WebView does
+not draw. `bf-refresher` without a page context now tracks its nearest scrolling ancestor (past
+the body wrapper) instead of its parent element. The stretch stays off in iOS WebKit (Safari or a
+home-screen app, where Capacitor reports platform `web` and the mode is Material, detected from an
+`iPhone`/`iPad`/`iPod` user agent or `MacIntel` with more than one touch point), which rubber-bands
+natively, so the two never stack.
+
+Migration: the body's height is `auto`, so children that filled the scroller with `h-full` (a
+centred empty state) now collapse, and `min-h-full` or a `flex-1` inside a wrapper sized that way
+collapses too. Size such a child from its content or the viewport on your own wrapper
+(`min-h-[60dvh]`), not with `h-full`. The overscroll (the iOS bounce, the Android stretch and the
+refresher's iOS bounce mode) follows the engine (`BfPlatformService.mode()`), not
+`provideBfShell({ mode })`: Chrome never reports a negative `scrollTop`, so an Android app forced
+into the iOS look keeps the stretch and the material pull.
+
+Fixed: the scroller's bottom padding also adds `--bf-header-collapse`, the height a solid
+`bf-header` has collapsed by (`pb-[calc(var(--bf-tab-bar-inset,0px)+var(--bf-header-collapse,0px))]`,
+replacing `pb-(--bf-tab-bar-inset,0px)`), so the scroll range stays constant while the large title
+collapses. The keyboard assist's inline `padding-bottom` still overrides it while the keyboard is up.