@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/number-field.examples.md

@@ -0,0 +1,822 @@
+<!-- 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
+
+```tsx
+<Field>
+  <FieldLabel>Quantidade</FieldLabel>
+  <NumberField defaultValue={3} max={99} min={1} />
+  <FieldDescription>Máximo de 99 unidades por pedido.</FieldDescription>
+</Field>;
+```
+
+### 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
+
+```tsx
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldSizes() {
+  return (
+    <Stack gap={4}>
+      <NumberField aria-label="Units per case" defaultValue={24} min={1} size="sm" />
+      <NumberField aria-label="Cases ordered" defaultValue={12} min={1} size="md" />
+      <NumberField aria-label="Pallets ordered" defaultValue={2} min={1} size="lg" />
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldVariants() {
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Unit price</FieldLabel>
+        <NumberField
+          defaultValue={18}
+          format={{ currency: 'USD', style: 'currency' }}
+          min={0}
+          variant="outline"
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Discount</FieldLabel>
+        <NumberField
+          defaultValue={0.05}
+          format={{ style: 'percent' }}
+          max={1}
+          min={0}
+          step={0.01}
+          variant="subtle"
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Freight</FieldLabel>
+        <NumberField
+          defaultValue={32.38}
+          format={{ currency: 'USD', style: 'currency' }}
+          min={0}
+          stepper="none"
+          variant="plain"
+        />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+<NumberField defaultValue={12} stepper="stacked" />;
+
+// The arrangement a thumb can hit, and the one a quantity wants.
+<NumberField defaultValue={3} max={99} min={1} stepper="split" />;
+
+// Typed and never spun, which is what a dense table asks for.
+<NumberField defaultValue={1480} stepper="none" />;
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldRange() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Pallets on the trailer</FieldLabel>
+        <NumberField defaultValue={26} max={26} min={0} />
+        <FieldDescription>A 53-foot trailer holds 26 pallets.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Bottles of Chartreuse verte</FieldLabel>
+        <NumberField defaultValue={12} min={6} snapToStep step={6} />
+        <FieldDescription>Sold in cases of 6. Type 20 and leave the field.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldFormat() {
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Credit limit</FieldLabel>
+        <NumberField
+          defaultValue={25000}
+          format={{ currency: 'USD', style: 'currency' }}
+          min={0}
+          step={500}
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Sales tax</FieldLabel>
+        <NumberField
+          defaultValue={0.0825}
+          format={{ maximumFractionDigits: 2, style: 'percent' }}
+          max={1}
+          min={0}
+          step={0.0025}
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Pallet volume</FieldLabel>
+        <NumberField
+          defaultValue={1.8}
+          format={{ style: 'unit', unit: 'liter', unitDisplay: 'long' }}
+          min={0}
+          step={0.1}
+        />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+// 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.
+<NumberField locale="pt-BR" />;
+
+// 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.
+<NumberField formatOn="commit" locale="pt-BR" />;
+
+// 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldLocale() {
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Invoice total, United States</FieldLabel>
+        <NumberField
+          defaultValue={14800.5}
+          format={{ currency: 'USD', style: 'currency' }}
+          locale="en-US"
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Invoice total, Germany</FieldLabel>
+        <NumberField
+          defaultValue={14800.5}
+          format={{ currency: 'EUR', style: 'currency' }}
+          locale="de-DE"
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Invoice total, Egypt</FieldLabel>
+        <NumberField
+          defaultValue={14800.5}
+          format={{ currency: 'EGP', style: 'currency' }}
+          locale="ar-EG"
+        />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldAdornments() {
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Purchase price</FieldLabel>
+        <NumberField
+          defaultValue={1480}
+          end="USD"
+          format={{ minimumFractionDigits: 2 }}
+          min={0}
+          start="$"
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Lead time</FieldLabel>
+        <NumberField defaultValue={14} end="days" max={120} min={0} />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Grid } from '@slotted/react/grid';
+import { NumberField, NumberFieldScrub } from '@slotted/react/number-field';
+
+export default function NumberFieldScrubExample() {
+  return (
+    <Grid columns={2} gap={4}>
+      <Field>
+        <FieldLabel>Label width</FieldLabel>
+        <NumberField
+          defaultValue={100}
+          end="mm"
+          max={210}
+          min={20}
+          start={<NumberFieldScrub>W</NumberFieldScrub>}
+        />
+      </Field>
+      <Field>
+        <FieldLabel>Label height</FieldLabel>
+        <NumberField
+          defaultValue={150}
+          end="mm"
+          max={297}
+          min={20}
+          start={<NumberFieldScrub sensitivity={4}>H</NumberFieldScrub>}
+        />
+      </Field>
+    </Grid>
+  );
+}
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldStates() {
+  return (
+    <Stack gap={5}>
+      <Field invalid>
+        <FieldLabel>Quantity to ship</FieldLabel>
+        <NumberField defaultValue={120} min={1} />
+        <FieldError>Only 39 units of Chai are in stock.</FieldError>
+      </Field>
+      <Field readOnly>
+        <FieldLabel>Units on order</FieldLabel>
+        <NumberField defaultValue={40} />
+        <FieldDescription>Counted from open purchase orders.</FieldDescription>
+      </Field>
+      <Field disabled>
+        <FieldLabel>Units reserved</FieldLabel>
+        <NumberField defaultValue={12} />
+        <FieldDescription>Released when the order ships.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### 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
+
+```tsx
+<NumberField defaultValue={1480320559774.25} locale="pt-BR" />;
+
+// 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.
+<NumberField defaultValue={-1480} end="BRL" locale="pt-BR" start="R$" />;
+```
+
+### Setting it once, reaching past it, and putting it in a form
+
+The provider carries the five decisions an application takes once; ref reaches the element and handle reaches the two actions a value cannot express; name submits the raw number through a hidden input rather than the formatted string.
+
+Excerpt — not a complete module
+
+```tsx
+<NumberFieldDefaultsProvider stepper="split">
+  <NumberField defaultValue={3} />
+</NumberFieldDefaultsProvider>;
+
+const handle = useRef<NumberFieldHandle>(null);
+<NumberField handle={handle} />;
+<Button onClick={() => handle.current?.increment()}>Mais um</Button>;
+
+// The hidden input carries 1480, never "R$ 1.480,00".
+<NumberField format={{ currency: 'BRL', style: 'currency' }} name="amount" />;
+```
+
+### 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
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldKeyboard() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Shipping weight</FieldLabel>
+        <NumberField
+          defaultValue={12.5}
+          format={{ maximumFractionDigits: 1, style: 'unit', unit: 'kilogram' }}
+          largeStep={10}
+          min={0}
+          smallStep={0.1}
+          step={1}
+        />
+        <FieldDescription>Arrows: 1 kg. Shift or Page keys: 10 kg. Alt: 0.1 kg.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Safety stock</FieldLabel>
+        <NumberField defaultValue={15} min={0} wheel />
+        <FieldDescription>
+          With the field focused, the mouse wheel steps the value.
+        </FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### clamp.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldClamp() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Line discount</FieldLabel>
+        <NumberField clamp="blur" defaultValue={10} end="%" max={25} min={0} />
+        <FieldDescription>Type 40 and leave the field: it returns to 25.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Order discount</FieldLabel>
+        <NumberField clamp="strict" defaultValue={10} end="%" max={25} min={0} />
+        <FieldDescription>A keystroke that would pass 25 is refused.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Contract discount</FieldLabel>
+        <NumberField clamp="none" defaultValue={10} end="%" max={25} min={0} />
+        <FieldDescription>40 stays, and the field is marked invalid.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### controlled.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+const USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });
+
+export default function NumberFieldControlled() {
+  const [limit, setLimit] = useState<number | null>(5000);
+
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Credit limit for Ernst Handel</FieldLabel>
+        <NumberField
+          format={{ currency: 'USD', style: 'currency' }}
+          min={0}
+          onValueChange={setLimit}
+          step={500}
+          stepFrom={5000}
+          value={limit}
+        />
+      </Field>
+      <Inline gap={3} justify="between">
+        <span>{limit === null ? 'No credit limit' : `Orders up to ${USD.format(limit)}`}</span>
+        <Button disabled={limit === null} onClick={() => setLimit(null)} variant="outline">
+          Remove limit
+        </Button>
+      </Inline>
+    </Stack>
+  );
+}
+```
+
+### decimals.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldDecimals() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Exchange rate, EUR to USD</FieldLabel>
+        <NumberField
+          defaultValue={1.0842}
+          format={{ maximumFractionDigits: 4, minimumFractionDigits: 4 }}
+          min={0}
+          step={0.0001}
+        />
+        <FieldDescription>Four decimals: 1.1 becomes 1.1000 on blur.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Cartons</FieldLabel>
+        <NumberField defaultValue={40} format={{ maximumFractionDigits: 0 }} min={0} />
+        <FieldDescription>Whole cartons: the decimal separator is refused.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### defaults.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Grid } from '@slotted/react/grid';
+import { NumberField, NumberFieldDefaultsProvider } from '@slotted/react/number-field';
+
+export default function NumberFieldDefaults() {
+  return (
+    <NumberFieldDefaultsProvider size="sm" stepper="split" variant="subtle">
+      <Grid gap={3} minItemWidth="xs">
+        <Field>
+          <FieldLabel>Cases</FieldLabel>
+          <NumberField defaultValue={6} min={0} />
+        </Field>
+        <Field>
+          <FieldLabel>Loose units</FieldLabel>
+          <NumberField defaultValue={11} min={0} />
+        </Field>
+        <Field>
+          <FieldLabel>Pallets</FieldLabel>
+          <NumberField defaultValue={1} min={0} stepper="stacked" />
+        </Field>
+      </Grid>
+    </NumberFieldDefaultsProvider>
+  );
+}
+```
+
+### format-on.tsx
+
+Example
+
+```tsx
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldFormatOn() {
+  return (
+    <Stack gap={5}>
+      <Field>
+        <FieldLabel>Annual purchase budget</FieldLabel>
+        <NumberField format={{ currency: 'USD', style: 'currency' }} formatOn="change" min={0} />
+        <FieldDescription>Type 1250000: the grouping appears with each digit.</FieldDescription>
+      </Field>
+      <Field>
+        <FieldLabel>Amount from bank statement</FieldLabel>
+        <NumberField format={{ currency: 'USD', style: 'currency' }} formatOn="commit" min={0} />
+        <FieldDescription>Your text stays as typed until Enter or blur.</FieldDescription>
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### handle.tsx
+
+Example
+
+```tsx
+import { useRef } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { NumberField, NumberFieldHandle } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldHandleExample() {
+  const cases = useRef<NumberFieldHandle>(null);
+
+  return (
+    <Stack gap={3}>
+      <Field>
+        <FieldLabel>Cases of Chang</FieldLabel>
+        <NumberField defaultValue={4} handle={cases} max={48} min={0} />
+      </Field>
+      <Inline gap={2}>
+        <Button onClick={() => cases.current?.decrement()} variant="outline">
+          Remove a case
+        </Button>
+        <Button onClick={() => cases.current?.increment()} variant="outline">
+          Add a case
+        </Button>
+      </Inline>
+    </Stack>
+  );
+}
+```
+
+### order-line.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Grid } from '@slotted/react/grid';
+import { Inline } from '@slotted/react/inline';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+import { Text } from '@slotted/react/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 },
+];
+
+export default function NumberFieldOrderLine() {
+  const [quantities, setQuantities] = useState<Record<string, number | null>>({
+    cabrales: 12,
+    hokkien: 10,
+    mozzarella: 5,
+  });
+
+  const total = LINES.reduce((sum, line) => sum + line.price * (quantities[line.id] ?? 0), 0);
+
+  return (
+    <Stack gap={5}>
+      <Stack gap={4}>
+        {LINES.map((line) => (
+          <Grid key={line.id} columns={3} gap={4} minItemWidth="xs">
+            <Stack gap={1}>
+              <Text weight="medium">{line.product}</Text>
+              <Text size="sm" tone="muted">
+                {USD.format(line.price)} each · {line.stock} in stock
+              </Text>
+            </Stack>
+            <Stack justify="center">
+              <NumberField
+                aria-label={`Quantity of ${line.product}`}
+                max={line.stock}
+                min={0}
+                onValueChange={(next) =>
+                  setQuantities((current) => ({ ...current, [line.id]: next }))
+                }
+                size="sm"
+                stepper="split"
+                value={quantities[line.id] ?? null}
+              />
+            </Stack>
+            <Stack justify="center">
+              <Text align="end" numeric="tabular">
+                {USD.format(line.price * (quantities[line.id] ?? 0))}
+              </Text>
+            </Stack>
+          </Grid>
+        ))}
+      </Stack>
+      <Inline gap={4} justify="between">
+        <Text weight="semibold">Order total</Text>
+        <Text numeric="tabular" weight="semibold">
+          {USD.format(total)}
+        </Text>
+      </Inline>
+    </Stack>
+  );
+}
+```
+
+### price-editor.tsx
+
+Example
+
+```tsx
+import { useState } from 'react';
+import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';
+import { Grid } from '@slotted/react/grid';
+import { NumberField } from '@slotted/react/number-field';
+
+const CURRENCY = { currency: 'USD', style: 'currency' } as const;
+
+export default function NumberFieldPriceEditor() {
+  const [cost, setCost] = useState<number | null>(175);
+  const [markup, setMarkup] = useState<number | null>(0.5);
+
+  const price =
+    cost === null || markup === null ? null : Math.round(cost * (1 + markup) * 100) / 100;
+
+  return (
+    <Grid gap={4} minItemWidth="xs">
+      <Field required>
+        <FieldLabel>Unit cost</FieldLabel>
+        <NumberField format={CURRENCY} min={0} onValueChange={setCost} step={0.5} value={cost} />
+      </Field>
+      <Field required>
+        <FieldLabel>Markup</FieldLabel>
+        <NumberField
+          format={{ style: 'percent' }}
+          largeStep={0.1}
+          max={3}
+          min={0}
+          onValueChange={setMarkup}
+          step={0.01}
+          value={markup}
+        />
+      </Field>
+      <Field readOnly>
+        <FieldLabel>List price</FieldLabel>
+        <NumberField format={CURRENCY} stepper="none" value={price} />
+        <FieldDescription>Unit cost plus markup.</FieldDescription>
+      </Field>
+    </Grid>
+  );
+}
+```
+
+### steppers.tsx
+
+Example
+
+```tsx
+import { Field, FieldLabel } from '@slotted/react/field';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldSteppers() {
+  return (
+    <Stack gap={4}>
+      <Field>
+        <FieldLabel>Reorder quantity</FieldLabel>
+        <NumberField defaultValue={40} min={0} step={10} stepper="stacked" />
+      </Field>
+      <Field>
+        <FieldLabel>Quantity</FieldLabel>
+        <NumberField defaultValue={3} max={99} min={1} stepper="split" />
+      </Field>
+      <Field>
+        <FieldLabel>Units in stock</FieldLabel>
+        <NumberField defaultValue={39} min={0} stepper="none" />
+      </Field>
+    </Stack>
+  );
+}
+```
+
+### validation.tsx
+
+Example
+
+```tsx
+import { useState, type SubmitEvent } from 'react';
+import { Button } from '@slotted/react/button';
+import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';
+import { Inline } from '@slotted/react/inline';
+import { NumberField } from '@slotted/react/number-field';
+import { Stack } from '@slotted/react/stack';
+
+export default function NumberFieldValidation() {
+  const [quantity, setQuantity] = useState<number | null>(null);
+  const [submitted, setSubmitted] = useState(false);
+  const [sent, setSent] = useState('');
+
+  const error = submitted && quantity === null ? 'Enter how many units to ship.' : '';
+
+  const submit = (event: SubmitEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    setSubmitted(true);
+    const data = new FormData(event.currentTarget);
+    setSent(quantity === null ? '' : `Sent quantity=${String(data.get('quantity'))}`);
+  };
+
+  return (
+    <form noValidate onSubmit={submit}>
+      <Stack gap={4}>
+        <Field required invalid={error !== '' ? true : undefined}>
+          <FieldLabel>Units of Chai to ship</FieldLabel>
+          <NumberField
+            max={39}
+            min={1}
+            name="quantity"
+            onValueChange={(next) => {
+              setQuantity(next);
+              setSent('');
+            }}
+            value={quantity}
+          />
+          <FieldDescription>39 units in stock.</FieldDescription>
+          <FieldError live="polite" reserve>
+            {error}
+          </FieldError>
+        </Field>
+        <Inline gap={3}>
+          <Button type="submit">Create shipment</Button>
+          {sent === '' ? null : <span role="status">{sent}</span>}
+        </Inline>
+      </Stack>
+    </form>
+  );
+}
+```