@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/tab-panel.md

@@ -0,0 +1,163 @@
+# bf-tab-panel
+
+One tab of a tab group with its label, badge, icon and lazy content
+
+`BfTabPanelComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabGroupComponent, BfTabPanelComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Inbox, Star } from 'lucide';
+
+/**
+ * The bf-tab-panel overview.
+ *
+ * Live demo of `bf-tab-panel`: two panels in a `bf-tab-group`, each with an icon, one with a
+ * count badge and lazy content in an `ng-template`.
+ */
+@Component({
+  selector: 'app-example-tab-panel-overview',
+  imports: [BfTabGroupComponent, BfTabPanelComponent, BfIconComponent],
+  template: `
+    <bf-tab-group label="Mailbox">
+      <bf-tab-panel value="starred" label="Starred">
+        <bf-icon bfSlot="icon" [icon]="star" />
+        <p class="text-body">Two starred threads.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="inbox" label="Inbox" [badge]="4">
+        <bf-icon bfSlot="icon" [icon]="inbox" />
+        <ng-template><p class="text-body">Four unread messages.</p></ng-template>
+      </bf-tab-panel>
+    </bf-tab-group>
+  `,
+})
+export class TabPanelOverviewExampleComponent {
+  protected readonly star = Star;
+  protected readonly inbox = Inbox;
+}
+```
+
+## Overview
+
+One tab of a `bf-tab-group` and the content it shows: `label` is the tab's text, `value` the
+key the group's `selected` holds. Put the content in an `ng-template` inside the panel and it is
+created only while the panel is selected (`keepAlive` keeps it once visited); plain content
+renders at once and is only hidden. An icon in `bfSlot="icon"` shows in the tab before the label.
+
+One tab of a [`bf-tab-group`](https://bitforge-ui.web.app/components/tab-group) and the content it shows. `label` is the tab's text and `value` the key the group's `selected` holds; the group renders the tab, owns the selection and the keyboard, and shows one panel at a time.
+
+## When to use
+
+Use `bf-tab-panel` for each section of a [bf-tab-group](https://bitforge-ui.web.app/components/tab-group), and only there. Use [bf-tab](https://bitforge-ui.web.app/components/tab) instead for a destination of the phone's [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar), and an `a[bfNavItem]` in a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) for a tab that is its own route.
+
+## Content
+
+Content in an `ng-template` inside the panel is created only while the panel shows and destroyed when another one does; `keepAlive` keeps it, hidden, once it has been shown. Plain content renders at once and is hidden while another tab is selected. The [tab group page](https://bitforge-ui.web.app/components/tab-group) shows both.
+
+## Badge, icon and disabled
+
+`badge` adds a count pill after the tab's label (`null` shows none), announced through `provideBfLabels()`'s `tabBadge(n)` ("3 new"). An element with `bfSlot="icon"`, usually a `bf-icon`, shows in the tab before the label. `disabled` greys the tab out: it cannot be clicked and the arrow keys skip it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabGroupComponent, BfTabPanelComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Activity, FileText, LayoutDashboard, Lock } from 'lucide';
+
+/**
+ * Tabs with icons, a count badge and a disabled tab.
+ *
+ * Each panel's `bfSlot="icon"` shows in its tab before the label; `badge` adds an announced
+ * count, and `disabled` takes a tab out of the selection and the keyboard navigation.
+ */
+@Component({
+  selector: 'app-example-tab-group-badges-and-icons',
+  imports: [BfTabGroupComponent, BfTabPanelComponent, BfIconComponent],
+  template: `
+    <bf-tab-group label="Project with icons">
+      <bf-tab-panel value="overview" label="Overview">
+        <bf-icon bfSlot="icon" [icon]="dashboard" />
+        <p class="text-body">The project at a glance.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="activity" label="Activity" [badge]="12">
+        <bf-icon bfSlot="icon" [icon]="activity" />
+        <p class="text-body">12 updates since your last visit.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="files" label="Files">
+        <bf-icon bfSlot="icon" [icon]="files" />
+        <p class="text-body">The brief and two mock-ups.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="billing" label="Billing" [disabled]="true">
+        <bf-icon bfSlot="icon" [icon]="lock" />
+        <p class="text-body">Billing is managed by the workspace owner.</p>
+      </bf-tab-panel>
+    </bf-tab-group>
+  `,
+})
+export class TabGroupBadgesAndIconsExampleComponent {
+  protected readonly dashboard = LayoutDashboard;
+  protected readonly activity = Activity;
+  protected readonly files = FileText;
+  protected readonly lock = Lock;
+}
+```
+
+## Desktop
+
+The panel's tab takes the group's hover, pressed and focus styles; see the [tab group's Desktop section](https://bitforge-ui.web.app/components/tab-group#desktop). The panel itself is in the tab order and shows the focus ring on keyboard focus only.
+
+## Theming
+
+- The panel has no surface of its own; its focus ring is `ring` on `rounded-tile` corners.
+- The tab's tokens are on the [tab group](https://bitforge-ui.web.app/components/tab-group#theming) page.
+
+## Accessibility
+
+The host is `role="tabpanel"` with `aria-labelledby` naming its tab, `tabindex="0"` so the keyboard reaches content without a focusable element, and `hidden` while another tab is selected. Its tab is a `<button role="tab">` whose `aria-controls` names the panel; the visible `label` is the tab's name, followed by the badge's announcement when there is one.
+
+### Keyboard
+
+The group owns the tab stop and the arrow keys; its [keyboard table](https://bitforge-ui.web.app/components/tab-group#keyboard) has them all.
+
+| Key                                              | Action                                     |
+| ------------------------------------------------ | ------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves from the selected tab into the panel |
+
+## Inputs
+
+| Name        | Type             | Default  | Description                                                                                                                                         |
+| ----------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`     | `string`         | required | The key of this panel; the group's `selected` holds it while the panel is shown.                                                                    |
+| `label`     | `string`         | required | The tab's visible text, also its accessible name.                                                                                                   |
+| `disabled`  | `boolean`        | `false`  | Disables the tab: it cannot be clicked and the arrow keys skip it.                                                                                  |
+| `badge`     | `number \| null` | `null`   | A count shown as a pill after the tab's label, announced with `provideBfLabels()`'s `tabBadge(count)` ("3 new"); `null` shows none.                 |
+| `keepAlive` | `boolean`        | `false`  | Keeps the content of an `ng-template` in the DOM, hidden, once the panel has been shown, so its state (scroll, form input) survives switching tabs. |
+
+## Slots
+
+- `icon`: An icon in the tab before the label, a `bf-icon`.
+- `default`: Content rendered at once and hidden while another tab is selected; put it in an `ng-template` instead to create it only when the panel is shown.
+
+## Notes
+
+### Do
+
+- Give every panel a stable, meaningful `value` (`overview`, `activity`): it is what `selected` stores.
+- Wrap content that fetches or draws a lot in an `ng-template`.
+
+### Don't
+
+- Don't use a `bf-tab-panel` outside a `bf-tab-group`; it needs one.
+- Don't rely on the badge alone for important information; it is a count, not a message.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-tab-panel`: one tab of a `bf-tab-group` and its content (`role="tabpanel"`,
+`aria-labelledby` its tab, `tabindex="0"`): `value`, `label`, `disabled`, a `badge` count
+announced with `tabBadge(count)` and an `icon` slot shown in the tab. Content in an `ng-template`
+is created only while the panel shows; `keepAlive` keeps it, hidden, once visited.