@bitforgehq/ui 0.3.0

package/ai/components/tab.md

@@ -0,0 +1,295 @@
+# bf-tab
+
+One tab bar destination with an icon, a label and an optional count badge
+
+`BfTabComponent` from `@bitforgehq/ui` · Navigation · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Inbox, Sun } from 'lucide';
+
+/**
+ * The bf-tab overview.
+ *
+ * Live demo of `bf-tab`: two tabs inside a `bf-tab-bar`, one with a badge; click to switch.
+ */
+@Component({
+  selector: 'app-example-tab-overview',
+  imports: [BfTabBarComponent, BfTabComponent, BfIconComponent],
+  template: `
+    <bf-tab-bar [(active)]="active" [floating]="false" label="Sections">
+      <bf-tab id="today" label="Today"><bf-icon [icon]="sun" /></bf-tab>
+      <bf-tab id="inbox" label="Inbox" [badge]="2"><bf-icon [icon]="inbox" /></bf-tab>
+    </bf-tab-bar>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">
+      Active tab: {{ active() }}
+    </p>
+  `,
+})
+export class TabOverviewExampleComponent {
+  readonly active = signal('today');
+  readonly sun = Sun;
+  readonly inbox = Inbox;
+}
+```
+
+## Overview
+
+One destination inside `bf-tab-bar`: icon in the default slot, `label` under it, optional count
+`badge`. A `button role="tab"` in a standalone bar; inside `bf-tabs`, a link to the tab's URL
+with `aria-current` while active: `page` on the tab's root page, `true` on a child page of it
+(the current section, not the current page).
+
+One destination of a [`bf-tab-bar`](https://bitforge-ui.web.app/components/tab-bar): an icon in the default slot with a `label` underneath. A `bf-tab` lives only inside a bar, which owns the selection (`active`), the keyboard navigation and the floating layout; this page covers what a single tab adds: its id, its badge and its disabled state.
+
+## When to use
+
+Use `bf-tab` for each destination of a [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar), and only there. Use [bf-segmented](https://bitforge-ui.web.app/components/segmented) instead for options that switch a view inside a page, and [bf-button](https://bitforge-ui.web.app/components/button) for an action.
+
+## Basic usage
+
+Give every tab an `id` (the selection key the bar's `active` holds and `changed` emits) and a short `label`, and put a `bf-icon` in its default slot. The `id` is not a host DOM id: the host drops its own `id` attribute, and the id lands once, on the tab's inner `<button>` (or `<a>` inside `bf-tabs`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileText, FolderOpen, Users } from 'lucide';
+
+/**
+ * Tabs with an icon and a label.
+ *
+ * Each `bf-tab` is one destination: its `id` is the selection key the bar's `active` holds.
+ */
+@Component({
+  selector: 'app-example-tab-basic',
+  imports: [BfTabBarComponent, BfTabComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col items-center gap-3">
+      <bf-tab-bar [(active)]="active" [floating]="false" label="Workspace">
+        <bf-tab id="notes" label="Notes"><bf-icon [icon]="fileText" /></bf-tab>
+        <bf-tab id="files" label="Files"><bf-icon [icon]="folderOpen" /></bf-tab>
+        <bf-tab id="people" label="People"><bf-icon [icon]="users" /></bf-tab>
+      </bf-tab-bar>
+      <p class="text-caption text-text-muted">active: {{ active() }}</p>
+    </div>
+  `,
+})
+export class TabBasicExampleComponent {
+  protected readonly fileText = FileText;
+  protected readonly folderOpen = FolderOpen;
+  protected readonly users = Users;
+  protected readonly active = signal('notes');
+}
+```
+
+## Badges
+
+Give a tab a `badge` for an unread or pending count, or a short text. The badge sits at the inline end of the icon (its left under `dir="rtl"`). A number is announced through `provideBfLabels()`'s `tabBadge(n)` ("3 new"); a string is announced as written.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Bell, MessageCircle } from 'lucide';
+
+/**
+ * Tabs with badges.
+ *
+ * A number badge is announced as "Messages, 3 new"; a text badge is announced as written.
+ */
+@Component({
+  selector: 'app-example-tab-badges',
+  imports: [BfTabBarComponent, BfTabComponent, BfIconComponent],
+  template: `
+    <bf-tab-bar [(active)]="active" [floating]="false" label="Updates">
+      <bf-tab id="messages" label="Messages" [badge]="3"><bf-icon [icon]="messageCircle" /></bf-tab>
+      <bf-tab id="alerts" label="Alerts" badge="!"><bf-icon [icon]="bell" /></bf-tab>
+    </bf-tab-bar>
+  `,
+})
+export class TabBadgesExampleComponent {
+  protected readonly messageCircle = MessageCircle;
+  protected readonly bell = Bell;
+  protected readonly active = signal('messages');
+}
+```
+
+## Disabled
+
+`disabled` greys the tab out and takes it out of the keyboard navigation; it cannot be clicked. Inside `bf-tabs` a disabled tab is a link without an `href`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Archive, PenLine } from 'lucide';
+
+/** A disabled tab: skipped by the arrow keys and not clickable. */
+@Component({
+  selector: 'app-example-tab-disabled',
+  imports: [BfTabBarComponent, BfTabComponent, BfIconComponent],
+  template: `
+    <bf-tab-bar [(active)]="active" [floating]="false" label="Mail">
+      <bf-tab id="drafts" label="Drafts"><bf-icon [icon]="penLine" /></bf-tab>
+      <bf-tab id="archive" label="Archive" [disabled]="true"><bf-icon [icon]="archive" /></bf-tab>
+    </bf-tab-bar>
+  `,
+})
+export class TabDisabledExampleComponent {
+  protected readonly penLine = PenLine;
+  protected readonly archive = Archive;
+  protected readonly active = signal('drafts');
+}
+```
+
+## Desktop
+
+A tab lives in a phone tab bar; see the [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) page for what to use on desktop. Under a mouse an inactive tab takes a `surface-muted` fill and a `text` icon on hover, the active capsule `primary-soft-hover`, with the pointer cursor; a disabled tab shows `not-allowed`. The focus ring shows on keyboard focus only.
+
+## Theming
+
+- Active tab capsule: `primary-soft` background, `primary-strong` icon/label and a 1.5 px inset
+  `primary-strong` outline, so the active tab does not rest on the fill alone. Inactive: `text-muted`.
+- Hover (pointer cursor): the active capsule goes to `primary-soft-hover`, an inactive one takes a
+  `surface-muted` fill and `text` icon.
+- Pressed: the capsule takes `primary-soft-pressed` (an inactive one with a `text` icon); none
+  while disabled.
+- Disabled tab (`disabled` button, or `aria-disabled` link inside `bf-tabs`): `surface-sunken`
+  capsule, `text-disabled` icon and label (never opacity).
+- A label longer than the tab's width wraps to at most two lines; a long word is hyphenated where the page's `lang` allows it (`hyphens-auto`), else broken where it must be.
+- Label: `text-nano` (11/14 px), capped at 200 % (22/28 px, `min(var(--text-nano), 22px)`, in px
+  because iOS Dynamic Type scales the root); the capsule (30 × 52 px), its icon, the badge
+  (18 px, its count capped at 13 px), the padding and the gaps are px, so they keep their size at
+  every text size. The label
+  never clips vertically: the bar grows with a two-line label. At compact heights
+  (`(max-height: 500px)`, phone landscape) the icon and the label sit side by side
+  (`flex-row gap-1.5`).
+- Badge: `primary` background, `on-primary` text; always a circle (`rounded-full`).
+- Shape (tab and capsule): `rounded-control` (`--radius-control`, `9999px` by default).
+- Focus ring: `ring`.
+
+## Accessibility
+
+In a standalone bar a tab is a native `<button role="tab">` with `aria-selected`, one of a
+roving-`tabindex` tablist; inside `bf-tabs` it is an `<a href>` link to the tab's root URL, with
+`aria-current` while active. The bar decides which form it takes; the
+[`bf-tab-bar` page](https://bitforge-ui.web.app/components/tab-bar#accessibility) describes both,
+with their keyboard behaviour.
+
+The visible `label` is the tab's name. With a `badge`, the badge text is `aria-hidden` and the
+name becomes the label, a comma and the announcement ("Inbox, 3 new", one string with no pause
+before the comma), so it still starts with the visible label. A `disabled` tab is native-disabled
+(a button) or `aria-disabled="true"` without an `href` (a link), so it is skipped by Tab and inert.
+The active capsule stays visible under `forced-colors` (`Highlight`/`HighlightText`).
+
+### Keyboard
+
+The bar owns the tab stop and the arrow keys; its [Accessibility section](https://bitforge-ui.web.app/components/tab-bar#keyboard) has the full table.
+
+| Key                                 | Action                                                                                 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> | Standalone bar: selects the focused tab; on the active tab, the bar emits `reselected` |
+| <kbd>Enter</kbd>                    | Inside `bf-tabs`: follows the tab's link                                               |
+
+## Inputs
+
+| Name       | Type                       | Default  | Description                                                                                                                                                                                                                                                                                              |
+| ---------- | -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`       | `string`                   | required | Stable identifier; matches `bf-tab-bar`'s `active` when this tab is selected. It is a selection key only, never reflected as the DOM `id` of more than the inner `<button>` (or `<a>` inside `bf-tabs`).                                                                                                 |
+| `label`    | `string`                   | required | Visible label under the icon.                                                                                                                                                                                                                                                                            |
+| `badge`    | `string \| number \| null` | `null`   | Optional count shown as a badge on the icon capsule; announced to screen readers as part of the tab's accessible name (`aria-label` "{label}, {announcement}", with `provideBfLabels()`'s `tabBadge(n)`, `"{n} new"`, for a number, the string as-is otherwise) since the badge itself is `aria-hidden`. |
+| `disabled` | `boolean`                  | `false`  | Disables the tab: skipped by keyboard navigation, cannot be clicked.                                                                                                                                                                                                                                     |
+
+## Slots
+
+- `default`: The tab icon, a `bf-icon` above the label.
+
+## Methods
+
+### `focus(): void`
+
+Moves keyboard focus to this tab's button (or link); called by `bf-tab-bar` after arrow-key
+selection.
+
+## Notes
+
+### Do
+
+- Give each tab a short, one-word label ("Benachrichtigungen" wraps in a quarter-width tab).
+- Keep ids stable and meaningful (`today`, `inbox`): they are what `active` stores and routes map to.
+
+### Don't
+
+- Don't use a `bf-tab` outside a `bf-tab-bar`.
+- Don't rely on the badge alone for important information; it is a count, not a message.
+
+## Migration notes
+
+### 0.3.0
+
+**Breaking:** (ARIA contract) inside `bf-tabs` a tab is `<a href>` with `aria-current` while
+active: `page` on the tab's root page, `true` on a child page of it (no `role="tab"` or
+`aria-selected`); a disabled one is `<a role="link" aria-disabled="true">` without `href`. A plain
+primary click selects the tab through the bar (default prevented); Ctrl/Cmd, Shift, Alt and middle
+clicks open the link in a new tab or window. The link's underline is removed with an important
+utility (`no-underline!`), so an unlayered global link rule cannot underline it. See Migration 11.
+
+**Behaviour:** a badged tab is named by `aria-label` = label, comma, announcement ("Projects, 3
+new"; was "Projects , 3 new", with a pause, from a visually hidden span that browsers joined with a
+space), in both forms; the `sr-only` announcement span is gone. Without a badge the visible label
+is the name, as before.
+
+**Behaviour:** the badge is placed with a logical inset (`-end-2`), so it sits at the icon's
+inline end under `dir="rtl"`.
+
+**Behaviour:** a numeric `badge` is announced through `provideBfLabels()`'s `tabBadge(count)`
+(`"{n} new"` by default, now translatable); a string badge is announced as given.
+
+**Behaviour:** the active capsule carries a 1.5 px inset `primary-strong` outline (≥ 3:1 on its
+`primary-soft` fill and the bar), so the active tab no longer rests on a fill 1.23:1 from the bar;
+a disabled active capsule is outlined in `text-disabled`. The tab and its capsule use
+`rounded-control` (`--radius-control`); the count badge stays a circle.
+
+**Docs:** `bf-tab` has a page of its own (`tab-bar/tab.docs.md`): its id, its badges (moved from
+the `bf-tab-bar` page) and a disabled tab, with the tab's own theming and accessibility; the
+`bf-tab-bar` page links to it.
+
+JSDoc of `tab.component.ts` for the API reference: `@slot` docs for `default`; template handlers and
+framework hooks marked `@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): the capsule of an enabled tab takes `primary-soft-pressed` (an inactive one with the `text` icon) while the tab is held down. None while disabled; under forced colours the system colours win.
+
+**Behaviour:** large text (F-051): the label's size and line height are capped at 200 %
+(`min(var(--text-nano), 22px)`, `min(var(--text-nano--line-height), 28px)`, in px because iOS
+Dynamic Type scales the root); it still wraps to at most two lines and never clips vertically. The
+tab has 4 px of vertical padding, so a grown tab keeps off the bar's edge. The capsule (30 × 52
+px), the badge (18 px, its count capped at 13 px), the padding and the gaps are px, so they keep
+their size at every text size. The label hyphenates a long word where the engine has
+hyphenation for the page's `lang` (`hyphens-auto wrap-break-word`, was `wrap-anywhere`), and
+otherwise still breaks it rather than overflowing (WKWebView on the iOS 18 simulator does not
+hyphenate "Projects", so it still reads "Projec/ts" at AX5). At
+compact heights (`(max-height: 500px)`, F-054) the icon and the label sit side by side
+(`flex-row gap-[6px]`).
+
+### 0.2.0
+
+The label is `text-nano` (11/14; the line was 16.5 px). Dropped the `[&>svg]:h-5 [&>svg]:w-5`
+selector, which never matched (icons render inside the `bf-icon` host). A disabled tab uses tokens
+instead of `opacity-40`: `surface-sunken` capsule, `text-disabled` icon and label. The tab can
+shrink (`min-w-0`) and its label is capped at `max-w-full px-1` (it wraps, see "Changed" below), so
+a long label no longer overflows its quarter of the bar.
+
+Fixed: the tab shows a pointer cursor and its capsule a hover (`primary-soft-hover` when active,
+`surface-muted` fill and `text` icon when inactive); a disabled tab keeps its sunken capsule.
+
+Changed: a long label wraps to at most two lines (`line-clamp-2 wrap-anywhere text-center`) instead
+of truncating to one, so "Benachrichtigungen" stays readable in a quarter-width tab.
+
+### 0.1.0
+
+New `bf-tab`: one destination inside `bf-tab-bar` — an icon in the default slot, `label` under it, and an optional `badge` count. `id` and `label` are required; `disabled` removes it from keyboard navigation and blocks clicks. Renders a native `<button role="tab">` with `aria-selected` and a roving `tabindex` driven by the bar's `tabStop`; the active tab's icon sits on a `primary-soft` capsule (`forced-colors:bg-[Highlight]`) with a `primary-strong` label, inactive tabs are `text-muted`. The host no longer reflects `id` as a DOM attribute (`bf-tab id="today"` previously duplicated `id="today"` onto both the host and the inner `<button>`); the id now lands once, on the button. The badge is `aria-hidden`; a visually hidden `sr-only` span after the label announces it instead (`"{n} new"` for a numeric badge, the string as-is otherwise), so the tab's accessible name carries meaning instead of a bare number.