@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/number-field.examples.md

@@ -0,0 +1,1078 @@
+<!-- index: ./index.md -->
+# number-field
+
+`data-ui="number-field"` · Number input with steppers and formatting.
+
+## Examples
+
+### Playground
+
+One control with every axis on it, driven by the controls below the canvas. Type a number, then hold the increment button: it steps once, waits, and then repeats.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Quantidade</label>
+  <div slNumberField>
+    <input slNumberFieldInput defaultValue="3" min="1" max="99" />
+  </div>
+  <span slFieldDescription>Máximo de 99 unidades por pedido.</span>
+</div>
+```
+
+### The step the control sits at
+
+Three steps, and inside a field the control takes the field’s rather than its own: a small field holding a medium control is a field and a control disagreeing about one row.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-sizes',
+  imports: [SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slNumberField size="sm">
+        <input slNumberFieldInput aria-label="Units per case" defaultValue="24" min="1" />
+      </div>
+      <div slNumberField size="md">
+        <input slNumberFieldInput aria-label="Cases ordered" defaultValue="12" min="1" />
+      </div>
+      <div slNumberField size="lg">
+        <input slNumberFieldInput aria-label="Pallets ordered" defaultValue="2" min="1" />
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldSizes {}
+```
+
+### How much frame the control shows
+
+outline takes the ground it is placed on, subtle sinks into the page, and plain shows nothing until the pointer or the caret arrives — which is what a dense table cell of amounts needs.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-variants',
+  imports: [SlField, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Unit price</label>
+        <div slNumberField variant="outline">
+          <input
+            slNumberFieldInput
+            defaultValue="18"
+            min="0"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Discount</label>
+        <div slNumberField variant="subtle">
+          <input
+            slNumberFieldInput
+            defaultValue="0.05"
+            min="0"
+            max="1"
+            step="0.01"
+            [format]="{ style: 'percent' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Freight</label>
+        <div slNumberField variant="plain" stepper="none">
+          <input
+            slNumberFieldInput
+            defaultValue="32.38"
+            min="0"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldVariants {}
+```
+
+### Where the two buttons sit, and whether they sit at all
+
+stacked is one column at the inline end; split puts decrement and increment at either end of the frame with the value centred between them, which is the only arrangement whose targets clear 24 pixels in both axes.
+
+Excerpt — not a complete module
+
+```html
+<div slNumberField stepper="stacked"><input slNumberFieldInput defaultValue="12" /></div>
+
+<!-- The arrangement a thumb can hit, and the one a quantity wants. -->
+<div slNumberField stepper="split">
+  <input slNumberFieldInput defaultValue="3" min="1" max="99" />
+</div>
+
+<!-- Typed and never spun, which is what a dense table asks for. -->
+<div slNumberField stepper="none"><input slNumberFieldInput defaultValue="1480" /></div>
+```
+
+### The bounds, the step, and what happens at the edge
+
+The stepper that would leave the range is disabled rather than silently inert. Type 400 into the first control and tab away: clamp="blur" brings it back, while clamp="none" leaves it where you put it and says so.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-range',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Pallets on the trailer</label>
+        <div slNumberField>
+          <input slNumberFieldInput defaultValue="26" min="0" max="26" />
+        </div>
+        <span slFieldDescription>A 53-foot trailer holds 26 pallets.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Bottles of Chartreuse verte</label>
+        <div slNumberField>
+          <input slNumberFieldInput defaultValue="12" min="6" step="6" snapToStep />
+        </div>
+        <span slFieldDescription>Sold in cases of 6. Type 20 and leave the field.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldRange {}
+```
+
+### Currency, percent and unit are formattings, not types
+
+One numeric value, written by Intl.NumberFormat. The symbol inside the value comes from format and is part of what a reader copies; a symbol beside the value is an adornment instead, and the two sit side by side below.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-format',
+  imports: [SlField, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Credit limit</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="25000"
+            min="0"
+            step="500"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Sales tax</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="0.0825"
+            min="0"
+            max="1"
+            step="0.0025"
+            [format]="{ maximumFractionDigits: 2, style: 'percent' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pallet volume</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="1.8"
+            min="0"
+            step="0.1"
+            [format]="{ style: 'unit', unit: 'liter', unitDisplay: 'long' }"
+          />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldFormat {}
+```
+
+### When the grouping appears
+
+The two amounts below are the same under both settings; the axis decides only what the field shows between two keystrokes. The number itself moves on every keystroke that parses either way.
+
+Excerpt — not a complete module
+
+```html
+<!-- The default. The caret stays on the character it was on, because it is
+     counted in the reader's own characters rather than in string indices. -->
+<div slNumberField><input slNumberFieldInput locale="pt-BR" /></div>
+
+<!-- The reader's own text until blur, Enter, a stepper press or a key step.
+     For an amount that is pasted and audited rather than typed. -->
+<div slNumberField>
+  <input slNumberFieldInput locale="pt-BR" formatOn="commit" />
+</div>
+
+<!-- Rounding and padding belong to the commit under both: 1,50 keeps its
+     nought while it is being typed, and 1, keeps its separator. -->
+```
+
+### The separator, the grouping and the numerals
+
+Paste “R$ 1.480,00” into the Brazilian control and “١٬٤٨٠” into the Arabic one: both parse, because the parser is built from the same Intl parts the formatter writes with.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-locale',
+  imports: [SlField, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Invoice total, United States</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="14800.5"
+            locale="en-US"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Invoice total, Germany</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="14800.5"
+            locale="de-DE"
+            [format]="{ currency: 'EUR', style: 'currency' }"
+          />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Invoice total, Egypt</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="14800.5"
+            locale="ar-EG"
+            [format]="{ currency: 'EGP', style: 'currency' }"
+          />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldLocale {}
+```
+
+### What sits beside the number
+
+start and end name the reading direction rather than a side, and neither is ever squeezed: the value gives up width first. Switch the toolbar to rtl and the mark stays before the amount.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  SlNumberField,
+  SlNumberFieldEnd,
+  SlNumberFieldInput,
+  SlNumberFieldStart,
+} from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-adornments',
+  imports: [
+    SlField,
+    SlFieldLabel,
+    SlNumberField,
+    SlNumberFieldEnd,
+    SlNumberFieldInput,
+    SlNumberFieldStart,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Purchase price</label>
+        <div slNumberField>
+          <span slNumberFieldStart>$</span>
+          <input
+            slNumberFieldInput
+            defaultValue="1480"
+            min="0"
+            [format]="{ minimumFractionDigits: 2 }"
+          />
+          <span slNumberFieldEnd>USD</span>
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Lead time</label>
+        <div slNumberField>
+          <input slNumberFieldInput defaultValue="14" min="0" max="120" />
+          <span slNumberFieldEnd>days</span>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldAdornments {}
+```
+
+### Drag the mark to move the number
+
+The design tools’ gesture. Press the mark and drag sideways: two pixels per step, Shift for the large step, Alt for the small one. A right-to-left document steps up towards the left, the inline end.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlGrid } from '@slotted/angular/grid';
+import {
+  SlNumberField,
+  SlNumberFieldEnd,
+  SlNumberFieldInput,
+  SlNumberFieldScrub,
+  SlNumberFieldStart,
+} from '@slotted/angular/number-field';
+
+@Component({
+  selector: 'app-number-field-scrub',
+  imports: [
+    SlField,
+    SlFieldLabel,
+    SlGrid,
+    SlNumberField,
+    SlNumberFieldEnd,
+    SlNumberFieldInput,
+    SlNumberFieldScrub,
+    SlNumberFieldStart,
+  ],
+  template: `
+    <div slGrid [columns]="2" [gap]="4">
+      <div slField>
+        <label slFieldLabel>Label width</label>
+        <div slNumberField>
+          <span slNumberFieldStart><span slNumberFieldScrub>W</span></span>
+          <input slNumberFieldInput defaultValue="100" min="20" max="210" />
+          <span slNumberFieldEnd>mm</span>
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Label height</label>
+        <div slNumberField>
+          <span slNumberFieldStart><span slNumberFieldScrub [sensitivity]="4">H</span></span>
+          <input slNumberFieldInput defaultValue="150" min="20" max="297" />
+          <span slNumberFieldEnd>mm</span>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldScrubExample {}
+```
+
+### The states the frame paints
+
+Read-only keeps full-strength ink and softens its edge, because the value is real and still submitted; disabled is muted to a measured colour rather than faded, and both withdraw the steppers by disabling them rather than removing them.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-states',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlNumberField,
+    SlNumberFieldInput,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid>
+        <label slFieldLabel>Quantity to ship</label>
+        <div slNumberField><input slNumberFieldInput defaultValue="120" min="1" /></div>
+        <span slFieldError>Only 39 units of Chai are in stock.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Units on order</label>
+        <div slNumberField><input slNumberFieldInput defaultValue="40" /></div>
+        <span slFieldDescription>Counted from open purchase orders.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Units reserved</label>
+        <div slNumberField><input slNumberFieldInput defaultValue="12" /></div>
+        <span slFieldDescription>Released when the order ships.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldStates {}
+```
+
+### Numbers the family did not choose
+
+A value longer than the control ellipsises rather than clipping mid-glyph; a negative keeps its sign in front of the digits in both directions; and at 240 pixels the value surrenders width while the steppers keep their target size.
+
+Excerpt — not a complete module
+
+```html
+<div slNumberField>
+  <input slNumberFieldInput defaultValue="1480320559774.25" locale="pt-BR" />
+</div>
+
+<!-- The digits are tabular, so nothing shifts as they are typed over,
+     and the minus stays in front of the amount in an Arabic document. -->
+<div slNumberField>
+  <span slNumberFieldStart>R$</span>
+  <input slNumberFieldInput defaultValue="-1480" locale="pt-BR" />
+</div>
+```
+
+### Setting it once, reaching past it, and putting it in a form
+
+ControlValueAccessor is the two-way binding the ecosystem expects; exportAs hands the template the directive, which carries increment(), decrement() and the native element; name submits the raw number through a hidden input.
+
+Excerpt — not a complete module
+
+```html
+<div slNumberField>
+  <input slNumberFieldInput [formControl]="quantity" min="1" max="99" />
+</div>
+
+<div slNumberField>
+  <input slNumberFieldInput #campo="slNumberFieldInput" defaultValue="3" />
+</div>
+<button type="button" (click)="campo.increment()">Mais um</button>
+
+<!-- The hidden input carries 1480, never "R$ 1.480,00". -->
+<div slNumberField>
+  <input
+    slNumberFieldInput
+    name="amount"
+    defaultValue="1480"
+    [format]="{ style: 'currency', currency: 'BRL' }"
+  />
+</div>
+```
+
+### What the keyboard does, and what it deliberately does not
+
+Arrows step, Shift and the page keys move by the large amount, Alt by the small one, Home and End reach the bounds. Tab never lands on a stepper: twenty amounts in a form would be forty extra stops.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-keyboard',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Shipping weight</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="12.5"
+            min="0"
+            step="1"
+            largeStep="10"
+            smallStep="0.1"
+            [format]="{ maximumFractionDigits: 1, style: 'unit', unit: 'kilogram' }"
+          />
+        </div>
+        <span slFieldDescription>Arrows: 1 kg. Shift or Page keys: 10 kg. Alt: 0.1 kg.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Safety stock</label>
+        <div slNumberField>
+          <input slNumberFieldInput defaultValue="15" min="0" wheel />
+        </div>
+        <span slFieldDescription>With the field focused, the mouse wheel steps the value.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldKeyboard {}
+```
+
+### clamp.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldEnd, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-clamp',
+  imports: [
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlNumberField,
+    SlNumberFieldEnd,
+    SlNumberFieldInput,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Line discount</label>
+        <div slNumberField>
+          <input slNumberFieldInput clamp="blur" defaultValue="10" min="0" max="25" />
+          <span slNumberFieldEnd>%</span>
+        </div>
+        <span slFieldDescription>Type 40 and leave the field: it returns to 25.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Order discount</label>
+        <div slNumberField>
+          <input slNumberFieldInput clamp="strict" defaultValue="10" min="0" max="25" />
+          <span slNumberFieldEnd>%</span>
+        </div>
+        <span slFieldDescription>A keystroke that would pass 25 is refused.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Contract discount</label>
+        <div slNumberField>
+          <input slNumberFieldInput clamp="none" defaultValue="10" min="0" max="25" />
+          <span slNumberFieldEnd>%</span>
+        </div>
+        <span slFieldDescription>40 stays, and the field is marked invalid.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldClamp {}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+const USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });
+
+@Component({
+  selector: 'app-number-field-controlled',
+  imports: [SlButton, SlField, SlFieldLabel, SlInline, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Credit limit for Ernst Handel</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            min="0"
+            step="500"
+            stepFrom="5000"
+            [format]="{ currency: 'USD', style: 'currency' }"
+            [value]="limit()"
+            (valueChange)="limit.set($event.value)"
+          />
+        </div>
+      </div>
+      <div slInline [gap]="3" justify="between">
+        <span>{{ summary() }}</span>
+        <button slButton variant="outline" [disabled]="limit() === null" (click)="limit.set(null)">
+          Remove limit
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldControlled {
+  readonly limit = signal<number | null>(5000);
+  readonly summary = computed(() => {
+    const limit = this.limit();
+    return limit === null ? 'No credit limit' : `Orders up to ${USD.format(limit)}`;
+  });
+}
+```
+
+### decimals.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-decimals',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Exchange rate, EUR to USD</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="1.0842"
+            min="0"
+            step="0.0001"
+            [format]="{ maximumFractionDigits: 4, minimumFractionDigits: 4 }"
+          />
+        </div>
+        <span slFieldDescription>Four decimals: 1.1 becomes 1.1000 on blur.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Cartons</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            defaultValue="40"
+            min="0"
+            [format]="{ maximumFractionDigits: 0 }"
+          />
+        </div>
+        <span slFieldDescription>Whole cartons: the decimal separator is refused.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldDecimals {}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlGrid } from '@slotted/angular/grid';
+import {
+  provideNumberFieldDefaults,
+  SlNumberField,
+  SlNumberFieldInput,
+} from '@slotted/angular/number-field';
+
+@Component({
+  selector: 'app-number-field-defaults',
+  imports: [SlField, SlFieldLabel, SlGrid, SlNumberField, SlNumberFieldInput],
+  providers: [provideNumberFieldDefaults({ size: 'sm', stepper: 'split', variant: 'subtle' })],
+  template: `
+    <div slGrid [gap]="3" minItemWidth="xs">
+      <div slField>
+        <label slFieldLabel>Cases</label>
+        <div slNumberField><input slNumberFieldInput defaultValue="6" min="0" /></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Loose units</label>
+        <div slNumberField><input slNumberFieldInput defaultValue="11" min="0" /></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pallets</label>
+        <div slNumberField stepper="stacked">
+          <input slNumberFieldInput defaultValue="1" min="0" />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldDefaults {}
+```
+
+### format-on.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-format-on',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Annual purchase budget</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            formatOn="change"
+            min="0"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+        <span slFieldDescription>Type 1250000: the grouping appears with each digit.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Amount from bank statement</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            formatOn="commit"
+            min="0"
+            [format]="{ currency: 'USD', style: 'currency' }"
+          />
+        </div>
+        <span slFieldDescription>Your text stays as typed until Enter or blur.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldFormatOn {}
+```
+
+### handle.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-handle',
+  imports: [SlButton, SlField, SlFieldLabel, SlInline, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="3">
+      <div slField>
+        <label slFieldLabel>Cases of Chang</label>
+        <div slNumberField>
+          <input slNumberFieldInput #cases="slNumberFieldInput" defaultValue="4" min="0" max="48" />
+        </div>
+      </div>
+      <div slInline [gap]="2">
+        <button slButton variant="outline" (click)="cases.decrement()">Remove a case</button>
+        <button slButton variant="outline" (click)="cases.increment()">Add a case</button>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldHandleExample {}
+```
+
+### order-line.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlGrid } from '@slotted/angular/grid';
+import { SlInline } from '@slotted/angular/inline';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+
+const USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });
+
+const LINES = [
+  { id: 'cabrales', product: 'Queso Cabrales', price: 14, stock: 22 },
+  { id: 'hokkien', product: 'Singaporean Hokkien Fried Mee', price: 9.8, stock: 26 },
+  { id: 'mozzarella', product: 'Mozzarella di Giovanni', price: 34.8, stock: 14 },
+];
+
+@Component({
+  selector: 'app-number-field-order-line',
+  imports: [SlGrid, SlInline, SlNumberField, SlNumberFieldInput, SlStack, SlText],
+  template: `
+    <div slStack [gap]="5">
+      <div slStack [gap]="4">
+        @for (line of lines; track line.id) {
+          <div slGrid [columns]="3" [gap]="4" minItemWidth="xs">
+            <div slStack [gap]="1">
+              <span slText weight="medium">{{ line.product }}</span>
+              <span slText size="sm" tone="muted"
+                >{{ usd(line.price) }} each · {{ line.stock }} in stock</span
+              >
+            </div>
+            <div slStack justify="center">
+              <div slNumberField size="sm" stepper="split">
+                <input
+                  slNumberFieldInput
+                  min="0"
+                  [attr.aria-label]="'Quantity of ' + line.product"
+                  [max]="line.stock"
+                  [value]="quantities()[line.id] ?? null"
+                  (valueChange)="set(line.id, $event.value)"
+                />
+              </div>
+            </div>
+            <div slStack justify="center">
+              <span slText align="end" numeric="tabular">{{
+                usd(line.price * (quantities()[line.id] ?? 0))
+              }}</span>
+            </div>
+          </div>
+        }
+      </div>
+      <div slInline [gap]="4" justify="between">
+        <span slText weight="semibold">Order total</span>
+        <span slText numeric="tabular" weight="semibold">{{ usd(total()) }}</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldOrderLine {
+  readonly lines = LINES;
+  readonly quantities = signal<Record<string, number | null>>({
+    cabrales: 12,
+    hokkien: 10,
+    mozzarella: 5,
+  });
+  readonly total = computed(() =>
+    LINES.reduce((sum, line) => sum + line.price * (this.quantities()[line.id] ?? 0), 0),
+  );
+
+  usd(amount: number): string {
+    return USD.format(amount);
+  }
+
+  set(id: string, value: number | null): void {
+    this.quantities.update((current) => ({ ...current, [id]: value }));
+  }
+}
+```
+
+### price-editor.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlGrid } from '@slotted/angular/grid';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+
+@Component({
+  selector: 'app-number-field-price-editor',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlGrid, SlNumberField, SlNumberFieldInput],
+  template: `
+    <div slGrid [gap]="4" minItemWidth="xs">
+      <div slField required>
+        <label slFieldLabel>Unit cost</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            min="0"
+            step="0.5"
+            [format]="currency"
+            [value]="cost()"
+            (valueChange)="cost.set($event.value)"
+          />
+        </div>
+      </div>
+      <div slField required>
+        <label slFieldLabel>Markup</label>
+        <div slNumberField>
+          <input
+            slNumberFieldInput
+            min="0"
+            max="3"
+            step="0.01"
+            largeStep="0.1"
+            [format]="{ style: 'percent' }"
+            [value]="markup()"
+            (valueChange)="markup.set($event.value)"
+          />
+        </div>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>List price</label>
+        <div slNumberField stepper="none">
+          <input slNumberFieldInput [format]="currency" [value]="price()" />
+        </div>
+        <span slFieldDescription>Unit cost plus markup.</span>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldPriceEditor {
+  readonly currency: Intl.NumberFormatOptions = { currency: 'USD', style: 'currency' };
+  readonly cost = signal<number | null>(175);
+  readonly markup = signal<number | null>(0.5);
+  readonly price = computed(() => {
+    const cost = this.cost();
+    const markup = this.markup();
+    return cost === null || markup === null ? null : Math.round(cost * (1 + markup) * 100) / 100;
+  });
+}
+```
+
+### steppers.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-steppers',
+  imports: [SlField, SlFieldLabel, SlNumberField, SlNumberFieldInput, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Reorder quantity</label>
+        <div slNumberField stepper="stacked">
+          <input slNumberFieldInput defaultValue="40" min="0" step="10" />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Quantity</label>
+        <div slNumberField stepper="split">
+          <input slNumberFieldInput defaultValue="3" min="1" max="99" />
+        </div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Units in stock</label>
+        <div slNumberField stepper="none">
+          <input slNumberFieldInput defaultValue="39" min="0" />
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class NumberFieldSteppers {}
+```
+
+### validation.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlNumberField, SlNumberFieldInput } from '@slotted/angular/number-field';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-number-field-validation',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlField,
+    SlFieldDescription,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlNumberField,
+    SlNumberFieldInput,
+    SlStack,
+  ],
+  template: `
+    <form novalidate (submit)="submit($event)">
+      <div slStack [gap]="4">
+        <div slField required [invalid]="error() !== '' ? true : undefined">
+          <label slFieldLabel>Units of Chai to ship</label>
+          <div slNumberField>
+            <input
+              slNumberFieldInput
+              name="quantity"
+              min="1"
+              max="39"
+              [formControl]="quantity"
+              (valueChange)="sent.set('')"
+            />
+          </div>
+          <span slFieldDescription>39 units in stock.</span>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3">
+          <button slButton type="submit">Create shipment</button>
+          @if (sent() !== '') {
+            <span role="status">{{ sent() }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class NumberFieldValidation {
+  readonly quantity = new FormControl<number | null>(null, Validators.required);
+  readonly value = toSignal(this.quantity.valueChanges, { initialValue: this.quantity.value });
+  readonly submitted = signal(false);
+  readonly sent = signal('');
+  readonly error = computed(() =>
+    this.submitted() && this.value() === null ? 'Enter how many units to ship.' : '',
+  );
+
+  submit(event: Event): void {
+    event.preventDefault();
+    this.submitted.set(true);
+    const data = new FormData(event.target as HTMLFormElement);
+    this.sent.set(this.quantity.valid ? `Sent quantity=${String(data.get('quantity'))}` : '');
+  }
+}
+```