@bitforgehq/ui 0.3.0

package/ai/components/select.md

@@ -0,0 +1,510 @@
+# bf-select
+
+Native single-choice dropdown styled like the text field, with Signal Forms binding
+
+`BfSelectComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfButtonComponent, BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/**
+ * The bf-select overview.
+ *
+ * Live demo of `bf-select`: a placeholder option and three real options, bound to a signal, with a
+ * number-valued team select and a Clear button that sets `null`; then the sm, md and lg sizes in a
+ * row.
+ */
+@Component({
+  selector: 'app-example-select-overview',
+  imports: [BfButtonComponent, BfSelectComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-select
+        label="Region"
+        placeholder="Pick a region"
+        [options]="regions"
+        [(value)]="region"
+      />
+      <div class="flex flex-wrap items-end gap-3">
+        <bf-select
+          label="Team"
+          placeholder="Pick a team"
+          class="w-56"
+          [options]="teams"
+          [(value)]="teamId"
+        />
+        <bf-button variant="outline" (click)="teamId.set(null)">Clear</bf-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-select
+          size="sm"
+          ariaLabel="Small select"
+          placeholder="sm · 32 px"
+          [options]="regions"
+          class="w-40"
+        />
+        <bf-select
+          ariaLabel="Medium select"
+          placeholder="md · 40 px"
+          [options]="regions"
+          class="w-40"
+        />
+        <bf-select
+          size="lg"
+          ariaLabel="Large select"
+          placeholder="lg · 48 px"
+          [options]="regions"
+          class="w-40"
+        />
+      </div>
+    </div>
+  `,
+})
+export class SelectOverviewExampleComponent {
+  readonly regions: BfSelectOption[] = [
+    { value: 'ch', label: 'Switzerland' },
+    { value: 'de', label: 'Germany' },
+    { value: 'fr', label: 'France' },
+  ];
+  readonly region = signal<string | null>(null);
+  /** Numeric ids: the value is a `number`, `null` while nothing is picked. */
+  readonly teams: BfSelectOption<number>[] = [
+    { value: 7, label: 'Design' },
+    { value: 42, label: 'Platform' },
+  ];
+  readonly teamId = signal<number | null>(null);
+
+  readonly status = computed(() => {
+    const region = this.regions.find((r) => r.value === this.region());
+    const team = this.teamId();
+    return [
+      region ? `Region: ${region.label}` : 'No region picked.',
+      team === null ? 'No team (null).' : `Team id: ${team}.`,
+    ].join(' ');
+  });
+}
+```
+
+## Overview
+
+Native single-choice dropdown styled like the text field, with a placeholder option and
+Signal Forms binding. Generic over the option value (a string by default); `null` means nothing
+is selected.
+
+A single-choice dropdown built on the native `<select>`, so it opens the platform picker on phones and stays keyboard-accessible everywhere. Styled like the text field with a CSS chevron.
+
+## When to use
+
+Use `bf-select` to choose one value from a list too long to show at once: a country, a project, a time zone. Use [bf-radio-group](https://bitforge-ui.web.app/components/radio-group) instead for up to five or six options that should be read side by side, [bf-segmented](https://bitforge-ui.web.app/components/segmented) for two to four options that switch a view, and [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) for actions rather than a value.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** A select of projects with a placeholder until one is picked. */
+@Component({
+  selector: 'app-example-select-basic',
+  imports: [BfSelectComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-select
+        label="Project"
+        placeholder="Pick a project"
+        [options]="projects"
+        [(value)]="projectId"
+      />
+      <p class="text-caption text-text-muted">projectId: {{ projectId() ?? 'null' }}</p>
+    </div>
+  `,
+})
+export class SelectBasicExampleComponent {
+  readonly projects: BfSelectOption[] = [
+    { value: 'atlas', label: 'Atlas rebrand' },
+    { value: 'bloom', label: 'Bloom app' },
+  ];
+  readonly projectId = signal<string | null>(null);
+}
+```
+
+`value` is `null` while nothing is selected, and the placeholder shows then. `(changed)` emits the
+chosen value (never `null`) after a user change.
+
+## Typed values
+
+The select is generic over the option value: numbers, ids and objects bind directly, with no
+string conversion. `BfSelectOption` defaults to `string`; type it for anything else, and bind a
+`T | null` signal or form field.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** A select of numeric team ids: the bound value is a `number | null`. */
+@Component({
+  selector: 'app-example-select-typed',
+  imports: [BfSelectComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-select label="Team" placeholder="Pick a team" [options]="teams" [(value)]="teamId" />
+      <p class="text-caption text-text-muted">teamId: {{ teamId() ?? 'null' }}</p>
+    </div>
+  `,
+})
+export class SelectTypedExampleComponent {
+  readonly teams: BfSelectOption<number>[] = [
+    { value: 7, label: 'Design' },
+    { value: 42, label: 'Platform' },
+  ];
+  readonly teamId = signal<number | null>(null);
+}
+```
+
+Options are matched to `value` with `Object.is`. For object values that are equal but not the same
+instance (reloaded from a server), pass `compareWith`:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+interface Team {
+  id: number;
+  name: string;
+}
+
+/**
+ * A select of objects matched by id.
+ *
+ * The form's team is an equal object, not the option's instance (as after a reload), so
+ * `compareWith` matches by `id`.
+ */
+@Component({
+  selector: 'app-example-select-compare-with',
+  imports: [FormField, BfSelectComponent],
+  template: `
+    <bf-select label="Team" [options]="teamOptions" [compareWith]="byId" [formField]="task.team" />
+  `,
+})
+export class SelectCompareWithExampleComponent {
+  protected readonly teamOptions: BfSelectOption<Team>[] = [
+    { value: { id: 7, name: 'Design' }, label: 'Design' },
+    { value: { id: 42, name: 'Platform' }, label: 'Platform' },
+  ];
+  readonly byId = (a: Team, b: Team) => a.id === b.id;
+  private readonly model = signal<{ team: Team | null }>({ team: { id: 42, name: 'Platform' } });
+  protected readonly task = form(this.model);
+}
+```
+
+`compareWith` is called as `compareWith(optionValue, value)`. A string, number or boolean option
+value is also the native `<option value>` (`"42"` for `42`), so a native form post and browser
+tests (`selectOption('42')`) see it; an object option's native value is its index. A choice is
+mapped back by position, so the model always gets the option's real value. An option whose value is `null` is not supported: `null` means nothing is selected, so such an
+option never shows as selected.
+
+Migrating from 0.2: "nothing selected" is `null` (it was `''`). Type bound signals and fields
+`T | null` and compare against `null`, or listen to `(changed)`; an option whose value is `''`
+(e.g. "All") is now a real option.
+
+## With Signal Forms
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** A select bound to a Signal Forms field. */
+@Component({
+  selector: 'app-example-select-signal-forms',
+  imports: [FormField, BfSelectComponent],
+  template: `<bf-select label="Region" [options]="regions" [formField]="profile.region" />`,
+})
+export class SelectSignalFormsExampleComponent {
+  protected readonly regions: BfSelectOption[] = [
+    { value: 'eu', label: 'Europe' },
+    { value: 'us', label: 'Americas' },
+  ];
+  private readonly model = signal<{ region: string | null }>({ region: 'eu' });
+  protected readonly profile = form(this.model);
+}
+```
+
+Model the field as `T | null`, starting at `null`; `required()` treats `null` as empty. With
+Reactive Forms, bind a `FormControl<T | null>` through `[formControl]` or `formControlName`.
+
+## Read-only
+
+`readonly` shows the chosen option on the muted surface and blocks changes. A mouse press focuses
+the select without opening the picker, and the picker keys (arrows, Alt+Arrow, Enter, Space, F4,
+type-ahead) do nothing. On touch screens the platform picker can still open, because the browser
+gives no press to cancel; a choice made there snaps back to the bound value, so the value never
+changes. The select stays in the tab order. Signal Forms binds it from `readonly()` rules.
+
+```ts
+import { Component } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** A read-only select. */
+@Component({
+  selector: 'app-example-select-readonly',
+  imports: [BfSelectComponent],
+  template: `<bf-select label="Region" [options]="regions" [readonly]="true" [value]="region" />`,
+})
+export class SelectReadonlyExampleComponent {
+  protected readonly regions: BfSelectOption[] = [
+    { value: 'eu', label: 'Europe' },
+    { value: 'us', label: 'Americas' },
+  ];
+  protected readonly region = 'us';
+}
+```
+
+## Without a visible label
+
+A table filter or a toolbar select can skip the visible `label`; give it `ariaLabel`, or
+`ariaLabelledby` pointing at the element that names it. A select without a visible label needs one
+of the two. Both are ignored while `label` is set.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** A small toolbar select named by `ariaLabel`. */
+@Component({
+  selector: 'app-example-select-unlabelled',
+  imports: [BfSelectComponent],
+  template: `
+    <bf-select ariaLabel="Filter by status" size="sm" [options]="statuses" [(value)]="status" />
+  `,
+})
+export class SelectUnlabelledExampleComponent {
+  protected readonly statuses: BfSelectOption[] = [
+    { value: 'all', label: 'All' },
+    { value: 'open', label: 'Open' },
+  ];
+  protected readonly status = signal<string | null>('all');
+}
+```
+
+## Sizes
+
+`sm` 32 px, `md` 40 px (default), `lg` 48 px — the `BfSize` scale shared with `bf-input`, `bf-button`, `bf-chip` and `bf-segmented`, so a toolbar of one step has one height. Unset, `size` follows `provideBfDefaults()`'s `fieldSize`, `md` by default; a Capacitor app sets `provideBfDefaults({ fieldSize: 'lg' })` once for the 48 px phone look, and a dense sub-tree (a filter bar, a table) can set `{ size: 'sm' }` in a component's `providers`. Fields get no touch extension: `sm`/`md` fields stay 32/40 px under a coarse pointer, so touch apps use `provideBfDefaults({ fieldSize: 'lg' })`. The chevron sits at the inline end (left under `dir="rtl"`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/** The sm, md and lg select sizes. */
+@Component({
+  selector: 'app-example-select-sizes',
+  imports: [BfSelectComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-select size="sm" ariaLabel="Status" [options]="statuses" [(value)]="status" />
+      <bf-select label="Project" [options]="projects" [(value)]="projectId" />
+      <bf-select size="lg" label="Region" [options]="regions" [(value)]="region" />
+    </div>
+  `,
+})
+export class SelectSizesExampleComponent {
+  protected readonly statuses: BfSelectOption[] = [{ value: 'open', label: 'Open' }];
+  protected readonly projects: BfSelectOption[] = [{ value: 'atlas', label: 'Atlas rebrand' }];
+  protected readonly regions: BfSelectOption[] = [{ value: 'eu', label: 'Europe' }];
+  protected readonly status = signal<string | null>('open');
+  protected readonly projectId = signal<string | null>('atlas');
+  protected readonly region = signal<string | null>('eu');
+}
+```
+
+## Validation
+
+Once the control is touched it shows the first error as text: the error's own `message`, else the default for its kind from `provideBfLabels()`'s `validation` labels (`required` "Fill in this field", `email`, `pattern`, `parse`, `min(n)`, `max(n)`, `minLength(n)` "Use at least n characters", `maxLength(n)`, `minDate(d)`, `maxDate(d)`, and `fallback` "Check this value" for any other kind), so it never turns red without text. Reactive Forms `Validators.*` errors carry no message and get the same defaults (`minlength`/`maxlength` read their limit from the error's `context`). An explicit `errorMessage` wins over both and shows at once, e.g. for a server error.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, required } from '@angular/forms/signals';
+import { BfButtonComponent, BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+
+/**
+ * A required select with the default message.
+ *
+ * `required(p.region)` has no message, so a submit with nothing chosen shows "Fill in this field".
+ */
+@Component({
+  selector: 'app-example-select-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfSelectComponent],
+  template: `
+    <form [formRoot]="profile" class="flex flex-col items-start gap-3">
+      <bf-select
+        label="Region"
+        class="self-stretch"
+        [options]="options"
+        [formField]="profile.region"
+      />
+      <bf-button type="submit">Save</bf-button>
+    </form>
+  `,
+})
+export class SelectValidationExampleComponent {
+  protected readonly options: BfSelectOption[] = [
+    { value: 'eu', label: 'Europe' },
+    { value: 'us', label: 'Americas' },
+  ];
+  private readonly model = signal<{ region: string | null }>({ region: null });
+  protected readonly profile = form(
+    this.model,
+    (p) => {
+      required(p.region);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+Hover darkens the border (`text-muted`, `danger` in the error state) with the pointer cursor; a read-only select keeps the default cursor. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The `primary` border and the focus ring show on every focus, as on the text fields. The picker is the browser's own list, so it matches the operating system. Fields default to `md` (40 px); `provideBfDefaults({ fieldSize: 'sm' })` gives 32 px selects for toolbars and filter bars ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Border: `border-strong` (the control boundary, ≥ 3:1), switching to `danger-border` on error; focus: `primary` border with a `ring` ring.
+- Hover (pointer cursor): border `text-muted`, or `danger` in the error state.
+- Disabled: `surface-sunken` border, `surface-muted` background, `text-disabled` text. Read-only: `surface-muted` background, default cursor. Placeholder text: `text-muted` (≥ 4.5:1). Chevron: `text-subtle`.
+- Label, help and error text come from the `bf-field` wrapper (see its Theming section).
+
+## Accessibility
+
+Native `<select>`, so it opens the platform's own picker on phones and stays fully keyboard-operable. `bf-field` renders the `<label for>`; the select itself wires `aria-describedby` to the help paragraph and the error paragraph under it (both while shown, help first) and, while it is invalid, `aria-errormessage` to the error paragraph; `aria-invalid` is set once touched and invalid (an explicit `errorMessage` shows immediately). The `placeholder`, when set, is a disabled option so it can be shown but never chosen. `aria-label` and `aria-labelledby` carry `ariaLabel` and `ariaLabelledby` only while there is no visible `label`. Read-only: `aria-readonly="true"`, the select stays focusable, a mouse press focuses it without opening the picker, the picker keys (arrows, Alt+Arrow, Enter, Space, F4, type-ahead) are blocked, and a change that still gets through (the platform picker on touch screens) is reverted, so the value never changes. `focus()` focuses the native select; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+The select is a native `<select>`, so these are the browser's keys and differ slightly between operating systems. While `readonly`, the picker and type-ahead keys are blocked; <kbd>Tab</kbd> and <kbd>Escape</kbd> still work.
+
+| Key                                                  | Action                                                                                                                                                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>     | Moves focus to and from the select; a `readonly` one stays in the tab order                                                                                              |
+| <kbd>Space</kbd>                                     | Opens the picker                                                                                                                                                         |
+| <kbd>Alt</kbd>+<kbd>ArrowDown</kbd> / <kbd>F4</kbd>  | Opens the picker on Windows and Linux                                                                                                                                    |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>            | Closed: chooses the previous / next option on Windows and Linux (<kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> too), opens the picker on macOS; open: moves the highlight |
+| <kbd>Home</kbd> / <kbd>End</kbd>                     | Closed on Windows and Linux: chooses the first / last option; open: highlights the first / last option                                                                   |
+| <kbd>PageUp</kbd> / <kbd>PageDown</kbd>              | Moves several options up / down (to the first / last in a short list)                                                                                                    |
+| <kbd>Enter</kbd>                                     | In the open picker: chooses the highlighted option                                                                                                                       |
+| <kbd>Escape</kbd>                                    | Closes the open picker without changing the value                                                                                                                        |
+| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd> | Type-ahead: moves to the next option whose label starts with the typed text                                                                                              |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                |
+| ---------------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `options`        | `readonly BfSelectOption<T>[]`                              | required    | The options to choose from.                                                                                                                |
+| `compareWith`    | `BfCompareWith<T>`                                          | `Object.is` | Equality for matching `value` to an option (default `Object.is`); pass one for object values.                                              |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                   |
+| `label`          | `string`                                                    | `''`        | Visible label above the control.                                                                                                           |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when no visible label is rendered (e.g. a table filter). Ignored when `label` is set.                                      |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                |
+| `placeholder`    | `string`                                                    | `''`        | Disabled first option shown while nothing is selected.                                                                                     |
+| `helpText`       | `string`                                                    | `''`        | Helper text under the control.                                                                                                             |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                            |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                       |
+| `readonly`       | `boolean`                                                   | `false`     | Shows the value but blocks changes; the select stays focusable and exposes `aria-readonly`. Set by `[formField]`; do not bind it yourself. |
+| `required`       | `boolean`                                                   | `false`     | Marks the control required. 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 field. Set by `[formField]`; do not bind it yourself.                                                        |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                        |
+| `name`           | `string`                                                    | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                      |
+| `id`             | `string`                                                    | `generated` | Control id; generated when not set.                                                                                                        |
+| `value`          | `T \| null`                                                 | `null`      | The selected option's value, `null` while nothing is selected; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.          |
+
+## Outputs
+
+| Name      | Payload      | Description                                                                                             |
+| --------- | ------------ | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `T`          | Emitted with the chosen value after a user change (never `null`).                                       |
+| `focused` | `FocusEvent` | Emitted when the control gains focus.                                                                   |
+| `blurred` | `FocusEvent` | Emitted when the control loses focus.                                                                   |
+| `touch`   | `void`       | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the native select; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Provide a `placeholder` when no option is a sensible default, and make the field required.
+- Keep option labels short; long labels are truncated by the native control.
+
+### Don't
+
+- Don't use it for two or three options that fit on screen; use `bf-radio-group` or `bf-segmented`.
+
+## Migration notes
+
+### 0.3.0
+
+**Breaking:** typed values. `BfSelectComponent<T = string>` is generic over the option value
+(`BfSelectOption<T = string>`), so numbers, ids and objects bind directly; `value` is `T | null`
+and defaults to `null` (was `''`), which shows the placeholder. New `compareWith`
+(`BfCompareWith<T>`, default `Object.is`) matches `value` to an option, and new `changed` emits the
+chosen value (never `null`) after a user change. A string, number or boolean option value is the
+native `<option value>` (`"42"` for `42`); an object option's is its index; a choice maps back by
+position, so duplicate native values still resolve. An option whose value is `''` is now
+selectable instead of reading as "empty"; an option whose value is `null` is unsupported (it reads
+as nothing selected). See Migration 6, 7 and 9.
+
+**Breaking:** the default `size` is `md` (40 px) instead of `lg` (48 px); `size` is a `BfSize`
+(`sm` 32, `md` 40, `lg` 48 px — `sm` is new) and, unset, follows `provideBfDefaults()`'s
+`fieldSize`. See Migration 2. The chevron and the text padding are logical, so the chevron sits at
+the inline end under `dir="rtl"`.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `select.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs; template handlers and framework hooks marked `@internal`, so the reference leaves
+them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+### 0.2.0
+
+The rest border is `border-strong`; the empty value (placeholder) is `text-muted` (was
+`text-subtle`). The chevron stays `text-subtle`.
+
+Changed: the border narrows to 1 px (was 1.5 px); the chevron stroke stays 1.5 px.
+
+Changed: the focus ring narrows to 2 px (was 4 px), as on `bf-input`.
+
+Fixed: the native select shows a pointer cursor and a hover border (`text-muted`, `danger` in the
+error state); focus and disabled borders still win.
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only the select keeps its
+value on the `surface-muted` background with `aria-readonly="true"` and stays in the tab order; a
+mouse press focuses it without opening the picker, the picker keys (arrows, Alt+Arrow, Enter, Space,
+F4, type-ahead) are blocked, and a change that still gets through (the platform picker on touch
+screens, which offers no press to cancel) is reverted without writing the model. `ariaLabel` / `ariaLabelledby` name a
+select without a visible `label` (ignored while `label` is set). `focus(options?)` focuses the
+native control, so Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit
+now work (they were no-ops).
+
+### 0.1.0
+
+Same `md`/`lg` size rename as `bf-input`. Without a `placeholder`, an unmatched `value` (e.g. the empty string) now renders a hidden, disabled, selected placeholder option so the native control shows no visible selection instead of falling back to the first real option. The inert `[value]` binding on `<select>` was removed; selection is driven entirely by `[selected]` on each `<option>`. The host no longer reflects a static `id` attribute onto `<bf-select>`. Added `bg-none` so consumers loading `@tailwindcss/forms` don't get a second, duplicate chevron drawn by the plugin's default `background-image` alongside the library's own CSS chevron.