@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/button.md

@@ -95,12 +95,12 @@ export class ButtonOverviewExampleComponent {
 
 Also matches: `a[bfButton]`
 
-Pill-shaped action button with five variants, three sizes, a loading state and icon slots. Put
+Pill-shaped action button with six variants, three sizes, a loading state and icon slots. Put
 the label in the default slot and icons in the `icon-start` / `icon-end` slots; never place a
 `bf-button` inside another interactive element. For navigation, put `bfButton` on your own `<a>`
 (with `href` or `routerLink`): it renders as a real link that looks like the button.
 
-Buttons trigger an action or move the user forward. The shape is a pill in every variant; the variant encodes emphasis, so a screen reads correctly at a glance: one `primary`, `tonal` beside it, `text` for low-emphasis actions inside cards and rows.
+Buttons trigger an action or move the user forward. The shape is a pill in every variant; the variant encodes emphasis, so a screen reads correctly at a glance: one `primary`, `tonal` beside it, `text` for low-emphasis actions inside cards and rows, `ghost` for quiet neutral actions and navigation.
 
 ## When to use
 
@@ -140,13 +140,13 @@ export class ButtonBasicExampleComponent {
 
 ## Variants
 
-`primary` (filled sage), `tonal` (soft tint), `outline`, `text` and `danger`.
+`primary` (filled), `tonal` (soft tint), `outline`, `text`, `danger` and `ghost`. `ghost` is the quiet neutral one: muted text with no fill at rest and a neutral surface on hover, with the `text` variant's padding. Use it for secondary toolbar actions and navigation rows, where a row of `text` buttons would read as a row of coloured links and `tonal` would tint every one. `variant` takes a `BfButtonAppearance` (the five `BfButtonVariant` styles plus `ghost`).
 
 ```ts
 import { Component } from '@angular/core';
 import { BfButtonComponent } from '@bitforgehq/ui';
 
-/** The five button variants. */
+/** The six button variants. */
 @Component({
   selector: 'app-example-button-variants',
   imports: [BfButtonComponent],
@@ -157,6 +157,7 @@ import { BfButtonComponent } from '@bitforgehq/ui';
       <bf-button variant="outline">Outline</bf-button>
       <bf-button variant="text">Text</bf-button>
       <bf-button variant="danger">Delete</bf-button>
+      <bf-button variant="ghost">Ghost</bf-button>
     </div>
   `,
 })
@@ -300,9 +301,57 @@ export class ButtonLinkExampleComponent {
 }
 ```
 
+## Navigation
+
+A row of `a[bfButton variant="ghost"]` is a top navigation or a sidebar. The link of the current page shows it: `ghost` and `text` links with `aria-current="page"` take the tonal fill (`outline` draws its border in primary), so the template needs no `[variant]` switch. With the router, add `routerLinkActive` and `ariaCurrentWhenActive="page"` to each link and the router sets `aria-current` for you. Put the links in a `<nav>` with an `aria-label`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+interface NavLink {
+  readonly id: string;
+  readonly label: string;
+}
+
+/**
+ * A top navigation of ghost links.
+ *
+ * The current page carries `aria-current="page"` and shows it; with the router,
+ * `routerLinkActive` and `ariaCurrentWhenActive="page"` set it instead of the click handler.
+ */
+@Component({
+  selector: 'app-example-button-nav',
+  imports: [BfButtonComponent],
+  template: `
+    <nav aria-label="Main" class="flex flex-wrap items-center gap-1">
+      @for (link of links; track link.id) {
+        <a
+          bfButton
+          variant="ghost"
+          [href]="'#' + link.id"
+          [attr.aria-current]="link.id === current() ? 'page' : null"
+          (click)="$event.preventDefault(); current.set(link.id)"
+          >{{ link.label }}</a
+        >
+      }
+    </nav>
+  `,
+})
+export class ButtonNavExampleComponent {
+  protected readonly links: readonly NavLink[] = [
+    { id: 'overview', label: 'Overview' },
+    { id: 'projects', label: 'Projects' },
+    { id: 'team', label: 'Team' },
+    { id: 'settings', label: 'Settings' },
+  ];
+  protected readonly current = signal('overview');
+}
+```
+
 ## Desktop
 
-Hover darkens the fill (`primary`, `tonal`, `danger`), the border (`outline`) or the text (`text`), with the pointer cursor; a disabled button shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only (`focus-visible`), never after a mouse click. Under a fine pointer the visible box is the hit area, so `sm` (32 px) buttons sit side by side in toolbars and table rows without overlapping hit areas. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
+Hover darkens the fill (`primary`, `tonal`, `danger`), the border (`outline`) or the text (`text`), or lays a neutral surface under `ghost`, with the pointer cursor; a disabled button shows `not-allowed`. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring shows on keyboard focus only (`focus-visible`), never after a mouse click. Under a fine pointer the visible box is the hit area, so `sm` (32 px) buttons sit side by side in toolbars and table rows without overlapping hit areas. Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
 
 ## Theming
 
@@ -313,10 +362,16 @@ Consumes tokens by variant, rest → hover:
 - `outline`: `surface` / `text` / `border-strong` (the control boundary, ≥ 3:1) → `text-muted` border; focus swaps the border to `primary`
 - `text`: `primary-text` (primary as text, ≥ 4.5:1 on `bg` and `surface`) → `primary-strong`
 - `danger`: `danger-soft` / `danger` → `danger` / `danger-soft`
+- `ghost`: transparent / `text-muted` → `surface-muted` / `text`
+
+Current page (`a[bfButton]` with `aria-current="page"`): `ghost` and `text` take `primary-soft` /
+`primary-strong` (→ `primary-soft-hover` on hover, `primary-soft-pressed` while pressed), `outline` a `primary` border with
+`primary-strong` text; under forced colours a `LinkText` outline marks it instead.
 
 Pressed (while the mouse button, a touch or the Space key holds it down): `primary` →
 `primary-pressed`; `tonal`, `outline` and `text` → `primary-soft-pressed` (the `text` label turns
-`primary-strong`); `danger` → `danger-pressed` with `danger-soft` text. `a[bfButton]` presses the
+`primary-strong`); `danger` → `danger-pressed` with `danger-soft` text; `ghost` →
+`surface-pressed` with `text`. `a[bfButton]` presses the
 same way. A disabled or loading button has no pressed state, and under forced colours the system
 colours win.
 
@@ -328,7 +383,7 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 `bf-button` renders a native `<button>`; its `type` reflects the `type` input. Native `disabled` is set only by `disabled`. While `loading`, the button stays focusable and in the tab order with `aria-disabled="true"` and `aria-busy="true"`, so focus does not fall to `<body>` when an action starts; a click or Enter/Space is cancelled (`preventDefault`) and emits nothing. The spinner inside is `decorative`, so it adds no second status announcement; announce the outcome in your own message. Being a real button, it gets keyboard activation (Enter/Space) and the button role for free — no ARIA role is added. The focus-visible ring uses the `ring` token.
 
-`a[bfButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): it is exposed as `link`, is in the tab order while it has an `href` (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), activates with Enter only, and opens in a new tab with Ctrl/Cmd-click. Use it whenever activation navigates to a URL, and `bf-button` whenever it performs an action on the page ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)). No ARIA is added, and none of `disabled`, `loading` or `type` applies.
+`a[bfButton]` is your own `<a>`, so it keeps the link role and link keyboard behaviour ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): it is exposed as `link`, is in the tab order while it has an `href` (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), activates with Enter only, and opens in a new tab with Ctrl/Cmd-click. Use it whenever activation navigates to a URL, and `bf-button` whenever it performs an action on the page ([APG button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)). No ARIA is added, and none of `disabled`, `loading` or `type` applies. The current page is the `aria-current="page"` you (or `routerLinkActive` with `ariaCurrentWhenActive`) set: screen readers announce it ("current page"), and the fill only mirrors it.
 
 ### Keyboard
 
@@ -340,14 +395,14 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 ## Inputs
 
-| Name        | Type                                                                          | Default     | Description                                                                                                                                                                                                  |
-| ----------- | ----------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `variant`   | `BfButtonVariant` (`'primary' \| 'tonal' \| 'outline' \| 'text' \| 'danger'`) | `'primary'` | Visual style: primary (filled), tonal (soft tint), outline, text, danger.                                                                                                                                    |
-| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                   | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                                                                   |
-| `type`      | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                            | `'button'`  | Native button type. Use `submit` inside a form. Ignored on `a[bfButton]`.                                                                                                                                    |
-| `disabled`  | `boolean`                                                                     | `false`     | Disables the control and swallows clicks. Ignored on `a[bfButton]`: a link is never disabled; render a disabled `bf-button` instead.                                                                         |
-| `loading`   | `boolean`                                                                     | `false`     | Shows a spinner instead of the start icon and blocks activation. The button stays focusable (`aria-disabled` and `aria-busy`, never native `disabled`) and keeps its variant fill. Ignored on `a[bfButton]`. |
-| `fullWidth` | `boolean`                                                                     | `false`     | Stretches the button to its container's width.                                                                                                                                                               |
+| Name        | Type                                                                                        | Default     | Description                                                                                                                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`   | `BfButtonAppearance` (`'primary' \| 'tonal' \| 'outline' \| 'text' \| 'danger' \| 'ghost'`) | `'primary'` | Visual style: primary (filled), tonal (soft tint), outline, text, danger, or ghost (quiet neutral). On `a[bfButton]`, `ghost`, `text` and `outline` also show `aria-current="page"`.                         |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                                 | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                                                                                   |
+| `type`      | `BfButtonType` (`'button' \| 'submit' \| 'reset'`)                                          | `'button'`  | Native button type. Use `submit` inside a form. Ignored on `a[bfButton]`.                                                                                                                                    |
+| `disabled`  | `boolean`                                                                                   | `false`     | Disables the control and swallows clicks. Ignored on `a[bfButton]`: a link is never disabled; render a disabled `bf-button` instead.                                                                         |
+| `loading`   | `boolean`                                                                                   | `false`     | Shows a spinner instead of the start icon and blocks activation. The button stays focusable (`aria-disabled` and `aria-busy`, never native `disabled`) and keeps its variant fill. Ignored on `a[bfButton]`. |
+| `fullWidth` | `boolean`                                                                                   | `false`     | Stretches the button to its container's width.                                                                                                                                                               |
 
 ## Outputs
 
@@ -368,10 +423,12 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 - Use `primary` once per screen for the main action; `tonal` for secondary actions next to it; `text` for low-emphasis actions inside cards and lists.
 - Bind `[loading]` to the pending state of the action so the user gets feedback and cannot double-submit.
 - Use `type="submit"` inside a `<form>` so Enter submits.
+- Build a top nav or a sidebar from `a[bfButton variant="ghost"]` with `routerLinkActive` and `ariaCurrentWhenActive="page"`.
 
 ### Don't
 
 - Don't nest `bf-button` in an `<a>` or another button, and don't navigate from `(clicked)`; put `bfButton` on the `<a>` itself (`<a bfButton routerLink="…">`).
+- Don't switch `[variant]` to mark the current page; set `aria-current="page"` and the link shows it.
 - Don't disable a link; render a disabled `bf-button` while the destination is unavailable.
 - Don't add `dark:` classes or colors on the element; the theme handles both.
 - Don't put a `bf-icon` in the default slot; use the `icon-start` / `icon-end` slots so spacing stays right.
@@ -379,6 +436,16 @@ Icon and label sit 8 px apart. A label longer than its container truncates with
 
 ## Migration notes
 
+### 0.3.1
+
+New `ghost` variant: quiet and neutral (`text-muted` label, no fill at rest, `surface-muted` on
+hover, `surface-pressed` on press), with the `text` variant's sizes, padding and disabled state,
+for secondary toolbar actions and navigation rows. `a[bfButton]` with `aria-current="page"` shows
+the current page: `ghost` and `text` links take the tonal fill, `outline` a primary border, so a
+top nav built with `routerLinkActive` and `ariaCurrentWhenActive="page"` needs no `[variant]`
+switch. `variant` is now typed `BfButtonAppearance` (the five `BfButtonVariant` styles plus
+`ghost`); `BfButtonVariant` keeps its five members, so code that maps over it keeps compiling.
+
 ### 0.3.0
 
 **Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`

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

@@ -148,6 +148,60 @@ import { BfCardComponent } from '@bitforgehq/ui';
 export class CardVariantsExampleComponent {}
 ```
 
+## 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,14 +306,15 @@ 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
@@ -271,6 +326,12 @@ The card renders a plain `<div>` with no role. A clickable card follows the stre
 
 ## Migration notes
 
+### 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`).