@bitforgehq/ui 0.3.0

package/ai/components/number-input.md

@@ -0,0 +1,423 @@
+# bf-number-input
+
+Number field that binds number or null, with native min, max and step
+
+`BfNumberInputComponent` from `@bitforgehq/ui/number-input` · Forms · since 0.3.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/**
+ * The bf-number-input overview.
+ *
+ * Live demo of `bf-number-input`: a bound quantity with min, max and step and an echo, a price
+ * with a 0.05 step and a unit in the end slot, and a read-only field; then the sm, md and lg sizes
+ * in a row.
+ */
+@Component({
+  selector: 'app-example-number-input-overview',
+  imports: [BfNumberInputComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-number-input
+        label="Quantity"
+        helpText="1 to 99, in steps of 1."
+        class="max-w-60"
+        [min]="1"
+        [max]="99"
+        [step]="1"
+        [(value)]="quantity"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <bf-number-input
+        label="Hourly rate"
+        placeholder="0.00"
+        class="max-w-60"
+        [min]="0"
+        [step]="0.05"
+        [iconEnd]="true"
+        [(value)]="rate"
+      >
+        <span bfSlot="icon-end" class="text-caption text-text-muted">CHF</span>
+      </bf-number-input>
+      <bf-number-input label="Seats included" class="max-w-60" [value]="5" [readonly]="true" />
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-number-input
+          size="sm"
+          ariaLabel="Small number field"
+          placeholder="sm · 32 px"
+          class="w-40"
+        />
+        <bf-number-input ariaLabel="Medium number field" placeholder="md · 40 px" class="w-40" />
+        <bf-number-input
+          size="lg"
+          ariaLabel="Large number field"
+          placeholder="lg · 48 px"
+          class="w-40"
+        />
+      </div>
+    </div>
+  `,
+})
+export class NumberInputOverviewExampleComponent {
+  /** A number, `null` while the field is empty. */
+  readonly quantity = signal<number | null>(3);
+  readonly rate = signal<number | null>(null);
+
+  readonly status = computed(() => {
+    const quantity = this.quantity();
+    return quantity === null ? 'Quantity: empty (null)' : `Quantity: ${quantity} (a number)`;
+  });
+}
+```
+
+## Overview
+
+Number field with the chrome of the text field that binds `number | null`: an empty field is
+`null`, text the browser cannot read as a number is a `parse` error, and Signal Forms `min()` and
+`max()` become the native `min` and `max`.
+
+A number field with the look of `bf-input` that binds `number | null` instead of a string. It is a native `<input type="number">`, so the arrow keys and spin buttons step the value and `min`, `max` and `step` are native attributes. An empty field is `null`.
+
+It has its own entry point, `@bitforgehq/ui/number-input` (`import { BfNumberInputComponent } from '@bitforgehq/ui/number-input'`), because it parses its text with Angular's `transformedValue()` and so loads Angular Forms (`@angular/forms`, a required peer of the package). The main `@bitforgehq/ui` entry loads no Angular Forms code, so an app without forms never ships it.
+
+The decimal separator the field accepts follows the browser's own language, not the page's `lang` or Angular's `LOCALE_ID`, and differs between engines: under a German locale, WebKit reads `1,5` as `1.5` but treats a trailing `1.` as unreadable, while Chromium follows its UI language (with a German UI it read `1,5` as `15`). Test the locales your users run.
+
+## When to use
+
+Use `bf-number-input` for a quantity, a price, an age or another number you bind as `number | null`. Use [bf-input](https://bitforge-ui.web.app/components/input) instead for codes that only look numeric (postal codes, phone and card numbers), since a number field drops leading zeros.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/** A quantity from 1 to 99, bound as a number. */
+@Component({
+  selector: 'app-example-number-input-basic',
+  imports: [BfNumberInputComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-number-input label="Quantity" [min]="1" [max]="99" [(value)]="quantity" />
+      <p class="text-caption text-text-muted">quantity: {{ quantity() ?? 'null' }}</p>
+    </div>
+  `,
+})
+export class NumberInputBasicExampleComponent {
+  readonly quantity = signal<number | null>(1);
+}
+```
+
+Typing `42` stores the number `42`; clearing the field stores `null`, so type the bound signal or field `number | null` (a plain `number` field compiles, but receives `null` once cleared). Text the browser cannot read as a number (a lone `-`, `1e`) keeps the last number in the model and raises a `parse` error, "Enter a valid number", shown once the field is left, with or without a form. A form `reset()` or a new value replaces that text with the number.
+
+`(changed)` emits the new value (`null` when cleared) right after a user edit that changes the
+model; unreadable text changes nothing, so it does not emit.
+
+`min`, `max` and `step` limit the arrow keys and spin buttons only. Typed values outside them are stored without an error: range errors come from Signal Forms `min()`/`max()` (or Reactive `Validators.min()`/`max()`), and a step mismatch is not reported.
+
+## With Signal Forms
+
+Bind the field with `[formField]`. Signal Forms `min()` and `max()` flow into the native `min` and `max` attributes, and their errors show the default text for their kind ("Enter 18 or more", "Enter 120 or less") unless the rule passes a `message`. A parse error is reported to the field as a `parse` error, so it blocks `submit()` too.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, max, min, required } from '@angular/forms/signals';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/**
+ * An age field on Signal Forms.
+ *
+ * `required`, `min(18)` and `max(120)` without messages show the default text for each kind.
+ */
+@Component({
+  selector: 'app-example-number-input-signal-forms',
+  imports: [FormField, FormRoot, BfButtonComponent, BfNumberInputComponent],
+  template: `
+    <form [formRoot]="profile" class="flex flex-col items-start gap-3">
+      <bf-number-input label="Age" class="self-stretch" [formField]="profile.age" />
+      <bf-button type="submit">Save</bf-button>
+    </form>
+  `,
+})
+export class NumberInputSignalFormsExampleComponent {
+  readonly model = signal<{ age: number | null }>({ age: null });
+  readonly profile = form(
+    this.model,
+    (p) => {
+      required(p.age);
+      min(p.age, 18);
+      max(p.age, 120);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Reactive Forms
+
+The control works in Reactive Forms through Angular's Signal Forms interop (no `ControlValueAccessor`). Bind a `FormControl<number | null>`; `Validators.min()`/`max()` errors show the same default text, with the limit read from the error's `context`. Reactive validators do not reach the control's inputs, so pass `[min]`/`[max]` as well for the native attributes. The consumer-smoke fixture below binds it with `formControlName` inside a `FormGroup`; a standalone `[formControl]` works the same way.
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import {
+  BfButtonComponent,
+  BfCheckboxComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/**
+ * The same widgets in a Reactive Forms app: Angular 22 binds `formControlName` to them with no
+ * ControlValueAccessor. Controls are typed like the widgets' values: `number | null` for a select
+ * of numeric ids with nothing chosen yet and for a number field. `Validators.*` errors carry no
+ * message, so each touched invalid field shows the default text for the error's kind ("Fill in
+ * this field", "Enter 1 or more"), translated by `provideBfLabels()`; pass `errorMessage` only for
+ * text of your own.
+ */
+@Component({
+  selector: 'app-reactive-forms-example',
+  imports: [
+    ReactiveFormsModule,
+    BfButtonComponent,
+    BfCheckboxComponent,
+    BfInputComponent,
+    BfNumberInputComponent,
+    BfSelectComponent,
+  ],
+  template: `
+    <form [formGroup]="order" class="flex flex-col gap-4" novalidate (ngSubmit)="save()">
+      <bf-input label="Email" type="email" formControlName="email" />
+      <bf-select
+        label="Team"
+        placeholder="Choose a team"
+        [options]="teams"
+        formControlName="team"
+      />
+      <bf-number-input label="Quantity" formControlName="quantity" [min]="1" />
+      <bf-checkbox label="I accept the terms" formControlName="terms" />
+      <bf-button type="submit" class="self-start">Place order</bf-button>
+    </form>
+  `,
+})
+export class ReactiveFormsExampleComponent {
+  protected readonly teams: BfSelectOption<number>[] = [
+    { value: 1, label: 'Design' },
+    { value: 2, label: 'Engineering' },
+  ];
+
+  protected readonly order = new FormGroup({
+    email: new FormControl('', {
+      nonNullable: true,
+      validators: [Validators.required, Validators.email],
+    }),
+    team: new FormControl<number | null>(null, Validators.required),
+    quantity: new FormControl<number | null>(null, [Validators.required, Validators.min(1)]),
+    terms: new FormControl(false, { nonNullable: true, validators: Validators.requiredTrue }),
+  });
+
+  protected save(): void {
+    if (this.order.invalid) {
+      this.order.markAllAsTouched();
+      return;
+    }
+    // Send this.order.getRawValue() to your API.
+  }
+}
+```
+
+## Step and keyboard
+
+`step` sets the arrow-key and spin-button increment: `1` for whole numbers, `0.05` for a price, `any` for no grid. On phones, `inputMode` picks the virtual keyboard. Unset, a field that rules out negatives (`min` 0 or more) gets `numeric` for a whole-number step (or none) and `decimal` for a fractional one; any other field gets no `inputmode`, because neither the iOS numeric nor decimal pad has a minus key, and the full keyboard does. Set `inputMode` explicitly to override.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/** An hourly rate in 5-centime steps, with a currency in the icon-end slot. */
+@Component({
+  selector: 'app-example-number-input-step',
+  imports: [BfNumberInputComponent],
+  template: `
+    <bf-number-input label="Hourly rate" [min]="0" [step]="0.05" [iconEnd]="true" [(value)]="rate">
+      <span bfSlot="icon-end" class="text-text-muted">CHF</span>
+    </bf-number-input>
+  `,
+})
+export class NumberInputStepExampleComponent {
+  protected readonly rate = signal<number | null>(120);
+}
+```
+
+## Sizes
+
+`sm` 32 px, `md` 40 px (default), `lg` 48 px — the `BfSize` scale of `bf-input`. Unset, `size` follows `provideBfDefaults()`'s `fieldSize`, `md` by default. Fields get no touch extension: `sm`/`md` fields stay 32/40 px under a coarse pointer, so touch apps use `provideBfDefaults({ fieldSize: 'lg' })`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/** The sm, md and lg number field sizes. */
+@Component({
+  selector: 'app-example-number-input-sizes',
+  imports: [BfNumberInputComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-number-input size="sm" ariaLabel="Quantity" [(value)]="quantity" />
+      <bf-number-input label="Quantity" [(value)]="quantity" />
+      <bf-number-input size="lg" label="Quantity" [(value)]="quantity" />
+    </div>
+  `,
+})
+export class NumberInputSizesExampleComponent {
+  protected readonly quantity = signal<number | null>(2);
+}
+```
+
+## Read-only
+
+`readonly` uses the native attribute: the number can be selected and copied, the field stays in the tab order on the muted surface, and the arrow keys do not change it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';
+
+/** A read-only number field. */
+@Component({
+  selector: 'app-example-number-input-readonly',
+  imports: [BfNumberInputComponent],
+  template: `<bf-number-input label="Seats included" [value]="5" [readonly]="true" />`,
+})
+export class NumberInputReadonlyExampleComponent {}
+```
+
+## Desktop
+
+The field has no hover state; the text cursor shows over it. The `primary` border and the focus ring show on every focus, by mouse or keyboard, because a focused field takes typing. Fields default to `md` (40 px); `provideBfDefaults({ fieldSize: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, gives 32 px fields for a dense filter bar or table ([density guide](https://bitforge-ui.web.app/density)). The browser's spin buttons step the value with the mouse, within `min`, `max` and `step`.
+
+## Theming
+
+The same tokens as `bf-input`:
+
+- Border: `border-strong`, switching to `danger-border` on error; focus: `primary` border with a `ring` ring.
+- Disabled: `surface-sunken` border, `surface-muted` background, `text-disabled` text. Read-only: `surface-muted` background. Placeholder: `text-muted`. Icon slots: `text-subtle` (an icon's 3:1); give unit text such as `CHF` `text-text-muted` for 4.5:1.
+- Label, help and error text come from the `bf-field` wrapper (see its Theming section).
+
+## Accessibility
+
+Native `<input type="number">`, exposed as a spinbutton with its value, `min` and `max`; the arrow keys step it. `bf-field` renders the `<label for>`; the input 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, and `aria-invalid` is set once the field is touched (or left, for a parse error) and invalid. `aria-label` and `aria-labelledby` carry `ariaLabel` and `ariaLabelledby` only while there is no visible `label`. `focus()` focuses the native input; Signal Forms calls it from `focusBoundControl()`. Some browsers step a focused number field when the mouse wheel turns over it; the component leaves that native behaviour alone.
+
+### Keyboard
+
+| Key                                              | Action                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus to and from the field; a `readonly` one stays in the tab order            |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>        | Steps the value up / down by `step`, within `min` and `max`; nothing while `readonly` |
+| <kbd>Enter</kbd>                                 | Inside a `<form>` with a submit button, submits the form                              |
+
+## Inputs
+
+| Name             | Type                                                                                                    | Default     | Description                                                                                                                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `number \| undefined`                                                                                   | `undefined` | Lowest value (native `min`); bound by Signal Forms `min()`. Set by `[formField]`; do not bind it yourself.                                                                                |
+| `max`            | `number \| undefined`                                                                                   | `undefined` | Highest value (native `max`); bound by Signal Forms `max()`. Set by `[formField]`; do not bind it yourself.                                                                               |
+| `step`           | `BfNumberInputStep \| undefined` (`number \| 'any' \| undefined`)                                       | `undefined` | Step of the arrow keys and spin buttons, and the native step check (e.g. `0.05` or `any`).                                                                                                |
+| `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. 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`                                                                                                | `''`        | Example value shown while empty.                                                                                                                                                          |
+| `helpText`       | `string`                                                                                                | `''`        | Helper text under the control.                                                                                                                                                            |
+| `errorMessage`   | `string`                                                                                                | `''`        | Explicit error text; takes precedence over Signal Forms and parse errors.                                                                                                                 |
+| `disabled`       | `boolean`                                                                                               | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                                                                      |
+| `readonly`       | `boolean`                                                                                               | `false`     | Makes the control read-only. Set by `[formField]`; do not bind it yourself.                                                                                                               |
+| `required`       | `boolean`                                                                                               | `false`     | Marks the control required (label marker and native attribute). 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; 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.                                                              |
+| `name`           | `string`                                                                                                | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                                                                     |
+| `id`             | `string`                                                                                                | `generated` | Control id; generated when not set.                                                                                                                                                       |
+| `iconStart`      | `boolean`                                                                                               | `false`     | Reserve space for an icon or unit in the `icon-start` slot.                                                                                                                               |
+| `iconEnd`        | `boolean`                                                                                               | `false`     | Reserve space for an icon or unit in the `icon-end` slot.                                                                                                                                 |
+| `autocomplete`   | `string`                                                                                                | `''`        | Native autocomplete hint.                                                                                                                                                                 |
+| `inputMode`      | `BfNumberInputMode` (`'numeric' \| 'decimal' \| ''`)                                                    | `''`        | Virtual keyboard; unset, a field with `min >= 0` gets `numeric` for an integer (or no) step and `decimal` otherwise, and any other field none (the full keyboard, which has a minus key). |
+| `enterKeyHint`   | `BfInputEnterKeyHint` (`'enter' \| 'done' \| 'go' \| 'next' \| 'previous' \| 'search' \| 'send' \| ''`) | `''`        | Label of the virtual keyboard's Enter key (native `enterkeyhint`).                                                                                                                        |
+| `value`          | `number \| null`                                                                                        | `null`      | The number, `null` while the field is empty; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                                                                           |
+
+## Outputs
+
+| Name      | Payload          | Description                                                                                             |
+| --------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `number \| null` | Emitted with the new value (`null` when emptied) right after the user changes it.                       |
+| `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. |
+
+## Slots
+
+- `icon-start`: An icon inside the field, before the number.
+- `icon-end`: An icon inside the field, after the number.
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the native input; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Use it for quantities, prices, ages and numeric ids that are typed, instead of `bf-input type="number"` with a string model.
+- Give a `step` that matches the data (`0.05` for a price), so stepping and the native check agree.
+
+### Don't
+
+- Don't use it for codes that only look numeric (postal codes, phone numbers, card numbers): leading zeros are lost; use `bf-input` with `inputMode="numeric"`.
+- Don't bind both `[(value)]` and `[formField]`.
+
+## Migration notes
+
+### 0.3.0
+
+New `changed` output: the new `number | null` right after a user edit that changes the model
+(unreadable text changes nothing and does not emit). `step` is typed with the new exported
+`BfNumberInputStep` (`number | 'any'`) and `inputMode` with `BfNumberInputMode`
+(`'numeric' | 'decimal' | ''`); `enterKeyHint` takes `BfInputEnterKeyHint` (`BfEnterKeyHint | ''`).
+
+New `bf-number-input`: a native `<input type="number">` with the chrome, sizes (`fieldSize`), slots
+and states of `bf-input` that implements `FormValueControl<number | null>` through Angular's
+`transformedValue()`. An empty field is `null`; text the browser cannot read as a number keeps the
+model and raises a `parse` error ("Enter a valid number", `provideBfLabels()`'s
+`validation.parse`), shown once the field is left, with or without a form. `min`, `max` and
+`step` are native attributes that limit stepping, bound by Signal Forms `min()`/`max()` (whose
+errors and default messages are the only range errors; a step mismatch is not reported). Unset,
+`inputMode` is `numeric` for an integer (or no) step and `decimal` otherwise only when `min >= 0`;
+without such a `min` it stays off, so phone keyboards keep a minus key. A form `reset()` replaces
+unreadable text with the number. Works
+with Reactive Forms `FormControl<number | null>` through the Signal Forms interop. See Migration 8.
+It ships in its own entry point, `import { BfNumberInputComponent } from
+'@bitforgehq/ui/number-input'`, because it parses with Angular's `transformedValue()` and so loads
+Angular Forms (`@angular/forms`, a required peer); a parse error reaches the bound Signal Forms
+field (blocking `submit()`) or Reactive `FormControl` (invalid) with no setup. The widgets entry
+`@bitforgehq/ui` loads no `@angular/forms` code at runtime, so an app without forms ships none of
+it.
+
+JSDoc of `number-input.component.ts` for the API reference: `@slot` docs for `icon-start`,
+`icon-end`; `@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.