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

package/dist/docs/number-field.json

@@ -0,0 +1,669 @@
+{
+  "family": "number-field",
+  "ui": "number-field",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Number input with steppers and formatting."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "stepper": [
+      "stacked",
+      "split",
+      "none"
+    ],
+    "clamp": [
+      "blur",
+      "strict",
+      "none"
+    ],
+    "formatOn": [
+      "change",
+      "commit"
+    ]
+  },
+  "members": {
+    "numberField": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "stepper": "stacked",
+        "step": 1,
+        "clamp": "blur",
+        "formatOn": "change",
+        "snapToStep": false,
+        "wheel": false
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "content",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "invalid",
+        "readonly"
+      ],
+      "parts": [
+        "root",
+        "input",
+        "start",
+        "end",
+        "scrub",
+        "stepper",
+        "decrement",
+        "increment"
+      ]
+    }
+  },
+  "docs": {
+    "numberField": {
+      "imports": {
+        "source": "import { NumberField, NumberFieldDefaultsProvider, NumberFieldScrub } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The frame. It carries data-ui=\"number-field\", data-size, data-variant and data-stepper, and data-disabled, data-invalid, data-readonly and data-scrubbing while they apply. It has no role: a spinbutton may hold only non-interactive children, so the two buttons are siblings of the input inside a box that announces nothing. className and style reach this element."
+        },
+        {
+          "part": "input",
+          "element": "input[type=text][role=spinbutton]",
+          "required": true,
+          "purpose": "The control. It holds the formatted text, the id, and aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext. It is type=\"text\" because type=\"number\" empties itself whenever the text is not a plain decimal number, so no grouping separator or currency symbol would survive it. ref reaches this element."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "Content before the value in the reading direction. It sits beside the number and is never selected, copied or parsed with it. A symbol that belongs inside the value comes from format instead."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "Content after the value in the reading direction, such as a unit or a currency code."
+        },
+        {
+          "part": "scrub",
+          "element": "span (NumberFieldScrub)",
+          "required": false,
+          "purpose": "A mark in start or end that moves the value when it is dragged sideways: one step per sensitivity pixels towards the inline end, largeStep with Shift and smallStep with Alt. The mark and the frame carry data-scrubbing while it is dragged. It is hidden from assistive technology, because the arrow keys in the input make the same change."
+        },
+        {
+          "part": "stepper",
+          "element": "span",
+          "required": false,
+          "purpose": "The column that holds both buttons under stepper=\"stacked\", inset from the frame and drawn without a border of its own; each button takes the inset back as hit area. It is not rendered under split, where the buttons are direct children of the frame."
+        },
+        {
+          "part": "decrement",
+          "element": "button[type=button][tabindex=-1]",
+          "required": false,
+          "purpose": "Steps down by step, by largeStep with Shift and by smallStep with Alt, and repeats while it is held. It is disabled at min, and it is out of the tab order because the arrow keys in the input make the same change."
+        },
+        {
+          "part": "increment",
+          "element": "button[type=button][tabindex=-1]",
+          "required": false,
+          "purpose": "Steps up by the same amounts and is disabled at max. Both buttons carry a translatable accessible name and aria-controls pointing at the input."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "number | null",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Makes the value controlled for the life of the component. null is empty, and empty is not zero: a required amount left blank and an amount of zero are different values."
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "The value an uncontrolled number field starts from. It is read once, and a native form reset returns to it."
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "The smallest value. The decrement button is disabled at it, Home moves to it, and the snapToStep grid is counted from it."
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "The largest value. The increment button is disabled at it, and End moves to it."
+        },
+        {
+          "name": "step",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "NumberField",
+          "description": "What the arrow keys and the two buttons add or subtract."
+        },
+        {
+          "name": "largeStep",
+          "type": "number",
+          "defaultValue": "step × 10",
+          "appliesTo": "NumberField",
+          "description": "What Shift with an arrow, Page Up and Page Down add or subtract, so a wide range is crossed without holding a key."
+        },
+        {
+          "name": "smallStep",
+          "type": "number",
+          "defaultValue": "step ÷ 10",
+          "appliesTo": "NumberField",
+          "description": "What Alt with an arrow adds or subtracts."
+        },
+        {
+          "name": "stepFrom",
+          "type": "number",
+          "defaultValue": "min, or 0",
+          "appliesTo": "NumberField",
+          "description": "The value the first step produces when the number field is empty."
+        },
+        {
+          "name": "snapToStep",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "NumberField",
+          "description": "Steps to multiples of step counted from min, so with min 2 and step 3 the values are 2, 5, 8 and 11. A typed value moves to the nearest multiple when the number field commits."
+        },
+        {
+          "name": "clamp",
+          "type": "'blur' | 'strict' | 'none'",
+          "defaultValue": "blur",
+          "appliesTo": "NumberField, NumberFieldDefaultsProvider",
+          "description": "What happens to a value outside min and max. blur returns it to the range when the number field commits, strict refuses the keystroke that would leave the range, and none keeps the value and sets aria-invalid and data-invalid while it is out of range."
+        },
+        {
+          "name": "format",
+          "type": "Intl.NumberFormatOptions",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "How the value is written and read back. Currency, percent and unit are formats of one number, and precision is set with minimumFractionDigits and maximumFractionDigits. When the number field commits, the number is rounded to the precision the input shows."
+        },
+        {
+          "name": "formatOn",
+          "type": "'change' | 'commit'",
+          "defaultValue": "change",
+          "appliesTo": "NumberField, NumberFieldDefaultsProvider",
+          "description": "When the text takes the format. change regroups it on every keystroke; commit keeps the typed text until blur, Enter, a stepper press or an arrow key. Under both, the number changes on every keystroke that parses."
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the locale of SlottedProvider, then en-US",
+          "appliesTo": "NumberField",
+          "description": "A BCP 47 tag. It sets the decimal separator, the grouping and the digits, for the text written and the text read back."
+        },
+        {
+          "name": "stepper",
+          "type": "'stacked' | 'split' | 'none'",
+          "defaultValue": "stacked",
+          "appliesTo": "NumberField, NumberFieldDefaultsProvider",
+          "description": "Where the two buttons sit. split places them at either end of the frame, and its targets are at least 24 CSS pixels in both directions; none removes them."
+        },
+        {
+          "name": "wheel",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "NumberField",
+          "description": "Lets the mouse wheel step the value while the input has focus and the pointer is over it. It is off by default, so scrolling a form never changes an amount."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "NumberField, NumberFieldDefaultsProvider",
+          "description": "The step of the control scale. When unset, the number field takes the size of its field, then of the provider. Height, padding, type and glyphs come from the control scale the theme sets per density."
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "NumberField, NumberFieldDefaultsProvider",
+          "description": "How much frame the number field draws. plain draws no border at rest and keeps the same box, for a dense table cell."
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Content before the value in the reading direction. It is never selected, copied or parsed with the number."
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Content after the value in the reading direction."
+        },
+        {
+          "name": "NumberFieldScrub sensitivity",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "NumberFieldScrub",
+          "description": "Pixels of horizontal drag per step. Use fewer pixels for a wide range and more for a fine one."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "NumberField",
+          "description": "Unset rather than false, so the number field follows the field around it. When set, it wins over the field and writes the native disabled, which removes the input from the tab order and from form submission."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "NumberField",
+          "description": "Unset rather than false, so the number field follows the field around it. Writes the native readonly: the input stays focusable, selectable and submitted, and both buttons are disabled."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "NumberField",
+          "description": "Unset rather than false, so the number field follows the field around it. Writes aria-invalid on the input and data-invalid on the frame."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "The element’s own attribute, passed through unchanged; NumberField never writes it. Inside a required field, the input receives aria-required instead, because the native attribute turns on the browser’s constraint validation."
+        },
+        {
+          "name": "name / form",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Reach a hidden input beside the visible one, which submits the raw number: 1480, not \"$1,480.00\"."
+        },
+        {
+          "name": "messages",
+          "type": "Partial<NumberFieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Replaces words of the active language, key by key: increment and decrement are the accessible names of the two buttons."
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: NumberFieldRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Renders another element in place of the frame and passes it every attribute. The props are typed as HTMLAttributes<HTMLElement>, so they spread onto any element. The input and the two buttons cannot be replaced."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Reaches the input element. focus(), select() and setSelectionRange() are the element’s own."
+        },
+        {
+          "name": "handle",
+          "type": "Ref<NumberFieldHandle>",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Reaches increment() and decrement(), for a shortcut or a button elsewhere on the page. Both move by one step within the bounds and report the reason programmatic."
+        },
+        {
+          "name": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "NumberField",
+          "description": "Reach the frame. Every other native prop reaches the input."
+        },
+        {
+          "name": "NumberFieldDefaultsProvider",
+          "type": "{ size, variant, stepper, formatOn, clamp }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets size, variant, stepper, formatOn and clamp once for every number field under it. A number field that states a value keeps it. The locale comes from SlottedProvider, so every amount in the application is written and read the same way."
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What the number field reads to wire itself: the id, the description and the four shared states."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: number | null, request: ChangeRequest<number | null>)",
+          "when": "Before the value changes. request.value is the new number and request.previous the number it replaces. request.reason is keyboard for typing, an arrow, a page key, Home, End or Enter; pointer for a stepper press, a wheel turn or a scrub; blur for the commit that formats, rounds and clamps on blur; programmatic for handle.increment() and handle.decrement(). request.source is the originating event, and request.cancel() refuses the change before it is applied. A request for the number NumberField already holds is not emitted."
+        },
+        {
+          "name": "onChange, onBlur, onKeyDown, onFocus",
+          "payload": "the element’s own events",
+          "when": "Whenever the input fires them. NumberField composes your handler with its own instead of replacing it: yours runs first and always runs, and calling preventDefault() on a key stops NumberField from acting on it."
+        }
+      ],
+      "accessibility": [
+        "NumberField follows the WAI-ARIA APG Spinbutton pattern: role=\"spinbutton\" on the input with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext, ArrowUp and ArrowDown to step, Home and End to reach the bounds, and Page Up and Page Down for the larger step.",
+        "aria-valuetext carries the formatted text, so a screen reader announces \"$1,480.00\" rather than 1480. When the number field is empty, neither aria-valuenow nor aria-valuetext is set: no value is not the value zero.",
+        "The frame has no role. WAI-ARIA requires the children of a spinbutton to be non-interactive, so the two buttons are siblings of the input inside a box that announces nothing.",
+        "The buttons are out of the tab order, as the APG pattern recommends, and stay in the accessibility tree with translatable names and aria-controls pointing at the input. A form of twenty amounts keeps twenty tab stops instead of sixty. A button at a bound is disabled, so its name is still announced and its appearance shows why it does nothing.",
+        "Inside a required field the input receives aria-required, never the native required, which would turn on the browser’s constraint validation. disabled and readonly are the native attributes.",
+        "The input is type=\"text\", and its inputMode comes from the props: numeric for a whole number at or above zero, decimal when the format allows a fraction, and text when min allows a negative, because neither numeric keypad offers a minus sign on every platform.",
+        "The mouse wheel is not bound unless wheel is set, and Escape is not bound at all, so scrolling a form never changes an amount.",
+        "The invalid state is never conveyed by color alone: aria-invalid announces it and the field’s error states it in words. In the high-contrast scheme the border does not carry it."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-control-border-color",
+    "--slotted-control-border-width",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-lg",
+    "--slotted-control-height-md",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-lg",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-inner-size-lg",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-inner-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-padding-inline-lg",
+    "--slotted-control-padding-inline-md",
+    "--slotted-control-padding-inline-sm",
+    "--slotted-control-radius",
+    "--slotted-control-shadow",
+    "--slotted-control-shadow-focus-geometry",
+    "--slotted-control-surface",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-number-field-action-size",
+    "--slotted-number-field-adornment-color",
+    "--slotted-number-field-background",
+    "--slotted-number-field-border-color",
+    "--slotted-number-field-color",
+    "--slotted-number-field-disabled-background",
+    "--slotted-number-field-disabled-border-color",
+    "--slotted-number-field-disabled-color",
+    "--slotted-number-field-hover-border-color",
+    "--slotted-number-field-icon-size-min",
+    "--slotted-number-field-invalid-border-color",
+    "--slotted-number-field-invalid-edge-width",
+    "--slotted-number-field-invalid-focus-ring-color",
+    "--slotted-number-field-placeholder-color",
+    "--slotted-number-field-plain-hover-background",
+    "--slotted-number-field-radius",
+    "--slotted-number-field-readonly-background",
+    "--slotted-number-field-readonly-border-color",
+    "--slotted-number-field-scrub-active-color",
+    "--slotted-number-field-shadow",
+    "--slotted-number-field-stepper-active-background",
+    "--slotted-number-field-stepper-color",
+    "--slotted-number-field-stepper-disabled-background",
+    "--slotted-number-field-stepper-disabled-color",
+    "--slotted-number-field-stepper-hover-background",
+    "--slotted-number-field-stepper-size",
+    "--slotted-number-field-subtle-background",
+    "--slotted-number-field-subtle-border-color",
+    "--slotted-number-field-subtle-hover-background",
+    "--slotted-radius-none",
+    "--slotted-radius-xs",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-surface-sunken",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-border",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Quantidade</FieldLabel>\n  <NumberField defaultValue={3} max={99} min={1} />\n  <FieldDescription>Máximo de 99 unidades por pedido.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the control sits at",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldSizes() {\n  return (\n    <Stack gap={4}>\n      <NumberField aria-label=\"Units per case\" defaultValue={24} min={1} size=\"sm\" />\n      <NumberField aria-label=\"Cases ordered\" defaultValue={12} min={1} size=\"md\" />\n      <NumberField aria-label=\"Pallets ordered\" defaultValue={2} min={1} size=\"lg\" />\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "variants",
+      "title": "How much frame the control shows",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldVariants() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Unit price</FieldLabel>\n        <NumberField\n          defaultValue={18}\n          format={{ currency: 'USD', style: 'currency' }}\n          min={0}\n          variant=\"outline\"\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Discount</FieldLabel>\n        <NumberField\n          defaultValue={0.05}\n          format={{ style: 'percent' }}\n          max={1}\n          min={0}\n          step={0.01}\n          variant=\"subtle\"\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Freight</FieldLabel>\n        <NumberField\n          defaultValue={32.38}\n          format={{ currency: 'USD', style: 'currency' }}\n          min={0}\n          stepper=\"none\"\n          variant=\"plain\"\n        />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "stepper",
+      "title": "Where the two buttons sit, and whether they sit at all",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<NumberField defaultValue={12} stepper=\"stacked\" />;\n\n// The arrangement a thumb can hit, and the one a quantity wants.\n<NumberField defaultValue={3} max={99} min={1} stepper=\"split\" />;\n\n// Typed and never spun, which is what a dense table asks for.\n<NumberField defaultValue={1480} stepper=\"none\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range",
+      "title": "The bounds, the step, and what happens at the edge",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldRange() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Pallets on the trailer</FieldLabel>\n        <NumberField defaultValue={26} max={26} min={0} />\n        <FieldDescription>A 53-foot trailer holds 26 pallets.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Bottles of Chartreuse verte</FieldLabel>\n        <NumberField defaultValue={12} min={6} snapToStep step={6} />\n        <FieldDescription>Sold in cases of 6. Type 20 and leave the field.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "format",
+      "title": "Currency, percent and unit are formattings, not types",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldFormat() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Credit limit</FieldLabel>\n        <NumberField\n          defaultValue={25000}\n          format={{ currency: 'USD', style: 'currency' }}\n          min={0}\n          step={500}\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Sales tax</FieldLabel>\n        <NumberField\n          defaultValue={0.0825}\n          format={{ maximumFractionDigits: 2, style: 'percent' }}\n          max={1}\n          min={0}\n          step={0.0025}\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Pallet volume</FieldLabel>\n        <NumberField\n          defaultValue={1.8}\n          format={{ style: 'unit', unit: 'liter', unitDisplay: 'long' }}\n          min={0}\n          step={0.1}\n        />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "formatOn",
+      "title": "When the grouping appears",
+      "note": "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.",
+      "language": "tsx",
+      "source": "// The default. The caret stays on the character it was on, because it is\n// counted in the reader's own characters rather than in string indices.\n<NumberField locale=\"pt-BR\" />;\n\n// The reader's own text until blur, Enter, a stepper press or a key step.\n// For an amount that is pasted and audited rather than typed.\n<NumberField formatOn=\"commit\" locale=\"pt-BR\" />;\n\n// Rounding and padding belong to the commit under both: 1,50 keeps its\n// nought while it is being typed, and 1, keeps its separator.\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locale",
+      "title": "The separator, the grouping and the numerals",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldLocale() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Invoice total, United States</FieldLabel>\n        <NumberField\n          defaultValue={14800.5}\n          format={{ currency: 'USD', style: 'currency' }}\n          locale=\"en-US\"\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Invoice total, Germany</FieldLabel>\n        <NumberField\n          defaultValue={14800.5}\n          format={{ currency: 'EUR', style: 'currency' }}\n          locale=\"de-DE\"\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Invoice total, Egypt</FieldLabel>\n        <NumberField\n          defaultValue={14800.5}\n          format={{ currency: 'EGP', style: 'currency' }}\n          locale=\"ar-EG\"\n        />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "adornments",
+      "title": "What sits beside the number",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldAdornments() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Purchase price</FieldLabel>\n        <NumberField\n          defaultValue={1480}\n          end=\"USD\"\n          format={{ minimumFractionDigits: 2 }}\n          min={0}\n          start=\"$\"\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Lead time</FieldLabel>\n        <NumberField defaultValue={14} end=\"days\" max={120} min={0} />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "scrub",
+      "title": "Drag the mark to move the number",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Grid } from '@slotted/react/grid';\nimport { NumberField, NumberFieldScrub } from '@slotted/react/number-field';\n\nexport default function NumberFieldScrubExample() {\n  return (\n    <Grid columns={2} gap={4}>\n      <Field>\n        <FieldLabel>Label width</FieldLabel>\n        <NumberField\n          defaultValue={100}\n          end=\"mm\"\n          max={210}\n          min={20}\n          start={<NumberFieldScrub>W</NumberFieldScrub>}\n        />\n      </Field>\n      <Field>\n        <FieldLabel>Label height</FieldLabel>\n        <NumberField\n          defaultValue={150}\n          end=\"mm\"\n          max={297}\n          min={20}\n          start={<NumberFieldScrub sensitivity={4}>H</NumberFieldScrub>}\n        />\n      </Field>\n    </Grid>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "The states the frame paints",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldStates() {\n  return (\n    <Stack gap={5}>\n      <Field invalid>\n        <FieldLabel>Quantity to ship</FieldLabel>\n        <NumberField defaultValue={120} min={1} />\n        <FieldError>Only 39 units of Chai are in stock.</FieldError>\n      </Field>\n      <Field readOnly>\n        <FieldLabel>Units on order</FieldLabel>\n        <NumberField defaultValue={40} />\n        <FieldDescription>Counted from open purchase orders.</FieldDescription>\n      </Field>\n      <Field disabled>\n        <FieldLabel>Units reserved</FieldLabel>\n        <NumberField defaultValue={12} />\n        <FieldDescription>Released when the order ships.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "content",
+      "title": "Numbers the family did not choose",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<NumberField defaultValue={1480320559774.25} locale=\"pt-BR\" />;\n\n// The digits are tabular, so nothing shifts as they are typed over,\n// and the minus stays in front of the amount in an Arabic document.\n<NumberField defaultValue={-1480} end=\"BRL\" locale=\"pt-BR\" start=\"R$\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, reaching past it, and putting it in a form",
+      "note": "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.",
+      "language": "tsx",
+      "source": "<NumberFieldDefaultsProvider stepper=\"split\">\n  <NumberField defaultValue={3} />\n</NumberFieldDefaultsProvider>;\n\nconst handle = useRef<NumberFieldHandle>(null);\n<NumberField handle={handle} />;\n<Button onClick={() => handle.current?.increment()}>Mais um</Button>;\n\n// The hidden input carries 1480, never \"R$ 1.480,00\".\n<NumberField format={{ currency: 'BRL', style: 'currency' }} name=\"amount\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and what it deliberately does not",
+      "note": "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.",
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldKeyboard() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Shipping weight</FieldLabel>\n        <NumberField\n          defaultValue={12.5}\n          format={{ maximumFractionDigits: 1, style: 'unit', unit: 'kilogram' }}\n          largeStep={10}\n          min={0}\n          smallStep={0.1}\n          step={1}\n        />\n        <FieldDescription>Arrows: 1 kg. Shift or Page keys: 10 kg. Alt: 0.1 kg.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Safety stock</FieldLabel>\n        <NumberField defaultValue={15} min={0} wheel />\n        <FieldDescription>\n          With the field focused, the mouse wheel steps the value.\n        </FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\n\nexport default function NumberFieldBasic() {\n  return (\n    <Field required>\n      <FieldLabel>Reorder point</FieldLabel>\n      <NumberField defaultValue={25} end=\"units\" max={500} min={0} step={5} />\n      <FieldDescription>Chai is reordered when stock falls to this level.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "clamp",
+      "title": "clamp.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldClamp() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Line discount</FieldLabel>\n        <NumberField clamp=\"blur\" defaultValue={10} end=\"%\" max={25} min={0} />\n        <FieldDescription>Type 40 and leave the field: it returns to 25.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Order discount</FieldLabel>\n        <NumberField clamp=\"strict\" defaultValue={10} end=\"%\" max={25} min={0} />\n        <FieldDescription>A keystroke that would pass 25 is refused.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Contract discount</FieldLabel>\n        <NumberField clamp=\"none\" defaultValue={10} end=\"%\" max={25} min={0} />\n        <FieldDescription>40 stays, and the field is marked invalid.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nconst USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });\n\nexport default function NumberFieldControlled() {\n  const [limit, setLimit] = useState<number | null>(5000);\n\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Credit limit for Ernst Handel</FieldLabel>\n        <NumberField\n          format={{ currency: 'USD', style: 'currency' }}\n          min={0}\n          onValueChange={setLimit}\n          step={500}\n          stepFrom={5000}\n          value={limit}\n        />\n      </Field>\n      <Inline gap={3} justify=\"between\">\n        <span>{limit === null ? 'No credit limit' : `Orders up to ${USD.format(limit)}`}</span>\n        <Button disabled={limit === null} onClick={() => setLimit(null)} variant=\"outline\">\n          Remove limit\n        </Button>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "decimals",
+      "title": "decimals.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldDecimals() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Exchange rate, EUR to USD</FieldLabel>\n        <NumberField\n          defaultValue={1.0842}\n          format={{ maximumFractionDigits: 4, minimumFractionDigits: 4 }}\n          min={0}\n          step={0.0001}\n        />\n        <FieldDescription>Four decimals: 1.1 becomes 1.1000 on blur.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Cartons</FieldLabel>\n        <NumberField defaultValue={40} format={{ maximumFractionDigits: 0 }} min={0} />\n        <FieldDescription>Whole cartons: the decimal separator is refused.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { Grid } from '@slotted/react/grid';\nimport { NumberField, NumberFieldDefaultsProvider } from '@slotted/react/number-field';\n\nexport default function NumberFieldDefaults() {\n  return (\n    <NumberFieldDefaultsProvider size=\"sm\" stepper=\"split\" variant=\"subtle\">\n      <Grid gap={3} minItemWidth=\"xs\">\n        <Field>\n          <FieldLabel>Cases</FieldLabel>\n          <NumberField defaultValue={6} min={0} />\n        </Field>\n        <Field>\n          <FieldLabel>Loose units</FieldLabel>\n          <NumberField defaultValue={11} min={0} />\n        </Field>\n        <Field>\n          <FieldLabel>Pallets</FieldLabel>\n          <NumberField defaultValue={1} min={0} stepper=\"stacked\" />\n        </Field>\n      </Grid>\n    </NumberFieldDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "format-on",
+      "title": "format-on.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldFormatOn() {\n  return (\n    <Stack gap={5}>\n      <Field>\n        <FieldLabel>Annual purchase budget</FieldLabel>\n        <NumberField format={{ currency: 'USD', style: 'currency' }} formatOn=\"change\" min={0} />\n        <FieldDescription>Type 1250000: the grouping appears with each digit.</FieldDescription>\n      </Field>\n      <Field>\n        <FieldLabel>Amount from bank statement</FieldLabel>\n        <NumberField format={{ currency: 'USD', style: 'currency' }} formatOn=\"commit\" min={0} />\n        <FieldDescription>Your text stays as typed until Enter or blur.</FieldDescription>\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "handle",
+      "title": "handle.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useRef } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { NumberField, NumberFieldHandle } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldHandleExample() {\n  const cases = useRef<NumberFieldHandle>(null);\n\n  return (\n    <Stack gap={3}>\n      <Field>\n        <FieldLabel>Cases of Chang</FieldLabel>\n        <NumberField defaultValue={4} handle={cases} max={48} min={0} />\n      </Field>\n      <Inline gap={2}>\n        <Button onClick={() => cases.current?.decrement()} variant=\"outline\">\n          Remove a case\n        </Button>\n        <Button onClick={() => cases.current?.increment()} variant=\"outline\">\n          Add a case\n        </Button>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "order-line",
+      "title": "order-line.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Grid } from '@slotted/react/grid';\nimport { Inline } from '@slotted/react/inline';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\nimport { Text } from '@slotted/react/typography';\n\nconst USD = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' });\n\nconst LINES = [\n  { id: 'cabrales', product: 'Queso Cabrales', price: 14, stock: 22 },\n  { id: 'hokkien', product: 'Singaporean Hokkien Fried Mee', price: 9.8, stock: 26 },\n  { id: 'mozzarella', product: 'Mozzarella di Giovanni', price: 34.8, stock: 14 },\n];\n\nexport default function NumberFieldOrderLine() {\n  const [quantities, setQuantities] = useState<Record<string, number | null>>({\n    cabrales: 12,\n    hokkien: 10,\n    mozzarella: 5,\n  });\n\n  const total = LINES.reduce((sum, line) => sum + line.price * (quantities[line.id] ?? 0), 0);\n\n  return (\n    <Stack gap={5}>\n      <Stack gap={4}>\n        {LINES.map((line) => (\n          <Grid key={line.id} columns={3} gap={4} minItemWidth=\"xs\">\n            <Stack gap={1}>\n              <Text weight=\"medium\">{line.product}</Text>\n              <Text size=\"sm\" tone=\"muted\">\n                {USD.format(line.price)} each · {line.stock} in stock\n              </Text>\n            </Stack>\n            <Stack justify=\"center\">\n              <NumberField\n                aria-label={`Quantity of ${line.product}`}\n                max={line.stock}\n                min={0}\n                onValueChange={(next) =>\n                  setQuantities((current) => ({ ...current, [line.id]: next }))\n                }\n                size=\"sm\"\n                stepper=\"split\"\n                value={quantities[line.id] ?? null}\n              />\n            </Stack>\n            <Stack justify=\"center\">\n              <Text align=\"end\" numeric=\"tabular\">\n                {USD.format(line.price * (quantities[line.id] ?? 0))}\n              </Text>\n            </Stack>\n          </Grid>\n        ))}\n      </Stack>\n      <Inline gap={4} justify=\"between\">\n        <Text weight=\"semibold\">Order total</Text>\n        <Text numeric=\"tabular\" weight=\"semibold\">\n          {USD.format(total)}\n        </Text>\n      </Inline>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "price-editor",
+      "title": "price-editor.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\nimport { Grid } from '@slotted/react/grid';\nimport { NumberField } from '@slotted/react/number-field';\n\nconst CURRENCY = { currency: 'USD', style: 'currency' } as const;\n\nexport default function NumberFieldPriceEditor() {\n  const [cost, setCost] = useState<number | null>(175);\n  const [markup, setMarkup] = useState<number | null>(0.5);\n\n  const price =\n    cost === null || markup === null ? null : Math.round(cost * (1 + markup) * 100) / 100;\n\n  return (\n    <Grid gap={4} minItemWidth=\"xs\">\n      <Field required>\n        <FieldLabel>Unit cost</FieldLabel>\n        <NumberField format={CURRENCY} min={0} onValueChange={setCost} step={0.5} value={cost} />\n      </Field>\n      <Field required>\n        <FieldLabel>Markup</FieldLabel>\n        <NumberField\n          format={{ style: 'percent' }}\n          largeStep={0.1}\n          max={3}\n          min={0}\n          onValueChange={setMarkup}\n          step={0.01}\n          value={markup}\n        />\n      </Field>\n      <Field readOnly>\n        <FieldLabel>List price</FieldLabel>\n        <NumberField format={CURRENCY} stepper=\"none\" value={price} />\n        <FieldDescription>Unit cost plus markup.</FieldDescription>\n      </Field>\n    </Grid>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "steppers",
+      "title": "steppers.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Field, FieldLabel } from '@slotted/react/field';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldSteppers() {\n  return (\n    <Stack gap={4}>\n      <Field>\n        <FieldLabel>Reorder quantity</FieldLabel>\n        <NumberField defaultValue={40} min={0} step={10} stepper=\"stacked\" />\n      </Field>\n      <Field>\n        <FieldLabel>Quantity</FieldLabel>\n        <NumberField defaultValue={3} max={99} min={1} stepper=\"split\" />\n      </Field>\n      <Field>\n        <FieldLabel>Units in stock</FieldLabel>\n        <NumberField defaultValue={39} min={0} stepper=\"none\" />\n      </Field>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Field, FieldDescription, FieldError, FieldLabel } from '@slotted/react/field';\nimport { Inline } from '@slotted/react/inline';\nimport { NumberField } from '@slotted/react/number-field';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function NumberFieldValidation() {\n  const [quantity, setQuantity] = useState<number | null>(null);\n  const [submitted, setSubmitted] = useState(false);\n  const [sent, setSent] = useState('');\n\n  const error = submitted && quantity === null ? 'Enter how many units to ship.' : '';\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n    const data = new FormData(event.currentTarget);\n    setSent(quantity === null ? '' : `Sent quantity=${String(data.get('quantity'))}`);\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <Field required invalid={error !== '' ? true : undefined}>\n          <FieldLabel>Units of Chai to ship</FieldLabel>\n          <NumberField\n            max={39}\n            min={1}\n            name=\"quantity\"\n            onValueChange={(next) => {\n              setQuantity(next);\n              setSent('');\n            }}\n            value={quantity}\n          />\n          <FieldDescription>39 units in stock.</FieldDescription>\n          <FieldError live=\"polite\" reserve>\n            {error}\n          </FieldError>\n        </Field>\n        <Inline gap={3}>\n          <Button type=\"submit\">Create shipment</Button>\n          {sent === '' ? null : <span role=\"status\">{sent}</span>}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}