@bitforgehq/ui 0.3.0

package/ai/components/card.md

@@ -0,0 +1,303 @@
+# bf-card
+
+Content surface with an optional header slot, in four visual styles from raised to flat
+
+`BfCardComponent` from `@bitforgehq/ui` · Data display · since 0.1.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfBadgeComponent,
+  BfButtonComponent,
+  BfCardComponent,
+  BfActionDirective,
+  BfProgressComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * The bf-card overview.
+ *
+ * Live demo of `bf-card`: a raised project card whose heading is a stretched `bfAction` link (to this page's "Clickable card" section) with a raised Share button, a tint stat card whose heading is a stretched `bfAction` button, and an ink focus card whose actions respond.
+ */
+@Component({
+  selector: 'app-example-card-overview',
+  imports: [
+    RouterLink,
+    BfActionDirective,
+    BfCardComponent,
+    BfBadgeComponent,
+    BfProgressComponent,
+    BfButtonComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div class="grid grid-cols-1 gap-4 @sm:grid-cols-3">
+        <bf-card>
+          <span bfSlot="header" class="flex items-center justify-between">
+            <span class="text-caption text-text-muted">Project</span>
+            <bf-badge variant="success">On track</bf-badge>
+          </span>
+          <!-- The heading's link is the card's one action; its ::after covers the card. -->
+          <h2 class="text-heading">
+            <a bfAction routerLink="/components/card" fragment="clickable-card">Atlas rebrand</a>
+          </h2>
+          <bf-progress [value]="68" label="Atlas rebrand progress" />
+          <!-- Raised above the stretched link, so it keeps its own click. -->
+          <bf-button
+            class="relative z-1 self-start"
+            variant="tonal"
+            size="sm"
+            (clicked)="status.set('Shared Atlas rebrand.')"
+          >
+            Share
+          </bf-button>
+        </bf-card>
+        <bf-card variant="tint">
+          <h2 class="text-caption text-primary-strong font-semibold">
+            <button bfAction type="button" (click)="openStats()">Completed this week</button>
+          </h2>
+          <span class="text-heading">18 · +4 vs last week</span>
+        </bf-card>
+        <bf-card variant="ink" padding="lg">
+          <span class="text-caption font-semibold">Focus session</span>
+          <span class="text-heading">Block 45 minutes for the Atlas deck</span>
+          <div class="flex gap-2">
+            <bf-button size="sm" (clicked)="status.set('Focus session started.')">Start</bf-button>
+            <bf-button variant="tonal" size="sm" (clicked)="status.set('Snoozed for an hour.')">
+              Later
+            </bf-button>
+          </div>
+        </bf-card>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class CardOverviewExampleComponent {
+  readonly opened = signal(0);
+  readonly status = signal('Click a card, or one of its buttons.');
+
+  openStats(): void {
+    this.opened.update((count) => count + 1);
+    this.status.set(
+      `Opened the weekly stats ${this.opened()} ${this.opened() === 1 ? 'time' : 'times'}.`,
+    );
+  }
+}
+```
+
+## Overview
+
+Surface for a piece of content: a project summary, a stat, a focus prompt. Four variants from
+the design: raised (default), tint, ink and flat. To make the whole card clickable, put a
+`bfAction` link or button in its heading (the stretched-link pattern).
+
+Cards group a piece of content on the canvas. The raised card is the workhorse; tint highlights a stat or a callout; ink is the dark focus card; flat sits inside another surface.
+
+## When to use
+
+Use `bf-card` to group one piece of content on the canvas: a stat, a project summary, a callout. Make it clickable with a `bfAction` link when the whole card opens one thing. Use [bf-list](https://bitforge-ui.web.app/components/list) instead for repeated rows of the same kind, and [bf-alert](https://bitforge-ui.web.app/components/alert) for a status message.
+
+## Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfProgressComponent } from '@bitforgehq/ui';
+
+/** A project card with header, body and footer. */
+@Component({
+  selector: 'app-example-card-basic',
+  imports: [BfCardComponent, BfProgressComponent],
+  template: `
+    <bf-card>
+      <span bfSlot="header" class="text-caption text-text-muted">Project</span>
+      <h3 class="text-heading">Atlas rebrand</h3>
+      <bf-progress [value]="68" label="Progress" />
+      <span bfSlot="footer" class="text-caption text-text-muted">12 of 18 tasks</span>
+    </bf-card>
+  `,
+})
+export class CardBasicExampleComponent {}
+```
+
+## Variants
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent } from '@bitforgehq/ui';
+
+/** The tint and ink cards, and a flat card inside a raised one. */
+@Component({
+  selector: 'app-example-card-variants',
+  imports: [BfCardComponent],
+  template: `
+    <div class="grid gap-3 @sm:grid-cols-2">
+      <bf-card variant="tint"><span class="text-display">18</span></bf-card>
+      <bf-card variant="ink"
+        ><span class="text-heading">Block 45 minutes for the Atlas deck</span></bf-card
+      >
+      <bf-card class="@sm:col-span-2">
+        <bf-card variant="flat">Inside a raised card</bf-card>
+      </bf-card>
+    </div>
+  `,
+})
+export class CardVariantsExampleComponent {}
+```
+
+## Clickable card
+
+A card that opens something is a stretched link: its heading holds the one interactive element, an `<a bfAction>` (navigation, with `href` or `routerLink`) or a `<button bfAction>` (an action on the page), and `bfAction` stretches that element's hit area over the whole card with an `::after`. The heading stays a heading, the link's name is the title alone, and the card shows the pointer, the `shadow-floating` hover and the focus ring (drawn on the card while the link has keyboard focus). Import `BfActionDirective` from `@bitforgehq/ui`.
+
+Other controls inside the card (a secondary button, a menu) sit above the stretched area with `class="relative z-1"`, so they stay independently clickable; everything else (text, a progress bar, a badge) clicks through to the link. Text under the stretched area cannot be selected or copied, because a press there lands on the link; give text that must stay copyable (an ID, an address) `class="relative z-1"` too, and it then no longer clicks through. The card lights up only for its own action: a card that holds navigation rows (`bf-list-item` with a `bfAction` title) is not itself clickable, and only the rows show the pointer, hover and ring.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  BfActionDirective,
+  BfButtonComponent,
+  BfCardComponent,
+  BfProgressComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * Clickable cards.
+ *
+ * The first card's heading is a stretched `<a bfAction>` link, with a Share button above it;
+ * the second's is a stretched `<button bfAction>` that acts on the page.
+ */
+@Component({
+  selector: 'app-example-card-clickable',
+  imports: [RouterLink, BfActionDirective, BfButtonComponent, BfCardComponent, BfProgressComponent],
+  template: `
+    <div class="grid gap-3 @sm:grid-cols-2">
+      <bf-card>
+        <span bfSlot="header" class="text-caption text-text-muted">Project</span>
+        <h3 class="text-heading"><a bfAction routerLink="/components/card">Atlas rebrand</a></h3>
+        <bf-progress [value]="68" label="Atlas rebrand progress" />
+        <bf-button class="relative z-1" variant="tonal" size="sm" (clicked)="status.set('Shared.')"
+          >Share</bf-button
+        >
+      </bf-card>
+
+      <bf-card variant="tint">
+        <h3 class="text-heading">
+          <button bfAction type="button" (click)="status.set('Stats opened.')">
+            Completed this week
+          </button>
+        </h3>
+        <span class="text-caption">18 · +4 vs last week</span>
+      </bf-card>
+      <p aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class CardClickableExampleComponent {
+  protected readonly status = signal('');
+}
+```
+
+`interactive` and `clicked`, which made the whole card one `<button>`, are deprecated since 0.3.0 and removed in 1.0.0: a button cannot hold a heading or another control, so screen readers heard one run-on name and lost the heading. Replace `<bf-card [interactive]="true" (clicked)="open()">` with a `bfAction` link or button in the card's heading.
+
+## Desktop
+
+A card holding a `bfAction` shows the pointer and lifts to `shadow-floating` while the pointer is anywhere over it; hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring is drawn around the whole card while its link or button has keyboard focus, not after a click. A link card keeps the browser's link behaviour: Ctrl/Cmd-click and a middle click open it in a new tab, and the status bar shows its URL on hover. Text under the stretched link cannot be selected with the mouse; give text that must stay copyable `class="relative z-1"`.
+
+## Theming
+
+Consumes tokens by variant, background then text, plus elevation:
+
+- `raised` (default): `surface` / `text`, `shadow-raised`
+- `tint`: `primary-soft` / `text`
+- `ink`: `text` / `bg`
+- `flat`: `surface` / `text`, `border-strong` (≥ 3:1, so the edge reads without a shadow)
+
+Padding comes from the spacing tokens: `md` is `--spacing-card` (18 px, `p-card`) and `lg` is `--spacing-card-lg` (24 px, `p-card-lg`), so an app can retune both in its `@theme`.
+
+A card holding its own `bfAction` element (or the deprecated `interactive` card) shows a pointer cursor, lifts to `shadow-floating` on hover, drops back to `shadow-raised` while its action is pressed and draws a focus ring on the `ring` token while its action has keyboard focus.
+
+Content is aligned to the inline start (`text-start`), so it follows `dir="rtl"`.
+
+## Accessibility
+
+The card renders a plain `<div>` with no role. A clickable card follows the stretched-link pattern: the only interactive element is the `bfAction` link or button in its heading, so the heading stays in the screen reader's heading list, the element's accessible name is the title alone, a link keeps link semantics ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/): Enter, a new tab on Ctrl/Cmd-click) and a button keeps button semantics ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/): Enter and Space). Tab reaches the action once per card, then any raised secondary control (a link action: 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). Under forced colours (Windows High Contrast), where the card's ring is dropped, a system-coloured outline around the whole card marks the focused action. The `::after` extension is invisible and adds nothing to the accessibility tree. The deprecated `interactive` card renders a native `<button>` around all content instead, which hides headings and must not hold other controls.
+
+### Keyboard
+
+| Key              | Action                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd>   | Moves to the card's `bfAction` link or button, then to each raised secondary control |
+| <kbd>Enter</kbd> | Follows a `bfAction` link, or activates a `bfAction` button                          |
+| <kbd>Space</kbd> | Activates a `bfAction` button; a link ignores it                                     |
+
+## Inputs
+
+| Name          | Type                                                      | Default    | Description                                                                                                                               |
+| ------------- | --------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`     | `BfCardVariant` (`'raised' \| 'tint' \| 'ink' \| 'flat'`) | `'raised'` | Surface treatment: raised (default), tint, ink, flat.                                                                                     |
+| `interactive` | `boolean`                                                 | `false`    | Whole card is a button that emits `clicked`. **Deprecated** (0.3.0 use a bfAction link or button in the card's heading; removed in 1.0.0) |
+| `padding`     | `BfCardPadding` (`'md' \| 'lg'`)                          | `'md'`     | Inner padding: md 18 px (`--spacing-card`), lg 24 px (`--spacing-card-lg`).                                                               |
+
+## Outputs
+
+| Name      | Payload | Description                                                                                                                                 |
+| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clicked` | `Event` | Emitted when an interactive card is activated. **Deprecated** (0.3.0 use a bfAction link or button in the card's heading; removed in 1.0.0) |
+
+## Slots
+
+- `header`: Content above the body, such as a title row.
+- `default`: The card body.
+- `footer`: Content below the body, such as its actions.
+
+## Notes
+
+### Do
+
+- One idea per card; use `bf-list` for repeated rows.
+- Use `lg` padding for cards that hold a heading and several blocks.
+- Make a card clickable with one `bfAction` link or button in its heading; give other controls in it `class="relative z-1"`.
+
+### Don't
+
+- Don't nest raised cards; use `flat` inside.
+- Don't use `interactive` (deprecated) or wrap a card in an `<a>`; both hide the heading and nest interactive content.
+- Don't put more than one `bfAction` in a card.
+- Don't put a `text` button on an ink card — its primary colour fails contrast on ink; use `tonal` or `outline`.
+
+## Migration notes
+
+### 0.3.0
+
+**Behaviour:** logical properties: content aligns to the inline start (`text-start`).
+
+**Deprecated:** `interactive` and `clicked` (removed in 1.0.0): a card-sized `<button>` hid the
+heading and could not hold other controls. Use the new stretched-link pattern instead: a
+`bfAction` link or button (`BfActionDirective`, new in `@bitforgehq/ui`) in the card's heading
+stretches its hit area over the card, which is now always `relative` and shows the pointer, the
+`shadow-floating` hover and the focus ring (on keyboard focus) while it holds its own `bfAction`
+(it registers with the nearest card or row, so a card holding navigation rows is not lit by them);
+secondary controls take `class="relative z-1"`. Text under the stretched area is not selectable.
+See Migration 12.
+
+JSDoc of `card.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `header`, `default`, `footer`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): a card holding a `bfAction` drops from `shadow-floating` back to `shadow-raised` while its action is held down (`has-[[data-bf-action]:active]`), the deprecated `interactive` card while it is. None while disabled; under forced colours the system colours win.
+
+`padding="lg"` is `p-card-lg` (the new `--spacing-card-lg` token, 24 px) instead of `p-6`
+(F-063); the rendered padding is unchanged, and an app can now retune it in its `@theme`.
+
+### 0.2.0
+
+The `flat` border is `border-strong` (was `border`, 1.32:1).
+
+### 0.1.0
+
+The card surface now fills its host (`h-full`), so cards in a stretched grid row end at the same height instead of ragged bottoms; block hosts of auto height are unaffected.
+
+New `bf-card`: a content surface with `header`/default/`footer` slots and four variants — `raised` (default, `shadow-raised`), `tint`, `ink` and `flat`. `padding` is `md` (18 px, default) or `lg` (24 px). `interactive` renders the card as a `<button>` that emits `clicked` and adds a hover shadow and focus ring.