@bitforgehq/ui 0.3.0

package/ai/components/tabs.md

@@ -0,0 +1,408 @@
+# bf-tabs
+
+Tabs page with one navigation stack per tab, wiring the tab bar to the router
+
+`BfTabsComponent` from `@bitforgehq/ui/mobile` · Navigation · since 0.2.0
+
+## Example
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfStackOutletComponent, BfTabsComponent } from '@bitforgehq/ui/mobile';
+import { Folder, Inbox, Sun, User } from 'lucide';
+import { InboxStateService } from '../../services/state/inbox.state.service';
+
+/**
+ * The tabbed app: one navigation stack per tab under `/tabs/<tab>`, and the floating tab bar with
+ * the Inbox unread badge.
+ */
+@Component({
+  selector: 'app-tabs',
+  host: { class: 'block h-full' },
+  imports: [
+    BfTabsComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="tabs">
+      <bf-stack-outlet />
+      <bf-tab-bar label="Main">
+        <bf-tab id="today" label="Today"><bf-icon [icon]="sun" /></bf-tab>
+        <bf-tab id="projects" label="Projects"><bf-icon [icon]="folder" /></bf-tab>
+        <bf-tab id="inbox" label="Inbox" [badge]="inboxBadge()"><bf-icon [icon]="inbox" /></bf-tab>
+        <bf-tab id="me" label="Me"><bf-icon [icon]="user" /></bf-tab>
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class TabsPage {
+  private readonly inboxState = inject(InboxStateService);
+
+  /** Unread messages on the Inbox tab; no badge at zero. */
+  protected readonly inboxBadge = computed(() => this.inboxState.unread() || null);
+  protected readonly sun = Sun;
+  protected readonly folder = Folder;
+  protected readonly inbox = Inbox;
+  protected readonly user = User;
+}
+```
+
+## Overview
+
+The tabs page of a mobile app: one navigation stack per tab. It wraps a `bf-stack-outlet`, which
+keeps a separate stack for every tab (keyed by the URL segment after `tabsPath`), and a
+`bf-tab-bar`, which it drives through `BF_TAB_BAR_CONTROLLER`: the bar shows the tab of the
+in-flight navigation's target, else of the current URL, and hides while the keyboard is open,
+without anything writing into it. Selecting another tab brings
+that tab back as it was left; re-selecting the active tab pops its stack to the root, or scrolls
+its content to the top when it is already there. The bar hides while the soft keyboard is open
+or about to open (a focused text control), and `--bf-tab-bar-inset` on the host tells
+`bf-content` how much to pad its bottom (the bar's measured height, a `ResizeObserver` on its
+`nav`, plus its bottom offset and 8 px; 64 px for the height until it is measured); the same value is mirrored on `<html>` as
+`--bf-tab-bar-inset-global` for overlays (the toast), which render outside the host. It is removed when the tabs are destroyed.
+It also provides `BF_TAB_LINKS`, so the projected bar is a `nav` of links to each tab's root URL
+(`aria-current` on the active one: `page` at the tab's root, `true` on a child page of it)
+instead of a `tablist`.
+
+The tabs page of a mobile app, with one navigation stack per tab. `bf-tabs` wraps a
+`bf-stack-outlet` and a `bf-tab-bar`: the outlet keeps a separate stack for every tab, keyed by the
+URL segment after the tabs route, so switching tabs parks the current tab's whole stack (depth,
+scroll and state kept) and brings the other one back exactly as it was left. The bar derives its
+selection from the router (through `BF_TAB_BAR_CONTROLLER`: the target of a navigation in flight,
+else the current tab route), the bar hides while the soft keyboard is open, and
+`--bf-tab-bar-inset` tells `bf-content` how far to pad its bottom.
+
+## When to use
+
+Use `bf-tabs` for the tab root of a Capacitor app: one navigation stack per tab behind a floating [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar). Use [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) instead for an app with one stack and no tabs, and a sidebar of links on desktop.
+
+## Basic usage
+
+The tabs page is a route with one child route per tab page; deeper pages of a tab are more child
+routes that start with the tab's segment. Every `bf-tab`'s `id` is that segment.
+
+```ts
+import { Component } from '@angular/core';
+import { type Routes } from '@angular/router';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfContentComponent,
+  BfHeaderComponent,
+  BfPageComponent,
+  BfStackOutletComponent,
+  BfTabsComponent,
+} from '@bitforgehq/ui/mobile';
+import { Folder, Sun, User } from 'lucide';
+
+/** A tab's root page (the three tabs share it here). */
+@Component({
+  selector: 'app-tab-root-page',
+  imports: [BfContentComponent, BfHeaderComponent, BfPageComponent],
+  template: `
+    <bf-page>
+      <bf-header title="Tab" />
+      <bf-content><p class="p-4">A tab's first page.</p></bf-content>
+    </bf-page>
+  `,
+})
+export class TabRootPage {}
+
+/**
+ * Tabs bound to the router.
+ *
+ * Each tab is a child route of `tabs` with a stack of its own; the tab bar inside `bf-tabs`
+ * becomes links to the tabs' roots.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-tabs-basic',
+  imports: [
+    BfIconComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfTabsComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="tabs">
+      <bf-stack-outlet />
+      <bf-tab-bar>
+        <bf-tab id="today" label="Today"><bf-icon [icon]="sun" /></bf-tab>
+        <bf-tab id="projects" label="Projects"><bf-icon [icon]="folder" /></bf-tab>
+        <bf-tab id="me" label="Me"><bf-icon [icon]="user" /></bf-tab>
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class TabsBasicExampleComponent {
+  protected readonly sun = Sun;
+  protected readonly folder = Folder;
+  protected readonly user = User;
+}
+
+/** The tabs route: one child path per tab, plus the pages pushed inside a tab. */
+export const routes: Routes = [
+  {
+    path: 'tabs',
+    component: TabsBasicExampleComponent,
+    children: [
+      { path: 'today', component: TabRootPage },
+      { path: 'today/task/:id', component: TabRootPage },
+      { path: 'projects', component: TabRootPage },
+      { path: 'me', component: TabRootPage },
+      { path: '', redirectTo: 'today', pathMatch: 'full' },
+    ],
+  },
+];
+```
+
+`tabsPath` is the route path of the tabs page (`'tabs'` above, or `'app/tabs'` for a nested one).
+Navigate inside a tab with `BfNavController.forward()` as anywhere else: `/tabs/today/task/4`
+pushes onto the Today stack. An empty `tabsPath` (`tabsPath=""`) mounts the tabs page at the root
+URL — the tab key is the first URL segment (`/today`, `/me`) with no `tabs` prefix; give the tabs
+route `path: ''` with the same shape of children.
+
+## Switching and re-selecting tabs
+
+Selecting another tab (a plain click on its link) navigates to where that tab was left (the URL
+of the top page of its stack, or `/tabs/<id>` the first time) and, once that navigation has succeeded, plays
+`BfHapticsService.selection()` when `hapticsOnTabChange` is on in `provideBfShell()` (a switch a
+guard refuses plays nothing). A tab switch has no transition and no swipe-back;
+`BfNavController.depth`, `canGoBack` and `back()` refer to the active tab's stack while the tabs
+page is shown, so the back button pops within the tab. A page pushed on an outer outlet above the
+tabs page (`/gallery`) parks the tabs page with every tab stack intact until it is popped. Selecting the tab that is already active pops its stack back to
+its existing root page (one history step back, so the root keeps its scroll and state) when it is
+deeper than one page, or scrolls its `bf-content` back to the top when it is already at the root.
+
+## Soft keyboard
+
+While `BfKeyboardService.visible()` or `BfKeyboardService.imminent()` is true the bar slides down
+out of view (the projected `bf-tab-bar` reads `hidden()` from `BF_TAB_BAR_CONTROLLER`): a 200 ms `translate`/`opacity`
+transition on iOS, instantly on Android (where the WebView resizes under the keyboard) and on the
+web. `imminent()` turns true on `focusin` of a text control, before any keyboard event: on Android
+the WebView shrinks before the plugin's will-show, and a bar hidden only then would first be lifted
+above the keyboard. It comes back when the keyboard hides or the control loses focus, and 2.5 s
+after the focus when no keyboard shows at all (a hardware keyboard, such as an iPad Magic Keyboard,
+fires no keyboard event).
+
+## Desktop
+
+`bf-tabs` is part of the Capacitor shell (`provideBfShell()`). On a desktop web app put the top-level destinations in a sidebar or a top `nav` of links with `routerLinkActive`, and a plain `router-outlet`. Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
+
+## Theming
+
+- `--bf-tab-bar-inset` on the `bf-tabs` host:
+  `calc(<height>px + 8px + max(var(--spacing-safe-bottom), 12px) + 8px)` (the bar's measured
+  height, its bottom offset of 8 px above the safe area with a 12 px floor, and 8 px of room above
+  the bar: 114 px on an iPhone with a home indicator at the default text size, 104 px with Android
+  gesture navigation, 92 px without an inset) while a bar is present and visible, `0px` while it is
+  hidden or absent. The height is measured with a `ResizeObserver` on the projected bar's `nav`, so
+  the inset follows a bar that grows with large text (a two-line label at Android font scale 2.0,
+  iOS Dynamic Type) or slims down at compact heights (phone landscape); until the first
+  measurement it is the bar's 64 px minimum. The observer is disconnected with the tabs. `bf-content`
+  pads its scroller's bottom by it; use it for anything else that must clear the bar.
+- `--bf-tab-bar-inset-global` on `<html>`: the same value, for overlays (the toast), which render in
+  the CDK overlay container outside `bf-tabs`; removed when the tabs are destroyed. Only overlays
+  read it — a page pushed outside `bf-tabs` keeps no bottom padding.
+- The bar itself keeps the `bf-tab-bar` tokens (`surface`, `shadow-floating`, `primary-soft`).
+- The host is `display: block; height: 100%` around a `relative flex h-full flex-col` column; give
+  the tabs page a height (it fills the outlet frame it is routed into).
+
+## Accessibility
+
+`bf-tabs` provides `BF_TAB_LINKS`, so its bar is a navigation landmark of links, not a `tablist`:
+the tabs switch routes, not in-page panels, which is what the
+[WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/) is for (the
+[tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) assumes tab panels in the same
+page). The bar is `nav` > a plain group > one `<a href>` per tab, pointing at the tab's root URL
+(`/tabs/<id>`, through the app's `LocationStrategy`, so the base href is included), with
+`aria-current` on the active tab: `page` while its root page is shown, `true` on a child page of it
+(the tab is then the current section, not the current page). Tab and Shift+Tab move between the
+tabs, Enter follows one, and the arrow keys do nothing; Ctrl/Cmd-click or a middle click opens the tab's root in a new
+browser tab. A plain click is not followed as a link: the bar turns it into a selection, so
+`bf-tabs` still brings the tab back where it was left, plays its haptic and pops to the root on
+reselect. A standalone `bf-tab-bar` outside `bf-tabs` keeps its `tablist` semantics. While the
+keyboard hides it, the bar's `nav` is `aria-hidden="true"` and `inert`, so it can be neither
+focused nor read. Each tab's
+stack follows `bf-stack-outlet`'s rules: parked stacks are `visibility: hidden`, `inert` and
+`aria-hidden`, and after a switch focus moves to the restored page's title (`data-bf-page-title`).
+
+**Safari and iOS WKWebView (the Capacitor iOS app) do not move Tab to links by default.** With a
+hardware keyboard (an iPad with a Magic Keyboard, a Mac), Tab skips the tab bar's links unless the
+user turns on "Press Tab to highlight each item" (Safari settings on macOS; on iPadOS the
+keyboard's Full Keyboard Access); Option+Tab reaches them otherwise. VoiceOver and Full Keyboard
+Access navigation are unaffected, and Chromium-based browsers and Android WebView tab to links as
+usual. The old `button role="tab"` bar was reachable with plain Tab in WebKit; the link bar trades
+that for real URLs, opening a tab in a new browser tab and `aria-current`.
+
+Only the `bf-tab-bar` placed directly inside `<bf-tabs>` in the same template becomes links. An
+in-page `bf-tab-bar` inside a tab's page (a routed page) keeps its `tablist`.
+
+### Keyboard
+
+In Safari and iOS WKWebView, Tab reaches the links only with "Press Tab to highlight each item" on (Option+Tab otherwise).
+
+| Key                                              | Action                                                    |
+| ------------------------------------------------ | --------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the tab links; a disabled tab is skipped    |
+| <kbd>Enter</kbd>                                 | Follows the focused tab's link; the arrow keys do nothing |
+
+## Inputs
+
+| Name       | Type     | Default  | Description                                                                           |
+| ---------- | -------- | -------- | ------------------------------------------------------------------------------------- |
+| `tabsPath` | `string` | required | Route path of the tabs page (e.g. `'tabs'`); the URL segment after it is the tab key. |
+
+## Slots
+
+- `default`: The tabs page body: a `bf-stack-outlet` and a `bf-tab-bar`.
+
+## Methods
+
+### `keyOf(url: string): string | null`
+
+The tab key of `url`: the primary segment after `tabsPath`. Query, fragment, matrix params and
+auxiliary routes (`(popup:…)`) are ignored.
+
+| Parameter | Type     | Description      |
+| --------- | -------- | ---------------- |
+| `url`     | `string` | The URL to read. |
+
+### `href(id: string): string`
+
+The URL of tab `id`'s root page (`/tabs/<id>`, with the app's base href), the `href` of its
+link in the bar: a new browser tab opens the tab's root. A plain click still restores the page
+the tab was left on.
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `id`      | `string` | The `id` of the tab. |
+
+### `isRoot(id: string): boolean`
+
+Whether the current URL is tab `id`'s root page (`…/<tabsPath>/<id>` with nothing after it,
+ignoring query, fragment and auxiliary routes); reactive through the router's signals.
+
+| Parameter | Type     | Description          |
+| --------- | -------- | -------------------- |
+| `id`      | `string` | The `id` of the tab. |
+
+### `select(id: string): void`
+
+Another tab, selected by the user in the bar: go back to where that tab was left (its stack's
+top page), or its root. The bar shows the target while the navigation is in flight and drops
+back by itself when a guard refuses it.
+
+| Parameter | Type     | Description                   |
+| --------- | -------- | ----------------------------- |
+| `id`      | `string` | The `id` of the selected tab. |
+
+### `reselect(id: string): void`
+
+The active tab again: pop its stack back to its existing root page (a history step), or
+replace the stack with the root when the history position is unknown; at the root, scroll its
+content to the top.
+
+| Parameter | Type     | Description                 |
+| --------- | -------- | --------------------------- |
+| `id`      | `string` | The `id` of the active tab. |
+
+## Notes
+
+### Do
+
+- Give every `bf-tab` the `id` of its route segment, and start every page of a tab with it.
+- Put `bf-content` in every tab page so it pads for the bar.
+
+### Don't
+
+- Don't bind `[(active)]` or `(changed)` on the bar inside `bf-tabs`; `bf-tabs` owns both.
+- Don't look for `role="tab"` inside `bf-tabs` in tests or scripts; query the tabs as links
+  (`getByRole('link', { name: 'Projects' })`) and the active one by `aria-current` (`page` at the
+  tab's root, `true` below it).
+- Don't nest a second `bf-tabs` inside a tab.
+
+## Migration notes
+
+### 0.3.0
+
+**Breaking:** (ARIA contract) `bf-tabs` provides `BF_TAB_LINKS`, so the `bf-tab-bar` projected
+directly into it is a `nav` of links with `aria-current` (`page` at the tab's root, `true` on a
+child page) instead of a `tablist` (the tabs switch routes, not in-page panels); an in-page bar on
+a tab's page keeps its `tablist`. New `href(id)`: the tab's root URL, `/<tabsPath>/<id>` through
+`LocationStrategy` (base href included), used as each tab's `href`, so Ctrl/Cmd-click opens a tab
+in a new browser tab; a plain click still restores the tab's last page. New `isRoot(id)`: whether
+the current URL is that root. Tab moves between tabs (in Safari and iOS WKWebView only with "Press
+Tab to highlight each item", else Option+Tab); the arrow keys no longer do (they stopped after one
+step before). See Migration 11.
+
+JSDoc of `tab-context.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `tabs.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs. No
+behaviour change.
+
+**Behaviour:** the bar is driven through `BF_TAB_BAR_CONTROLLER` instead of written into (F-021).
+`current()` (read-only) is the tab of the in-flight navigation's target after redirects once they
+are applied (`router.currentNavigation()`), else of
+the settled URL (`router.lastSuccessfulNavigation()`), keeping the last tab while neither is under
+`tabsPath`: a clicked tab shows at once and a navigation a guard refuses drops back by itself.
+`hidden()` is `keyboard.visible() || keyboard.imminent()`, `hideTransition()` is true on iOS, and
+`select(id)`/`reselect(id)` are the former `changed`/`reselected` handlers. `tabKey()` and
+`isRoot(id)` read the router's navigation signals; the `router.events` subscription and the three
+effects that wrote into the bar are gone. `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global` on
+`<html>`) is written in the render phase (`afterRenderEffect`). See Migration 24.
+
+**Behaviour:** `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global`) use the bar's measured height
+instead of the fixed 4 rem (F-051, F-054): an `afterRenderEffect` observes the projected bar's
+`nav` with a `ResizeObserver` and writes
+`calc(<height>px + 8px + max(var(--spacing-safe-bottom), 12px) + 8px)`, or `0px` while the bar is
+hidden; until the first measurement it uses the bar's 64 px minimum. The observer is disconnected on
+destroy. So the page's bottom padding follows a bar grown by large text or slimmed at compact
+heights.
+
+### 0.2.0
+
+New `bf-tabs` (`tabsPath` required input): the tabs page with one navigation stack per tab. It
+provides `BF_TAB_CONTEXT` (`tabKey` signal from `NavigationEnd.urlAfterRedirects`, `keyOf(url)` =
+the primary segment after `tabsPath`, parsed with `Router.parseUrl`, so query, fragment, matrix
+params and auxiliary routes are ignored) to the projected `bf-stack-outlet`, sets the
+projected `bf-tab-bar`'s `active` to the tab key, and handles its selections: another tab navigates
+with `nav.forward()` to where that tab was left (`outlet.lastUrlOf(key)`, else `/<tabsPath>/<key>`)
+and, once it has succeeded, `BfHapticsService.selection()` when `hapticsOnTabChange`, putting the
+bar back (without a haptic) if a guard refuses; the active tab again (`tabReselect`) at depth > 1 pops the stack to its existing root page
+(`outlet.popToRoot()`, one `Location.historyGo(-n)` step computed from the outlet's history
+positions, so the root keeps its DOM, scroll and state), falling back to
+`nav.root(['/', tabsPath, key])` when the position is unknown; at depth 1 it scrolls the active
+page's content to the top. It hides the bar while
+`BfKeyboardService.visible()` (`setHidden()`, animated on iOS only, instant on Android and the web) and writes
+`--bf-tab-bar-inset` on its host: `calc(64px + 24px + var(--spacing-safe-bottom))` while a bar is
+present and visible, `0px` otherwise. The same value is mirrored on `<html>` as
+`--bf-tab-bar-inset-global` for overlays, which render outside the host (the toast reads it), and
+removed on destroy; `bf-content` keeps reading `--bf-tab-bar-inset`, so a page outside `bf-tabs`
+gets no bottom padding.
+
+Fixed: on Android the bar flashed above the keyboard, because the WebView shrinks (lifting the fixed
+bar) before `keyboardWillShow`. The bar now hides on `BfKeyboardService.visible() ||
+BfKeyboardService.imminent()`, i.e. already on `focusin` of a text control.
+
+Fixed: an empty `tabsPath` (the tabs mounted at the root URL) built `['/', '', key]`, a doubled
+slash the router turned into a broken navigation. `onTabChange` and `onTabReselect` now build the
+command array from the non-empty segments of `tabsPath`, so `['/', key]` results when it is empty.
+
+Changed: `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global`) follows the bar's new position:
+`calc(64px + 8px + max(var(--spacing-safe-bottom), 12px) + 8px)` (the bar's height, its offset of
+8 px above the safe area with a 12 px floor, and 8 px of room above the bar; 114 px on an iPhone
+with a home indicator, was 122 px), replacing `calc(64px + 24px + var(--spacing-safe-bottom))`.
+
+Fixed: the inset counts the bar's height in `rem` (`calc(4rem + 8px + max(var(--spacing-safe-bottom),
+12px) + 8px)`), like the bar's own `h-16`. With iOS Dynamic Type (`BfTextScaleService`) the bar
+grows with the root font size; a fixed 64 px left the end of every page under the bar at the
+accessibility sizes (at AX3 the bar is 150 px tall). Unchanged at the default text size.