@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/tooltip.md

@@ -0,0 +1,230 @@
+# bf-tooltip
+
+Short hint beside a control on hover or keyboard focus, for desktop
+
+`BfTooltipComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfTooltipDirective } from '@bitforgehq/ui/overlay';
+import { Bold, Italic, Link, Underline } from 'lucide';
+
+/**
+ * The bf-tooltip overview.
+ *
+ * Live demo of `bfTooltip`: a formatting toolbar of icon buttons, each named by its `label` and
+ * showing the same name, with its keyboard shortcut, in a tooltip on hover or keyboard focus. The
+ * result line reports each press.
+ */
+@Component({
+  selector: 'app-example-tooltip-overview',
+  imports: [BfIconButtonComponent, BfIconComponent, BfTooltipDirective],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div role="group" aria-label="Formatting" class="flex flex-wrap items-center gap-2">
+        <bf-icon-button
+          label="Bold"
+          variant="text"
+          bfTooltip="Bold (Ctrl+B)"
+          (clicked)="press('Bold')"
+        >
+          <bf-icon [icon]="bold" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Italic"
+          variant="text"
+          bfTooltip="Italic (Ctrl+I)"
+          (clicked)="press('Italic')"
+        >
+          <bf-icon [icon]="italic" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Underline"
+          variant="text"
+          bfTooltip="Underline (Ctrl+U)"
+          (clicked)="press('Underline')"
+        >
+          <bf-icon [icon]="underline" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Insert link"
+          variant="text"
+          bfTooltip="Insert link (Ctrl+K)"
+          (clicked)="press('Insert link')"
+        >
+          <bf-icon [icon]="link" />
+        </bf-icon-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TooltipOverviewExampleComponent {
+  readonly bold = Bold;
+  readonly italic = Italic;
+  readonly underline = Underline;
+  readonly link = Link;
+  readonly status = signal('Hover or tab to a button for its tooltip.');
+
+  press(label: string): void {
+    this.status.set(`Pressed ${label}.`);
+  }
+}
+```
+
+## Overview
+
+The small dark pill of a tooltip (role `tooltip`). A `[bfTooltip]` directive renders it in the
+CDK overlay beside its element while the pointer rests on it or it has keyboard focus, so you
+rarely place it yourself; the directive is how you add a tooltip.
+
+Short hints for desktop and web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). Put `bfTooltip="Text"` on a control and a small dark `bf-tooltip` pill shows beside it
+when a mouse rests on it for half a second, or at once when it gets keyboard focus. It hides when
+the pointer leaves, on blur and on `Escape`. While it shows, the control is described by it
+(`aria-describedby`), so a screen reader reads the hint after the control's name. The pill
+renders in the CDK overlay container, so it works inside a `BfDialogService` dialog.
+
+Import `BfTooltipDirective` from `@bitforgehq/ui/overlay`. You rarely place `bf-tooltip`
+(`BfTooltipComponent`) yourself: the directive renders it.
+
+## When to use
+
+Use a tooltip to repeat the name of an icon-only control (`bf-icon-button`, a collapsed sidebar
+link) for mouse users, or to add a keyboard shortcut to it. A tooltip never holds information
+found nowhere else: touch screens never show it, so the control's own name and the page must say
+everything that matters. Use [bf-popover](https://bitforge-ui.web.app/components/popover) instead for content a user reads at
+length or interacts with (links, fields, buttons), [bf-field](https://bitforge-ui.web.app/components/field) help text for
+guidance on a form field, and in a Capacitor app the control's visible label.
+
+## Placement
+
+`bfTooltipPlacement` puts the tooltip on the `top` (default), `bottom`, `start` or `end` side of
+its element, centred along it, 8 px away. `start` and `end` follow the text direction, so they
+swap sides in right-to-left pages. A tooltip without room on its side flips to the opposite side
+first, then to the other two. The placement is read each time the tooltip shows.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfTooltipDirective, type BfTooltipPlacement } from '@bitforgehq/ui/overlay';
+
+/**
+ * Tooltips on each side of their button.
+ *
+ * `bfTooltipPlacement` puts the tooltip on the `top` (default), `bottom`, `start` or `end` side;
+ * `start` and `end` follow the text direction, and a tooltip without room flips to the other side.
+ */
+@Component({
+  selector: 'app-example-tooltip-placement',
+  imports: [BfButtonComponent, BfTooltipDirective],
+  template: `
+    <div class="flex flex-wrap items-center justify-center gap-3 py-8">
+      @for (side of sides; track side) {
+        <bf-button
+          variant="outline"
+          size="sm"
+          [bfTooltip]="'Shown on the ' + side + ' side'"
+          [bfTooltipPlacement]="side"
+        >
+          {{ side }}
+        </bf-button>
+      }
+    </div>
+  `,
+})
+export class TooltipPlacementExampleComponent {
+  protected readonly sides: readonly BfTooltipPlacement[] = ['top', 'bottom', 'start', 'end'];
+}
+```
+
+## Text
+
+Keep the text to a few words on one line: the name of the control, and maybe its shortcut
+("Bold (Ctrl+B)"). Longer text wraps at 20 rem. A bound text that changes while the tooltip shows
+("Copy link", then "Copied") updates it in place; an empty text shows no tooltip.
+
+On an icon-only `bf-icon-button` the tooltip repeats its `label`: the `label` stays the accessible
+name, and the tooltip describes the button. A collapsed `bf-sidebar` link (`a[bfNavItem]`) shows
+its name in the browser's `title` tooltip; add `bfTooltip` with the same text and
+`bfTooltipPlacement="end"` for a styled one that also shows on keyboard focus. Bind it to an empty
+text while the sidebar is expanded, where the label is visible.
+
+## Desktop
+
+Built for a mouse and a keyboard. Hovering shows the tooltip after a 500 ms rest, so a pointer
+that only passes over a toolbar shows nothing; moving the pointer from the control onto the
+tooltip keeps it open (so it can be read under a magnifier). Keyboard focus (`focus-visible`)
+shows it at once; a mouse click that focuses the control does not. The tooltip fades in over
+120 ms, without the fade when the system asks for reduced motion.
+
+Under a coarse pointer (`(pointer: coarse)`, touch screens and the Capacitor shell) no tooltip
+ever shows: there is no hover there, and a tooltip after a tap would sit under the finger. That
+is why a tooltip never carries information found nowhere else.
+
+## Theming
+
+- Pill: `bg-tooltip` with `text-on-tooltip` (14.9:1 in light, 13.8:1 in dark; the pill is dark
+  on a light page and light on a dark one), `rounded-field`, `shadow-raised`, `text-label-xs`,
+  10 px by 4 px padding, at most 20 rem wide.
+- Under forced colours (Windows High Contrast) the pill drops its fill and draws a 1 px border in
+  the text colour.
+
+## Accessibility
+
+- The pill is `role="tooltip"` with an id. While it shows, the control (the host, or the first
+  control inside it, such as the button of a `bf-icon-button`) gets that id added to its
+  `aria-describedby`, next to any ids it already has; the id is removed when the tooltip hides.
+- A tooltip is a description, never the name: an icon-only button keeps its `label` or
+  `aria-label`.
+- WCAG 1.4.13 (content on hover or focus): the tooltip can be dismissed with `Escape` without
+  moving the pointer or focus, stays while the pointer is over it, and stays until the pointer
+  leaves, focus leaves or `Escape` is pressed.
+- `Escape` goes to the tooltip first: inside a dialog or a popover, the first `Escape` hides the
+  tooltip and the next one closes the dialog.
+- A disabled native button fires no pointer events, so its tooltip never shows; explain why a
+  control is disabled in the page instead.
+
+### Keyboard
+
+| Key                                              | Action                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Focusing the control shows its tooltip; leaving hides it |
+| <kbd>Escape</kbd>                                | Hides the tooltip, focus stays where it is               |
+
+## Inputs
+
+| Name   | Type     | Default | Description                                                                |
+| ------ | -------- | ------- | -------------------------------------------------------------------------- |
+| `text` | `string` | `''`    | The tooltip's text: a few words that repeat or explain the control's name. |
+
+## Notes
+
+### Do
+
+- Repeat the name of icon-only controls, and add their keyboard shortcut.
+- Keep the text to a few words.
+- Put tooltips on controls that take focus, so keyboard users get them too.
+
+### Don't
+
+- Don't put information only in a tooltip: touch screens never show it.
+- Don't put links, buttons or other controls in a tooltip; use a popover.
+- Don't use a tooltip as the accessible name of a control.
+- Don't add a tooltip that repeats a visible text label word for word.
+
+## Migration notes
+
+### 0.3.1
+
+New `[bfTooltip]` (`BfTooltipDirective`) and its `bf-tooltip` pill (`BfTooltipComponent`) in
+`@bitforgehq/ui/overlay`: a short hint beside a control after a 500 ms hover or at once on keyboard
+focus, hidden on leave, blur and `Escape`, and kept while the pointer moves onto it (WCAG 1.4.13).
+`bfTooltipPlacement` (`BfTooltipPlacement`: `top` default, `bottom`, `start`, `end`, logical)
+flips when it would overflow. While it shows, the control is described by it
+(`aria-describedby`). Nothing shows under a coarse pointer. Fades in over 120 ms, not under
+reduced motion. New `BfTooltipHarness` in `@bitforgehq/ui/testing`.

package/ai/components/top-nav.md

@@ -0,0 +1,159 @@
+# bf-top-nav
+
+Horizontal app navigation, a wrapping row of links for apps with few sections
+
+`BfTopNavComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-top-nav overview.
+ *
+ * Live demo of `bf-top-nav`: a row of `a[bfNavItem]` router links for an app with few sections.
+ * This page is the current one; in a narrow container the row wraps onto more lines.
+ */
+@Component({
+  selector: 'app-example-top-nav-overview',
+  imports: [RouterLink, RouterLinkActive, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Desktop navigation">
+      @for (link of links; track link.path) {
+        <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">{{
+          link.label
+        }}</a>
+      }
+    </bf-top-nav>
+  `,
+})
+export class TopNavOverviewExampleComponent {
+  protected readonly links: readonly { path: string; label: string }[] = [
+    { path: '/components/sidebar', label: 'Sidebar' },
+    { path: '/components/top-nav', label: 'Top nav' },
+    { path: '/components/nav-item', label: 'Nav item' },
+    { path: '/components/nav-group', label: 'Nav group' },
+  ];
+}
+```
+
+## Overview
+
+The horizontal navigation of a desktop app with few sections: a `nav` landmark holding a row
+of `a[bfNavItem]` links that wraps onto more lines in a narrow container. Each link marks the
+current page from `aria-current="page"`, as in `bf-sidebar`.
+
+The horizontal navigation of a desktop web app with few sections: a `nav` landmark holding a row of [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links, usually in the app's header bar. In a narrow container the row wraps onto more lines. It shares its item with [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar), so the current page, the count badge and the focus ring look the same in both.
+
+## When to use
+
+Use `bf-top-nav` for the two to five top-level destinations of a desktop web app. Use [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) instead for more sections or sections in groups, and [bf-segmented](https://bitforge-ui.web.app/components/segmented) to switch a view in place. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) instead.
+
+## Basic usage
+
+Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActive="page">`: the router sets `aria-current="page"` on the current page's link and the item shows it in the tonal fill. Items lay out inline at their own width; an icon in `bfSlot="icon"` and a `badge` work as in the sidebar. Name the landmark with `label` (it falls back to `provideBfLabels()`'s `navigation`, "Main").
+
+## Icons and badges
+
+An icon in `bfSlot="icon"` sits before the label and `badge` adds a count pill, announced as "4 new", as in the sidebar.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ChartColumn, Inbox, LayoutDashboard } from 'lucide';
+
+/**
+ * Icons and a count badge in a top nav.
+ *
+ * Each `a[bfNavItem]` takes an icon in `bfSlot="icon"` and a `badge`, as in the sidebar.
+ */
+@Component({
+  selector: 'app-example-top-nav-icons',
+  imports: [RouterLink, RouterLinkActive, BfIconComponent, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Sections with icons">
+      <a bfNavItem routerLink="/components/top-nav" routerLinkActive ariaCurrentWhenActive="page">
+        <bf-icon bfSlot="icon" [icon]="dashboard" />
+        Overview
+      </a>
+      <a
+        bfNavItem
+        routerLink="/components/badge"
+        routerLinkActive
+        ariaCurrentWhenActive="page"
+        [badge]="4"
+      >
+        <bf-icon bfSlot="icon" [icon]="inbox" />
+        Inbox
+      </a>
+      <a bfNavItem routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+        <bf-icon bfSlot="icon" [icon]="chart" />
+        Reports
+      </a>
+    </bf-top-nav>
+  `,
+})
+export class TopNavIconsExampleComponent {
+  protected readonly dashboard = LayoutDashboard;
+  protected readonly inbox = Inbox;
+  protected readonly chart = ChartColumn;
+}
+```
+
+## Small screens
+
+The row wraps rather than scrolling sideways. When it would wrap onto too many lines, drive a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` links below a breakpoint from the same array (`class="hidden md:block"` on `bf-top-nav`, `class="md:hidden"` on the menu button), as the [sidebar's responsive layout](https://bitforge-ui.web.app/components/sidebar) shows.
+
+## Desktop
+
+The top nav is a desktop pattern. Its items take a `surface-muted` fill and the pointer on hover, a `surface-pressed` fill while pressed and the focus ring on keyboard focus only; the current page keeps its tonal fill with its own hover and pressed steps. Item height follows `provideBfDefaults()` (`controlSize`); under a coarse pointer every item is at least 44 px tall. Ctrl/Cmd-click and a middle click open a link in a new tab.
+
+## Theming
+
+- Layout: `flex flex-wrap` with a 4 px gap; no surface of its own, so it sits on the header bar or page behind it.
+- The items' tokens are on the [nav item](https://bitforge-ui.web.app/components/nav-item#theming) page.
+
+## Accessibility
+
+`bf-top-nav` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. Its links are plain `<a>` elements in DOM order; the current page is the one with `aria-current="page"`, which screen readers announce ("current page") and which an outline marks under forced colours.
+
+### Keyboard
+
+| Key                                              | Action                   |
+| ------------------------------------------------ | ------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the links  |
+| <kbd>Enter</kbd>                                 | Follows the focused link |
+
+## Inputs
+
+| Name    | Type     | Default | Description                                                                                                                                                       |
+| ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label` | `string` | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one. |
+
+## Slots
+
+- `default`: The destinations, `a[bfNavItem]` links.
+
+## Notes
+
+### Do
+
+- Keep it to a few short labels that fit one line at the usual window width.
+- Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"`.
+
+### Don't
+
+- Don't put more than five or six destinations in it; use a `bf-sidebar`.
+- Don't use it to switch a view inside a page; use a `bf-segmented`.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-top-nav`: the horizontal navigation of a desktop app with few sections, a `nav` row of
+`a[bfNavItem]` links that wraps in a narrow container, named by `label` (else `navigation`).

package/ai/reference/bf-app-frame-breakpoint.md

@@ -0,0 +1,27 @@
+# BfAppFrameBreakpoint
+
+The breakpoint where an app frame switches from its header bar to the sidebar
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The viewport width from which `bf-app-frame` shows its sidebar column instead of the narrow
+header bar: Tailwind's `md` (768 px) or `lg` (1024 px).
+
+```ts
+import { type BfAppFrameBreakpoint } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameBreakpoint = 'md' | 'lg'
+```
+
+## Values
+
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)

package/ai/reference/bf-app-frame-content-width.md

@@ -0,0 +1,29 @@
+# BfAppFrameContentWidth
+
+The maximum width of an app frame's content column, from medium to full
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The maximum width of `bf-app-frame`'s content column: `md` 48rem, `lg` 64rem, `xl` 80rem, or
+`full` for no limit.
+
+```ts
+import { type BfAppFrameContentWidth } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameContentWidth = 'md' | 'lg' | 'xl' | 'full'
+```
+
+## Values
+
+- `md`
+- `lg`
+- `xl`
+- `full`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)

package/ai/reference/bf-badge-appearance.md

@@ -0,0 +1,36 @@
+# BfBadgeAppearance
+
+Every badge tone, the five variants plus the informational info tone
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Every tone the `variant` input of a `bf-badge` takes: the five `BfBadgeVariant` tones plus
+`info`, for an informational label such as a category. A new type, so `Record`s and exhaustive
+switches over `BfBadgeVariant` keep compiling.
+
+```ts
+import { type BfBadgeAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeAppearance = BfBadgeVariant | 'info'
+```
+
+## Values
+
+- `neutral`
+- `primary`
+- `success`
+- `warning`
+- `danger`
+- `info`
+
+## Uses
+
+- [BfBadgeVariant](bf-badge-variant.md)
+
+## Used by
+
+- [bf-badge](../components/badge.md)

package/ai/reference/bf-badge-variant.md

@@ -26,4 +26,4 @@ type BfBadgeVariant = 'neutral' | 'primary' | 'success' | 'warning' | 'danger'
 
 ## Used by
 
-- [bf-badge](../components/badge.md)
+- [BfBadgeAppearance](bf-badge-appearance.md)

package/ai/reference/bf-bar-chart-orientation.md

@@ -0,0 +1,27 @@
+# BfBarChartOrientation
+
+The two bar directions, vertical columns or horizontal bars
+
+Type from `@bitforgehq/ui/charts` · since 0.3.1
+
+The direction of a `bf-bar-chart`'s bars: up from a horizontal baseline, or along from a
+vertical one (for long category names or many categories).
+
+```ts
+import { type BfBarChartOrientation } from '@bitforgehq/ui/charts';
+```
+
+## Signature
+
+```ts
+type BfBarChartOrientation = 'vertical' | 'horizontal'
+```
+
+## Values
+
+- `vertical`
+- `horizontal`
+
+## Used by
+
+- [bf-bar-chart](../components/bar-chart.md)

package/ai/reference/bf-button-appearance.md

@@ -0,0 +1,36 @@
+# BfButtonAppearance
+
+Every button style, the five variants plus the quiet neutral ghost
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Every value the `variant` input of a `bf-button` takes: the five `BfButtonVariant` styles plus
+`ghost`, the quiet neutral one. A new type, so `Record`s and exhaustive switches over
+`BfButtonVariant` keep compiling.
+
+```ts
+import { type BfButtonAppearance } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfButtonAppearance = BfButtonVariant | 'ghost'
+```
+
+## Values
+
+- `primary`
+- `tonal`
+- `outline`
+- `text`
+- `danger`
+- `ghost`
+
+## Uses
+
+- [BfButtonVariant](bf-button-variant.md)
+
+## Used by
+
+- [bf-button](../components/button.md)

package/ai/reference/bf-button-variant.md

@@ -26,4 +26,4 @@ type BfButtonVariant = 'primary' | 'tonal' | 'outline' | 'text' | 'danger'
 
 ## Used by
 
-- [bf-button](../components/button.md)
+- [BfButtonAppearance](bf-button-appearance.md)

package/ai/reference/bf-calendar-disabled-date.md

@@ -0,0 +1,23 @@
+# BfCalendarDisabledDate
+
+A function that marks an ISO date as not pickable in a calendar
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+Tells `bf-calendar` which dates cannot be picked, such as weekends or booked days.
+
+```ts
+import { type BfCalendarDisabledDate } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCalendarDisabledDate = (iso: string) => boolean
+```
+
+## Used by
+
+- [bf-calendar](../components/calendar.md)
+- [bf-date-input](../components/date-input.md)
+- [bf-datetime-input](../components/datetime-input.md)

package/ai/reference/bf-calendar-harness.md

@@ -0,0 +1,51 @@
+# BfCalendarHarness
+
+Test harness for the calendar: reads the month and picks a date by ISO string
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-calendar`. It works with ISO dates ('YYYY-MM-DD'), as the calendar's value
+does, and drives it as a user would: `selectDate()` jumps to another month through the month
+and year views, then clicks the day.
+
+```ts
+import { BfCalendarHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfCalendarHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The calendar's accessible name (`label`, else `ariaLabel`); it is not rendered visibly.
+
+### `getMonthLabel(): Promise<string>`
+
+The shown month and year as the header writes them, in the calendar's locale.
+
+### `getSelected(): Promise<string | null>`
+
+The picked date while it is in the shown month.
+
+### `nextMonth(): Promise<void>`
+
+Clicks the next-month button. Throws when it is disabled (the month is past `max`).
+
+### `previousMonth(): Promise<void>`
+
+Clicks the previous-month button. Throws when it is disabled (the month is before `min`).
+
+### `selectDate(iso: string): Promise<void>`
+
+Picks a date as a user would: when it is in another month, opens the month view, then the
+year view, clicks its year and month, then clicks the day. Throws for an invalid date, one
+the views do not list, and a disabled date or calendar.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |

package/ai/reference/bf-calendar-weekday.md

@@ -0,0 +1,31 @@
+# BfCalendarWeekday
+
+A weekday number from 0 for Sunday to 6 for Saturday, as Date counts
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+A weekday as `Date.getDay()` counts it: 0 Sunday, 1 Monday … 6 Saturday.
+
+```ts
+import { type BfCalendarWeekday } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfCalendarWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6
+```
+
+## Values
+
+- `0`
+- `1`
+- `2`
+- `3`
+- `4`
+- `5`
+- `6`
+
+## Used by
+
+- [bf-calendar](../components/calendar.md)