@bitforgehq/ui 0.3.0

package/ai/components/list-item.md

@@ -0,0 +1,326 @@
+# bf-list-item
+
+List row with leading slot, title, subtitle, trailing slot and an optional chevron
+
+`BfListItemComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfActionDirective,
+  BfAvatarComponent,
+  BfButtonComponent,
+  BfListComponent,
+  BfListItemComponent,
+  BfToggleComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * The bf-list-item overview.
+ *
+ * Live demo of `bf-list-item`: the same three rows as the list demo, without the inset container,
+ * a navigation row whose title is a stretched `bfAction` link (to this page's "Navigation rows"
+ * section) with a raised trailing button, plus a standalone row outside any list.
+ */
+@Component({
+  selector: 'app-example-list-item-overview',
+  imports: [
+    RouterLink,
+    BfActionDirective,
+    BfListComponent,
+    BfListItemComponent,
+    BfAvatarComponent,
+    BfButtonComponent,
+    BfToggleComponent,
+  ],
+  template: `
+    <bf-list [inset]="false">
+      <bf-list-item title="Jonas Keller" subtitle="Shared the Bloom moodboard">
+        <bf-avatar bfSlot="leading" initials="JK" />
+        <span bfSlot="trailing" class="text-caption text-text-muted">9:12</span>
+      </bf-list-item>
+      <bf-list-item title="Weekly summary" subtitle="Every Monday at 8:00">
+        <bf-toggle bfSlot="trailing" ariaLabel="Weekly summary" [(checked)]="weeklySummary" />
+      </bf-list-item>
+      <bf-list-item
+        title="Account"
+        subtitle="lena@studio.ch"
+        [interactive]="true"
+        [chevron]="true"
+        (clicked)="openAccount()"
+      />
+      <!-- A navigation row: the title is a link whose ::after covers the row. -->
+      <bf-list-item subtitle="Plan, invoices and payment" chevron>
+        <a bfSlot="title" bfAction routerLink="/components/list-item" fragment="navigation-rows">
+          Billing
+        </a>
+        <bf-button bfSlot="trailing" variant="text" size="sm" (clicked)="downloadInvoice()">
+          Invoice
+        </bf-button>
+      </bf-list-item>
+    </bf-list>
+    <!-- A row on its own, outside bf-list: it claims no listitem role. -->
+    <bf-list-item class="mt-3" title="Storage" subtitle="2.1 GB of 5 GB used" />
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+  `,
+})
+export class ListItemOverviewExampleComponent {
+  readonly weeklySummary = signal(true);
+
+  readonly opened = signal(0);
+  readonly downloads = signal(0);
+  readonly status = computed(() => {
+    const parts = [`Weekly summary ${this.weeklySummary() ? 'on' : 'off'}`];
+    if (this.opened() > 0) {
+      parts.push(`Account opened ${this.opened()}×`);
+    }
+    if (this.downloads() > 0) {
+      parts.push(`Invoice downloaded ${this.downloads()}×`);
+    }
+    return `${parts.join(' · ')}.`;
+  });
+
+  /** Counts the opens; a real app would navigate to the account screen. */
+  openAccount(): void {
+    this.opened.update((count) => count + 1);
+  }
+
+  /** Counts the downloads of the trailing button, which sits above the row's stretched link. */
+  downloadInvoice(): void {
+    this.downloads.update((count) => count + 1);
+  }
+}
+```
+
+## Overview
+
+One row of a list: leading slot (avatar, icon tile), title and subtitle, trailing slot
+(time, toggle, badge) and an optional chevron for rows that navigate. A navigation row puts a
+`bfAction` link in the `title` slot, so the row stays a list item and the link covers it.
+
+A row of a list: a leading slot (an avatar, an icon), the title and subtitle, a trailing slot (a time, a toggle, a chip) and an optional chevron. Place rows in a [`bf-list`](https://bitforge-ui.web.app/components/list), which gives them the list semantics and the inset container; a row can also stand alone. A row is static text, a navigation link or an action button, never more than one of them.
+
+## When to use
+
+Use `bf-list-item` for one row of a list: static text, a navigation link (`bfAction` in the title) or an action (`interactive`). Use [bf-card](https://bitforge-ui.web.app/components/card) instead for a block with its own heading and several parts, and [bf-menu](https://bitforge-ui.web.app/components/menu) for a short list of actions that opens from a button.
+
+## Basic usage
+
+`title` and `subtitle` are inputs; `bfSlot="leading"` and `bfSlot="trailing"` project the content beside them.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+/** A row with a leading avatar, a title, a subtitle and a trailing time. */
+@Component({
+  selector: 'app-example-list-item-basic',
+  imports: [BfAvatarComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      <bf-list-item title="Jonas Keller" subtitle="Shared the Bloom moodboard">
+        <bf-avatar bfSlot="leading" initials="JK" />
+        <span bfSlot="trailing" class="text-caption text-text-muted">9:12</span>
+      </bf-list-item>
+    </bf-list>
+  `,
+})
+export class ListItemBasicExampleComponent {}
+```
+
+## Long text
+
+A long title, title-slot content or subtitle wraps onto more lines (a long word or URL breaks anywhere), so nothing is lost at large text sizes (iOS Dynamic Type, Android font scale 2.0). Add `truncate` for a row that must stay on one line per text, such as a mail list's sender and preview: each is then cut with an ellipsis.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+/** A long title wraps by default; truncate keeps a mail-style row on one line. */
+@Component({
+  selector: 'app-example-list-item-long-text',
+  imports: [BfAvatarComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      <bf-list-item
+        title="Prepare the quarterly review with the whole studio team"
+        subtitle="Atlas · due Friday"
+      />
+      <bf-list-item
+        title="Jonas Keller"
+        subtitle="I added the new moodboard and the notes from the call on Tuesday"
+        truncate
+      >
+        <bf-avatar bfSlot="leading" initials="JK" />
+      </bf-list-item>
+    </bf-list>
+  `,
+})
+export class ListItemLongTextExampleComponent {}
+```
+
+## Navigation rows
+
+A row that opens another page is a link. Put an `<a bfAction>` with `href` or `routerLink` in the `title` slot (`bfSlot="title"`, rendered in the title position and type); `bfAction` stretches the link's hit area over the whole row, and the row shows the `surface-muted` hover and the focus ring while the link has keyboard focus. The row itself stays a list item, the link's name is the title alone, and the subtitle, the leading slot and the trailing slot click through to it. Add `chevron` to mark the row as navigation. Import `BfActionDirective` from `@bitforgehq/ui`.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfActionDirective,
+  BfAvatarComponent,
+  BfListComponent,
+  BfListItemComponent,
+} from '@bitforgehq/ui';
+
+/** A navigation row: a stretched `<a bfAction>` in the title slot, marked with a chevron. */
+@Component({
+  selector: 'app-example-list-item-navigation',
+  imports: [RouterLink, BfActionDirective, BfAvatarComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      <bf-list-item subtitle="lena@studio.ch" chevron>
+        <bf-avatar bfSlot="leading" initials="LM" />
+        <a bfSlot="title" bfAction routerLink="/components/list-item">Account</a>
+      </bf-list-item>
+    </bf-list>
+  `,
+})
+export class ListItemNavigationExampleComponent {}
+```
+
+The trailing slot sits above the stretched link (`relative z-1`), so a toggle, chip or button there stays independently clickable. The subtitle and other text under the stretched link cannot be selected or copied; give text that must stay copyable `class="relative z-1"` (it then no longer clicks through). A row lights up only for its own action, and a card around the list is not lit by the rows.
+
+## Action and settings rows
+
+A row that performs an action on the page (opens a sheet, starts a sync) is a button: `[interactive]="true"` renders the whole row as a native `<button>` that emits `clicked`, and `disabled` disables it. A trailing `bf-toggle` makes a settings row. Text starts at the inline start and the chevron sits at, and points to, the inline end, so both mirror under `dir="rtl"`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent, BfToggleComponent } from '@bitforgehq/ui';
+
+/**
+ * An action row and a settings row.
+ *
+ * "Sync now" is an `interactive` row (a native button); "Weekly summary" holds a trailing toggle.
+ */
+@Component({
+  selector: 'app-example-list-item-actions',
+  imports: [BfListComponent, BfListItemComponent, BfToggleComponent],
+  template: `
+    <bf-list>
+      <bf-list-item
+        title="Sync now"
+        [subtitle]="synced() ? 'Synced just now' : 'Last synced 5 min ago'"
+        [interactive]="true"
+        (clicked)="synced.set(true)"
+      />
+      <bf-list-item title="Weekly summary" subtitle="Every Monday at 8:00">
+        <bf-toggle bfSlot="trailing" ariaLabel="Weekly summary" [(checked)]="weekly" />
+      </bf-list-item>
+    </bf-list>
+  `,
+})
+export class ListItemActionsExampleComponent {
+  protected readonly synced = signal(false);
+  protected readonly weekly = signal(true);
+}
+```
+
+## Desktop
+
+An `interactive` row and a row holding a `bfAction` link take a `surface-muted` fill and the pointer cursor while hovered; a static row has none. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring is drawn around the row on keyboard focus only. A navigation row keeps the browser's link behaviour: Ctrl/Cmd-click and a middle click open it in a new tab. The trailing slot sits above the stretched link, so a toggle or button there takes its own click. Rows have one height; they do not follow `provideBfDefaults()`.
+
+## Theming
+
+- Row: `surface` / `text`; the subtitle `text-muted`.
+- Text: the title, the title slot and the subtitle wrap (`wrap-anywhere`); with `truncate` each keeps one line (`truncate`).
+- `interactive` rows and rows holding a `bfAction` link add a pointer, a `surface-muted` hover, a `surface-pressed` fill while pressed (the row's action, for a `bfAction` row) and a `ring` focus ring; `interactive` rows dim to `text-disabled` when `disabled` and have no pressed state then.
+- The `chevron` mark uses `text-subtle`.
+
+## Accessibility
+
+`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree.
+
+### Keyboard
+
+| Key              | Action                                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd>   | Moves to an `interactive` row, or to a navigation row's `bfAction` link, then to its trailing controls |
+| <kbd>Enter</kbd> | Follows a navigation row's link, or activates an `interactive` row (emits `clicked`)                   |
+| <kbd>Space</kbd> | Activates an `interactive` row; a link ignores it                                                      |
+
+## Inputs
+
+| Name          | Type      | Default | Description                                                                                                                                           |
+| ------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`  | `''`    | Primary text. For a navigation row, project an `<a bfSlot="title" bfAction>` instead.                                                                 |
+| `subtitle`    | `string`  | `''`    | Secondary text under the title.                                                                                                                       |
+| `interactive` | `boolean` | `false` | Render the row as a button that emits `clicked` (an action row; a row that navigates puts a `bfAction` link in the `title` slot instead).             |
+| `chevron`     | `boolean` | `false` | Show a trailing chevron (navigation rows).                                                                                                            |
+| `disabled`    | `boolean` | `false` | Disable an interactive row.                                                                                                                           |
+| `truncate`    | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes. |
+
+## Outputs
+
+| Name      | Payload | Description                                   |
+| --------- | ------- | --------------------------------------------- |
+| `clicked` | `Event` | Emitted when an interactive row is activated. |
+
+## Slots
+
+- `leading`: Content before the text, such as an avatar or an icon.
+- `title`: Rich title content, instead of or next to the `title` text.
+- `default`: More content under the title and subtitle.
+- `trailing`: Content at the end, such as a toggle, a badge or a button.
+
+## Notes
+
+### Do
+
+- Keep titles short; a long one wraps. Add `truncate` only where one line per row is the pattern (a mail list).
+- Make a row that navigates a `bfAction` link in the `title` slot, and a row that acts on the page `interactive`; put secondary actions in the trailing slot.
+
+### Don't
+
+- Don't nest interactive controls inside an `interactive` row (it is one button); use a navigation row with a trailing control instead.
+- Don't wrap a `bf-list-item` in an `<a>`, and don't navigate from an `interactive` row's `(clicked)`.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** logical properties: text aligns to the inline start and the chevron sits at the
+inline end, pointing there (mirrored under `dir="rtl"`).
+
+New navigation rows: a `title` content slot (`bfSlot="title"`), rendered in the title position
+and type, takes an `<a bfAction routerLink="…">` (the new `BfActionDirective`), whose `::after`
+stretches over the row. The row stays a `listitem`, the link's name is the title, and the row
+shows the pointer, the `surface-muted` hover and the focus ring (on keyboard focus) while it holds
+its own `bfAction`; the row box is `relative`. Text under the stretched link is not selectable.
+
+**Behaviour:** the trailing slot is wrapped in a `relative z-1` flex box (`gap-3`, as between the
+row's items, hidden when empty), so a toggle or button there stays clickable above a stretched
+link. `interactive` stays for rows that act on the page.
+
+**Docs:** `bf-list-item` has a page of its own (`list/list-item.docs.md`): the row's slots, the
+navigation rows and the action and settings rows (moved from the `bf-list` page), with the row's own
+theming and accessibility. The `bf-list` page keeps the container: a list of rows and the plain
+list, and links to the row page.
+
+JSDoc of `list-item.component.ts` for the API reference: `@slot` docs for `leading`, `title`,
+`default`, `trailing`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): an `interactive` row takes `surface-pressed` while held down, and a row holding a `bfAction` while its action is (`has-[[data-bf-action]:active]`). None while disabled; under forced colours the system colours win.
+
+While a row is pressed its chevron turns `text-muted` (`text-subtle` misses 3:1 on
+`surface-pressed`).
+
+**Behaviour:** the title, the title slot and the subtitle wrap by default (`wrap-anywhere`, no
+clamp) instead of truncating, so no text is lost at large text sizes (F-051). New
+`truncate = input(false, { transform: booleanAttribute })` restores one line with an ellipsis for
+each. See Migration 32. The mobile demo's Inbox rows use `truncate` (a mail list); its Today,
+project and Me rows wrap.

package/ai/components/list.md

@@ -0,0 +1,178 @@
+# bf-list
+
+Container for list rows, inset by default with rounded corners on a warm background
+
+`BfListComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfAvatarComponent,
+  BfListComponent,
+  BfListItemComponent,
+  BfToggleComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * The bf-list overview.
+ *
+ * Live demo of `bf-list`: an inset list with an avatar row, a toggle row and an interactive row.
+ */
+@Component({
+  selector: 'app-example-list-overview',
+  imports: [BfListComponent, BfListItemComponent, BfAvatarComponent, BfToggleComponent],
+  template: `
+    <bf-list>
+      <bf-list-item title="Jonas Keller" subtitle="Shared the Bloom moodboard">
+        <bf-avatar bfSlot="leading" initials="JK" />
+        <span bfSlot="trailing" class="text-caption text-text-muted">9:12</span>
+      </bf-list-item>
+      <bf-list-item title="Weekly summary" subtitle="Every Monday at 8:00">
+        <bf-toggle bfSlot="trailing" ariaLabel="Weekly summary" [(checked)]="weeklySummary" />
+      </bf-list-item>
+      <bf-list-item
+        title="Account"
+        subtitle="lena@studio.ch"
+        [interactive]="true"
+        [chevron]="true"
+        (clicked)="openAccount()"
+      />
+    </bf-list>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+  `,
+})
+export class ListOverviewExampleComponent {
+  readonly weeklySummary = signal(true);
+
+  readonly opened = signal(0);
+  readonly status = computed(() => {
+    const summary = `Weekly summary ${this.weeklySummary() ? 'on' : 'off'}`;
+    const opened = this.opened();
+    return opened === 0 ? `${summary}.` : `${summary} · Account opened ${opened}×.`;
+  });
+
+  /** Counts the opens; a real app would navigate to the account screen. */
+  openAccount(): void {
+    this.opened.update((count) => count + 1);
+  }
+}
+```
+
+## Overview
+
+Container for `bf-list-item` rows. The inset style (default) wraps the rows in the warm
+background with rounded corners, as in the design's grouped lists.
+
+Lists show rows of related items: settings, conversations, people. `bf-list` is the container; its rows are [`bf-list-item`](https://bitforge-ui.web.app/components/list-item)s, each with a leading slot, title and subtitle, a trailing slot and an optional chevron. Navigation, action and settings rows are on the `bf-list-item` page.
+
+## When to use
+
+Use `bf-list` for a group of rows of the same kind: settings, conversations, people. Use [bf-card](https://bitforge-ui.web.app/components/card) instead for one piece of content with its own layout, and a native `table` for data the user compares across columns.
+
+## Basic usage
+
+Put the rows in the default slot. Inside a `bf-list` every row is a list item, on the inset container.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+/** A list of recent activity, one row per person. */
+@Component({
+  selector: 'app-example-list-basic',
+  imports: [BfAvatarComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      @for (row of rows; track row.name) {
+        <bf-list-item [title]="row.name" [subtitle]="row.action">
+          <bf-avatar bfSlot="leading" [initials]="row.initials" />
+          <span bfSlot="trailing" class="text-caption text-text-muted">{{ row.time }}</span>
+        </bf-list-item>
+      }
+    </bf-list>
+  `,
+})
+export class ListBasicExampleComponent {
+  protected readonly rows = [
+    { name: 'Jonas Keller', initials: 'JK', action: 'Shared the Bloom moodboard', time: '9:12' },
+    { name: 'Lena Moser', initials: 'LM', action: 'Commented on the Atlas deck', time: '8:47' },
+    { name: 'Ana Ruiz', initials: 'AR', action: 'Closed three tasks', time: 'Yesterday' },
+  ];
+}
+```
+
+## Plain list
+
+`inset` false drops the warm container for rows placed directly on a card.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+/** A plain list placed directly on a card, without the inset container. */
+@Component({
+  selector: 'app-example-list-plain',
+  imports: [BfCardComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-card>
+      <h3 class="text-heading">Today</h3>
+      <bf-list [inset]="false">
+        <bf-list-item title="Review the Atlas deck" subtitle="10:00" />
+        <bf-list-item title="Call Bloom" subtitle="14:30" />
+      </bf-list>
+    </bf-card>
+  `,
+})
+export class ListPlainExampleComponent {}
+```
+
+## Theming
+
+`inset` (default) uses the `bg` background on a `card` radius; `[inset]="false"` is transparent with no radius. The rows' own tokens are on the [`bf-list-item` page](https://bitforge-ui.web.app/components/list-item#theming).
+
+## Accessibility
+
+`bf-list` renders `role="list"` on its container, and every `bf-list-item` inside it takes `role="listitem"`, so a screen reader announces the list and its row count. The rows' roles, links and buttons are described on the [`bf-list-item` page](https://bitforge-ui.web.app/components/list-item#accessibility).
+
+## Inputs
+
+| Name    | Type      | Default | Description                                                                      |
+| ------- | --------- | ------- | -------------------------------------------------------------------------------- |
+| `inset` | `boolean` | `true`  | Grouped look with the warm container; false renders rows on the page background. |
+
+## Slots
+
+- `default`: The rows, each a `bf-list-item`.
+
+## Notes
+
+### Do
+
+- Group rows that belong together in one `bf-list`; start a new list under a heading for a new group.
+- Use `[inset]="false"` on a card, so the card is the only container.
+
+### Don't
+
+- Don't put anything but `bf-list-item` rows in a `bf-list`; its `role="list"` expects list items.
+- Don't nest a `bf-list` inside a row.
+
+## Migration notes
+
+### 0.3.0
+
+JSDoc of `list.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+### 0.2.0
+
+`bf-list-item`'s title is `text-label` (15/20): its line is 20 px instead of an inherited 22.5, so
+a row without a 40 px leading slot is 2.5 px shorter (a title-only row is 48 px, above the 44 px
+hit area); rows with an avatar keep their 68 px.
+
+Fixed: `bf-list-item` sets `role="listitem"` only inside a `bf-list` (which provides the new internal
+`BF_LIST` token); a standalone row has no role, so axe no longer reports `aria-required-parent` for it.
+
+### 0.1.0
+
+New `bf-list` and `bf-list-item`: a `role="list"` container (inset by default, with a warm background and rounded corners; `inset=false` drops it for rows on a page) and a row with `leading`/`trailing` content slots, `title`/`subtitle` text, an optional trailing chevron, and an `interactive` mode that renders the row as a `<button>` emitting `clicked`. The interactive row's hover background is now `enabled:hover:bg-surface-muted` so a disabled row doesn't show a hover state; removed the unused `relative` from the row's base classes.