@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/calendar.md

@@ -0,0 +1,300 @@
+# bf-calendar
+
+Inline month calendar for picking one date, with month and year jumps
+
+`BfCalendarComponent` from `@bitforgehq/ui` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfCalendarComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-calendar overview.
+ *
+ * Live demo of `bf-calendar`: a due date picked by click or keyboard (the value is a plain ISO
+ * date string), the header's month buttons and month and year jump, and a status line with the
+ * picked date and the month on show.
+ */
+@Component({
+  selector: 'app-example-calendar-overview',
+  imports: [BfCalendarComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-calendar label="Due date" locale="en-GB" [(value)]="due" [(month)]="month" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class CalendarOverviewExampleComponent {
+  /** The picked date, 'YYYY-MM-DD'. */
+  readonly due = signal<string | null>('2026-10-14');
+  /** The month on show, 'YYYY-MM'; null opens on the due date's month. */
+  readonly month = signal<string | null>(null);
+
+  /** The picked date, and the month on show once the user has browsed to one. */
+  readonly status = computed(() => {
+    const month = this.month();
+    return `Due: ${this.due() ?? 'none'}${month ? ` · showing ${month}` : ''}`;
+  });
+}
+```
+
+## Overview
+
+Inline month calendar for picking one date, an ARIA grid with full keyboard support. The value
+is a plain ISO date string ('YYYY-MM-DD', never a Date with a time zone) or `null`; month and
+weekday names come from `Intl` in the calendar's `locale`; implements the Signal Forms value
+contract.
+
+A calendar shows one month as a grid of days for picking a single date. Its value is a plain ISO date string (`'2026-10-14'`), never a `Date` with a time of day, so no time zone can shift the day. Month and weekday names come from `Intl` in the calendar's locale, the header jumps to another month or year in two clicks, and it binds to Signal Forms like any other field.
+
+## When to use
+
+Use `bf-calendar` for an inline calendar that sits on the page: a booking page, a dashboard filter, a side panel where the month is always in view. For a date in a form field use [bf-date-input](https://bitforge-ui.web.app/components/date-input) instead: a typed date field that opens this calendar in a popover. Use [bf-select](https://bitforge-ui.web.app/components/select) or [bf-segmented](https://bitforge-ui.web.app/components/segmented) instead when the choice is a few fixed dates (today, tomorrow, next week). The calendar works the same in both shells: in a Capacitor app make it `lg` (48 px cells) for touch.
+
+## Value and month
+
+`value` is the picked date as `'YYYY-MM-DD'`, `null` while none is picked. `(changed)` emits the new date right after the user picks a different one, never for a value you set; `(picked)` emits on every pick, also of the date that already was the value, so a popover around the calendar knows when to close.
+
+`month` (`'YYYY-MM'`) is the month on show, two-way bindable. Left `null`, the calendar opens on the value's month, else on today's (kept inside `min` and `max`); the previous/next buttons, the month and year views and the keyboard write it. Bind `[(month)]` to keep it, or set it to open on another month. Once the user has browsed away, a new `value` you set does not move the view; set `month` with it. `today` sets the date marked as today (for an app that works in another time zone than the device); unset it is the device's local date.
+
+Only the days of the shown month are rendered; the cells of the neighbouring months stay empty. So every date appears once, the keyboard moves through one month at a time and crosses into the next one by moving past its end, and a screen reader never reads a date twice. The grid always takes six weeks of height, so the calendar never changes height between months.
+
+## Min, max and disabled dates
+
+`min` and `max` (ISO dates) bound the dates that can be picked; earlier and later days show disabled, the previous/next buttons stop at the months that hold them, and the year view lists only their years. `disabledDate` rules out more dates: a function called with each ISO date, here every weekend. Disabled days stay focusable (`aria-disabled`, as the ARIA grid pattern asks), so the arrow keys step onto them and past them, but a click, <kbd>Enter</kbd> or <kbd>Space</kbd> does nothing.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfCalendarComponent, type BfCalendarDisabledDate } from '@bitforgehq/ui';
+
+/**
+ * Min, max and disabled weekends.
+ *
+ * A delivery date between 2 November and 18 December 2026 on working days only: `min` and `max`
+ * bound the range (the month buttons stop there) and `disabledDate` rules out Saturdays and
+ * Sundays.
+ */
+@Component({
+  selector: 'app-example-calendar-min-max-disabled',
+  imports: [BfCalendarComponent],
+  template: `
+    <bf-calendar
+      label="Delivery date"
+      locale="en-GB"
+      min="2026-11-02"
+      max="2026-12-18"
+      [disabledDate]="weekends"
+      [(value)]="delivery"
+    />
+  `,
+})
+export class CalendarMinMaxDisabledExampleComponent {
+  readonly delivery = signal<string | null>('2026-11-04');
+
+  /** Saturdays and Sundays; an ISO date parses as UTC midnight, so getUTCDay is its weekday. */
+  readonly weekends: BfCalendarDisabledDate = (iso) => [0, 6].includes(new Date(iso).getUTCDay());
+}
+```
+
+## Locale and first day of the week
+
+`locale` (a BCP 47 tag) sets the month and weekday names, the full date each day is announced with, and the first column of the week. Empty, it follows the document's `lang`, else English. `firstDayOfWeek` (`0` Sunday to `6` Saturday) overrides the week the locale gives; without it the calendar asks `Intl.Locale`'s week info and falls back to Monday where the runtime has none. Here a German calendar, which starts on Monday. Put a `lang` on the element around it, so a screen reader reads the names in that language. The button names (previous/next month, choose month, choose year) are labels: translate them with `provideBfLabels()`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfCalendarComponent } from '@bitforgehq/ui';
+
+/**
+ * A German calendar.
+ *
+ * `locale="de"` gives German month and weekday names and a week that starts on Monday; the `lang`
+ * around it makes a screen reader read them in German.
+ */
+@Component({
+  selector: 'app-example-calendar-locale',
+  imports: [BfCalendarComponent],
+  template: `
+    <div lang="de">
+      <bf-calendar label="Liefertermin" locale="de" [(value)]="delivery" />
+    </div>
+  `,
+})
+export class CalendarLocaleExampleComponent {
+  readonly delivery = signal<string | null>('2026-10-14');
+}
+```
+
+## Sizes
+
+`size` sets the cell: `sm` 32 px, `md` 40 px (default), `lg` 48 px; the previous/next buttons and the title button take the same height. Unset, `size` follows `provideBfDefaults()`'s `controlSize`. Under a coarse pointer (touch) every day cell and header button is at least 44 px: the `sm` and `md` cells grow to 44 px (the calendar gets wider), `lg` stays 48 px. The calendar is seven cells wide and shrinks with a narrow column, the columns getting narrower and the rows keeping their height.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCalendarComponent } from '@bitforgehq/ui';
+
+/**
+ * Calendar sizes.
+ *
+ * The sm, md and lg steps (32, 40 and 48 px cells); under a coarse pointer the sm and md cells
+ * grow to 44 px.
+ */
+@Component({
+  selector: 'app-example-calendar-sizes',
+  imports: [BfCalendarComponent],
+  template: `
+    <div class="flex flex-wrap items-start gap-6">
+      <bf-calendar size="sm" label="Small" locale="en-GB" value="2026-10-14" />
+      <bf-calendar label="Medium" locale="en-GB" value="2026-10-14" />
+      <bf-calendar size="lg" label="Large" locale="en-GB" value="2026-10-14" />
+    </div>
+  `,
+})
+export class CalendarSizesExampleComponent {}
+```
+
+## Month and year views
+
+The title button (the month and year) opens the month view: the twelve months of the year, the shown one selected. Its title (the year) opens the year view, a scrolling list of years (those of `min` to `max`, else a hundred years either side). Picking a year opens its months; picking a month shows its days. <kbd>Escape</kbd> in either view returns to the days without picking.
+
+## With Signal Forms
+
+Bind the field with `[formField]`. Required, touched, errors, disabled and readonly flow in; the first error shows under the calendar once focus has left it, and `errorMessage` shows at once. `readonly` shows the value and lets the user browse months but blocks picking; `disabled` blocks everything and takes the calendar out of the tab order. `name` is accepted for Signal Forms but not rendered (the calendar has no native form element). `focus()` focuses the day that holds the tab stop.
+
+## Naming the calendar
+
+`label` is the calendar's accessible name (it is not shown), such as "Due date". Without it use `ariaLabel`, or `ariaLabelledby` pointing at a visible heading. The day grid itself is named by the month and year in the header. In specs, `BfCalendarHarness` from `@bitforgehq/ui/testing` finds a calendar by its `label` and picks a date by its ISO string.
+
+## Desktop
+
+Hovering a pickable day tints its mark `surface-muted` (the selected day `primary-hover`) with the pointer cursor; disabled days show the not-allowed cursor and no tint, and a read-only calendar has neither. Hover styles apply only on devices that can hover. The focus ring shows on keyboard focus only, on the day's round mark. Under a fine pointer each cell is its own hit area at every size; desktop density is `md`, and `provideBfDefaults({ size: 'sm' })` makes a dense calendar for a sidebar or a toolbar popover ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Day mark: `text`, hover `surface-muted`, pressed `surface-pressed`. Selected: `primary` with `on-primary`, hover `primary-hover`, pressed `primary-pressed`, bold (under `forced-colors` the system `Highlight` / `HighlightText` pair).
+- Today: a 1.5 px inset `primary-strong` ring and bold text, so it never rests on colour alone (`CanvasText` under `forced-colors`).
+- Disabled day: `text-disabled`; a disabled selected day keeps a `surface-sunken` pill with a `text-disabled` ring (`GrayText` under `forced-colors`).
+- Weekday header: `text-muted`. Header buttons: `text-muted`, hover `surface-muted` with `text`; the title `text`, bold.
+- Focus ring: `ring`. Error: a 1.5 px `danger-border` ring around the grid, the message below in `danger`.
+- Shape: the marks, month and year pills and header buttons use `rounded-control` (`9999px` by default, so the day marks are round); the error ring `rounded-card`.
+
+## Accessibility
+
+The calendar is a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`). The days are a `table` with `role="grid"`, named by the header's month and year (`aria-labelledby`); weekday columns are `th scope="col"` with the short name shown and the full name in `abbr`. Each day is a `gridcell` named by its full date in the locale ("Wednesday, 14 October 2026"); the selected day has `aria-selected="true"` (the others `"false"`), today `aria-current="date"`, and disabled days `aria-disabled="true"`: they stay focusable so the keyboard can move past them. One day holds the tab stop (roving `tabindex`): the last one moved to, else the selected day, else today, else the first day of the month inside `min`. A polite live region announces the month and year when they change. The grid carries `aria-readonly`, `aria-required`, `aria-disabled`, and once touched and invalid `aria-invalid` with `aria-errormessage`; the group's `aria-describedby` names the error. The previous/next buttons are named from the `calendarPreviousMonth` and `calendarNextMonth` labels and turn `aria-disabled` (keeping focus) past `min`/`max`; the title button reads its text followed by `calendarChooseMonth` or `calendarChooseYear`. The month and year views are grids too, with the shown month or year selected and the current one `aria-current="date"`; each month is named with its year. The chevrons and the caret are CSS borders and mirror under `dir="rtl"`, where <kbd>ArrowLeft</kbd> and <kbd>ArrowRight</kbd> swap as the days run right to left. Focus moves into the new grid when a view opens or closes.
+
+### Keyboard
+
+Moving never picks; <kbd>Enter</kbd> or <kbd>Space</kbd> does. Moves stop at `min` and `max`. While `readonly` the keys still move, and picking a day does nothing.
+
+| Key                                                      | Where          | Action                                                                                   |
+| -------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>         | Calendar       | Moves between the title button, the previous/next buttons and the grid's one tab stop    |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd>             | Days           | Next / previous day, into the neighbouring month at the ends (swapped under `dir="rtl"`) |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>                | Days           | Same weekday next / previous week                                                        |
+| <kbd>PageDown</kbd> / <kbd>PageUp</kbd>                  | Days           | Same day next / previous month (the 31st becomes the month's last day)                   |
+| <kbd>Shift</kbd>+<kbd>PageDown</kbd> / <kbd>PageUp</kbd> | Days           | Same day next / previous year                                                            |
+| <kbd>Home</kbd> / <kbd>End</kbd>                         | Days           | First / last day of the week                                                             |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                      | Days           | Picks the focused day (not a disabled one)                                               |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                      | Header buttons | The title opens the month (then the year) view; previous/next show the month             |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd>             | Months, years  | Next / previous month or year (swapped under `dir="rtl"`)                                |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>                | Months, years  | Next / previous row (three months, four years)                                           |
+| <kbd>Home</kbd> / <kbd>End</kbd>                         | Months, years  | First / last of the row                                                                  |
+| <kbd>PageDown</kbd> / <kbd>PageUp</kbd>                  | Months, years  | Same month next / previous year; twenty years on or back                                 |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                      | Months, years  | A month shows its days; a year opens its months                                          |
+| <kbd>Escape</kbd>                                        | Months, years  | Back to the days without picking (stops there, so a popover around it stays open)        |
+
+## Inputs
+
+| Name             | Type                                                                              | Default     | Description                                                                                                                                                                                       |
+| ---------------- | --------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `string \| undefined`                                                             | `undefined` | The earliest date that can be picked (ISO); earlier dates show disabled. Set by `[formField]`; do not bind it yourself.                                                                           |
+| `max`            | `string \| undefined`                                                             | `undefined` | The latest date that can be picked (ISO); later dates show disabled. Set by `[formField]`; do not bind it yourself.                                                                               |
+| `disabledDate`   | `BfCalendarDisabledDate \| null`                                                  | `null`      | Marks more dates as not pickable (weekends, booked days); called with each ISO date.                                                                                                              |
+| `firstDayOfWeek` | `BfCalendarWeekday \| undefined` (`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined`) | `undefined` | The first column's weekday, 0 Sunday to 6 Saturday; unset follows the locale's week (else Monday).                                                                                                |
+| `locale`         | `string`                                                                          | `''`        | BCP 47 locale of the month and weekday names and of the week; empty follows the document's `lang`, else English.                                                                                  |
+| `today`          | `string \| undefined`                                                             | `undefined` | The date marked as today (ISO); unset is the device's local date.                                                                                                                                 |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                       | `undefined` | Cell size: sm 32, md 40, lg 48 px (44 px under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                           |
+| `disabled`       | `boolean`                                                                         | `false`     | Disables the whole calendar: nothing is focusable or pickable. Set by `[formField]`; do not bind it yourself.                                                                                     |
+| `readonly`       | `boolean`                                                                         | `false`     | Shows the value and lets the user browse the months, but blocks picking. Set by `[formField]`; do not bind it yourself.                                                                           |
+| `required`       | `boolean`                                                                         | `false`     | Marks the date required (`aria-required` on the day grid). Set by `[formField]`; do not bind it yourself.                                                                                         |
+| `invalid`        | `boolean`                                                                         | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                                                  |
+| `touched`        | `boolean`                                                                         | `false`     | Whether the user has left the calendar; errors show only once touched. Set by `[formField]`; do not bind it yourself.                                                                             |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`                                | `[]`        | Validation errors from Signal Forms; the first message is shown once touched. Set by `[formField]`; do not bind it yourself.                                                                      |
+| `errorMessage`   | `string`                                                                          | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                                                                   |
+| `label`          | `string`                                                                          | `''`        | Accessible name of the calendar (not rendered visibly), such as "Due date".                                                                                                                       |
+| `ariaLabel`      | `string`                                                                          | `''`        | Accessible name when `label` is not set.                                                                                                                                                          |
+| `ariaLabelledby` | `string`                                                                          | `''`        | Id(s) of the element(s) that name the calendar (a visible heading) when `label` is not set.                                                                                                       |
+| `name`           | `string`                                                                          | `''`        | Name of the bound field. Not rendered (the calendar has no native form element); kept so Signal Forms can bind it. Set by `[formField]`; do not bind it yourself.                                 |
+| `id`             | `string`                                                                          | `generated` | The calendar's id; generated when not set.                                                                                                                                                        |
+| `value`          | `string \| null`                                                                  | `null`      | The picked date as an ISO string ('YYYY-MM-DD'), `null` while none is picked; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                                                  |
+| `month`          | `string \| null`                                                                  | `null`      | The month on show ('YYYY-MM'), two-way bindable; `null` shows the value's month, else today's. The previous/next buttons, the month and year views and the keyboard set it. Two-way: `[(month)]`. |
+
+## Outputs
+
+| Name      | Payload  | Description                                                                                                                                    |
+| --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `changed` | `string` | Emitted with the new date right after the user picks a different one.                                                                          |
+| `picked`  | `string` | Emitted with the date the user picked (click, Enter or Space), also when it already was the value, so a popover around the calendar can close. |
+| `touch`   | `void`   | Emitted when focus leaves the calendar, so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself.                |
+
+## Methods
+
+### `isDateDisabled(iso: string): boolean`
+
+Whether a date cannot be picked: it is outside `min`…`max` or `disabledDate` rules it out.
+
+| Parameter | Type     | Description            |
+| --------- | -------- | ---------------------- |
+| `iso`     | `string` | The ISO date to check. |
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the cell that owns the tab stop of the grid on show; Signal Forms calls it from
+`focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+### `select(iso: string): void`
+
+Picks `iso` as a click on its day would: ignored while disabled or read-only, and for an
+invalid or disabled date. Shows its month.
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `iso`     | `string` | The ISO date to pick. |
+
+## Notes
+
+### Do
+
+- Give the calendar a `label` (or `ariaLabel` / `ariaLabelledby`); it is the accessible name.
+- Store and send the value as the ISO string it is; turn it into a `Date` only to display or compute, at UTC midnight.
+- Bound the range with `min` and `max` rather than `disabledDate` alone, so the buttons and the year view stop there too.
+
+### Don't
+
+- Don't use it for a date range or several dates; it picks one date.
+- Don't put a calendar in a dense form row for an ordinary date field; a date input with a popover is the field form.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-calendar` in `@bitforgehq/ui`: an inline month calendar for picking one date. The value
+is a plain ISO date string (`'YYYY-MM-DD'`) or `null`, never a `Date`, so no time zone shifts
+the day; `(changed)` emits a new pick and `(picked)` every pick (for a popover to close).
+`[(month)]` (`'YYYY-MM'`) is the month on show. `min`, `max` and `disabledDate`
+(`BfCalendarDisabledDate`) disable dates; `firstDayOfWeek` (`BfCalendarWeekday`) and `locale`
+(default the document's `lang`) set the week and the `Intl` month and weekday names; `today`
+overrides the device's date; `size` sets the cells (32/40/48 px, 44 px under a coarse pointer).
+The header's title opens a month view and then a year view for quick jumps. An ARIA grid with
+roving focus: arrows by day and week (mirrored in RTL), Page Up/Down by month (Shift by year),
+Home/End to the week's ends, Enter/Space picks, Escape leaves the jump views; disabled days stay
+focusable with `aria-disabled`. Signal Forms value contract like `bf-segmented`. New label keys
+`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`, and
+a `BfCalendarHarness` in `@bitforgehq/ui/testing` (`getMonthLabel()`, `selectDate(iso)`,
+`getSelected()`, `nextMonth()`, `previousMonth()`).

package/ai/components/card.md

@@ -95,7 +95,7 @@ Surface for a piece of content: a project summary, a stat, a focus prompt. Four
 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.
+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 is the outlined card for a page level that should stay quiet, such as a dense grid of cards.
 
 ## When to use
 
@@ -148,6 +148,107 @@ import { BfCardComponent } from '@bitforgehq/ui';
 export class CardVariantsExampleComponent {}
 ```
 
+## Nesting surfaces
+
+Each level of a page takes one surface style, and a level inside a card steps down, never up:
+
+- **Raised card, then sunken tile.** Inside a raised card, group figures or blocks on sunken, borderless tiles: [bf-stat](https://bitforge-ui.web.app/components/stat) `variant="tile"`, or your own block on `bg-surface-sunken` with the `card` radius.
+- **Never an outlined surface inside a raised one.** A `flat` card or a `card` stat inside a raised card draws a border on top of a shadow, two edges for one level; use a tile instead. Don't nest raised cards either.
+- **One surface style per level of a dashboard.** All cards on the page are raised (or all flat), and all tiles in them are sunken; mixing raised and flat cards side by side, or tiles and outlined stats in one card, reads as different kinds of content. The [bf-stat dashboard example](https://bitforge-ui.web.app/components/stat) puts raised cards on the page and sunken tiles in each.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfStatComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { CircleCheck, Clock, ListTodo } from 'lucide';
+
+/**
+ * A raised card holding a row of sunken tiles.
+ *
+ * One surface per level: the card is raised on the page, and the stats inside it are sunken,
+ * borderless tiles (`bf-stat variant="tile"`), never outlined surfaces.
+ */
+@Component({
+  selector: 'app-example-card-nesting',
+  imports: [BfCardComponent, BfIconComponent, BfStatComponent],
+  template: `
+    <bf-card padding="lg">
+      <h3 class="text-heading">This week</h3>
+      <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+        <bf-stat label="Open tasks" value="14" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+        </bf-stat>
+        <bf-stat label="Done" value="23" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="circleCheck" />
+        </bf-stat>
+        <bf-stat label="Time logged" value="31 h" variant="tile">
+          <bf-icon bfSlot="icon" [icon]="clock" />
+        </bf-stat>
+      </div>
+    </bf-card>
+  `,
+})
+export class CardNestingExampleComponent {
+  protected readonly listTodo = ListTodo;
+  protected readonly circleCheck = CircleCheck;
+  protected readonly clock = Clock;
+}
+```
+
+## Footer
+
+Content in `bfSlot="footer"` sits on the card's bottom edge: it takes the free space above it, so in a grid of cards (a `bf-card` fills its grid cell, `h-full`) every footer lines up, however differently the descriptions wrap, and the body keeps its 12 px gap above the footer. Put the footer's parts in one element (`<div bfSlot="footer" class="flex …">`), so they move together.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent, BfButtonComponent, BfCardComponent } from '@bitforgehq/ui';
+
+interface Project {
+  readonly id: string;
+  readonly name: string;
+  readonly summary: string;
+  readonly status: string;
+}
+
+/** A grid of cards whose descriptions wrap differently, with every footer on the bottom edge. */
+@Component({
+  selector: 'app-example-card-grid',
+  imports: [BfBadgeComponent, BfButtonComponent, BfCardComponent],
+  template: `
+    <div class="grid gap-4 @md:grid-cols-3">
+      @for (project of projects; track project.id) {
+        <bf-card>
+          <h3 class="text-heading">{{ project.name }}</h3>
+          <p class="text-body text-text-muted">{{ project.summary }}</p>
+          <div bfSlot="footer" class="flex items-center justify-between gap-2">
+            <bf-badge>{{ project.status }}</bf-badge>
+            <bf-button variant="outline" size="sm">Open</bf-button>
+          </div>
+        </bf-card>
+      }
+    </div>
+  `,
+})
+export class CardGridExampleComponent {
+  readonly projects: readonly Project[] = [
+    { id: 'atlas', name: 'Atlas rebrand', summary: 'New logo and colours.', status: 'Active' },
+    {
+      id: 'harbor',
+      name: 'Harbor onboarding',
+      summary:
+        'Rewrite the first-run flow so a new team reaches its first shared board in under five minutes, with sample data.',
+      status: 'Planning',
+    },
+    {
+      id: 'lumen',
+      name: 'Lumen reports',
+      summary: 'Weekly PDF exports for the finance team, scheduled per workspace.',
+      status: 'Review',
+    },
+  ];
+}
+```
+
 ## 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`.
@@ -252,25 +353,39 @@ The card renders a plain `<div>` with no role. A clickable card follows the stre
 
 - `header`: Content above the body, such as a title row.
 - `default`: The card body.
-- `footer`: Content below the body, such as its actions.
+- `footer`: Content below the body, such as its actions; it sits on the card's bottom edge.
 
 ## Notes
 
 ### Do
 
-- One idea per card; use `bf-list` for repeated rows.
+- One idea per card; use `bf-list` for repeated rows (`[inset]="false" divided class="-mx-card"` runs them edge to edge on the card).
 - Use `lg` padding for cards that hold a heading and several blocks.
+- Put a card's actions and status in one `bfSlot="footer"` element, so they line up across a grid.
 - 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 nest raised cards, and don't put an outlined surface (`flat`, a `card` stat) inside a raised one; use sunken tiles (`bf-stat variant="tile"`) inside.
+- Don't mix surface styles on one level of a dashboard; keep one per level.
 - 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.2
+
+New "Nesting surfaces" docs section: a raised card holds sunken tiles, never an outlined
+surface (`flat`, a `card` stat), and each level of a dashboard keeps one surface style. New
+`card/nesting` example. No code change.
+
+### 0.3.1
+
+The footer (`bfSlot="footer"`) sits on the card's bottom edge (`mt-auto`), so in a grid of cards
+whose descriptions wrap differently every footer lines up. A card whose footer already followed
+the body directly looks the same unless the card is taller than its content.
+
 ### 0.3.0
 
 **Behaviour:** logical properties: content aligns to the inline start (`text-start`).