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

package/dist/docs/currency-field.json

@@ -0,0 +1,649 @@
+{
+  "family": "currency-field",
+  "ui": "currency-field",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Number input for amounts in a currency."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "outline",
+      "subtle",
+      "plain"
+    ],
+    "entry": [
+      "cents",
+      "natural"
+    ],
+    "align": [
+      "end",
+      "start"
+    ],
+    "stepper": [
+      "none",
+      "stacked",
+      "split"
+    ],
+    "clamp": [
+      "blur",
+      "strict",
+      "none"
+    ],
+    "currencyDisplay": [
+      "symbol",
+      "narrowSymbol",
+      "code",
+      "name",
+      "none"
+    ],
+    "formatOn": [
+      "change",
+      "commit"
+    ]
+  },
+  "members": {
+    "currencyField": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "outline",
+        "entry": "cents",
+        "align": "end",
+        "stepper": "none",
+        "step": 1,
+        "clamp": "blur",
+        "formatOn": "change",
+        "currencyDisplay": "symbol",
+        "wheel": false,
+        "allowEmpty": 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": {
+    "currencyField": {
+      "imports": {
+        "source": "import { CurrencyField, CurrencyFieldDefaultsProvider, CurrencyFieldScrub } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The frame. Carries data-ui=\"currency-field\", the five axes — data-size, data-variant, data-entry, data-align, data-stepper — and data-disabled, data-invalid and data-readonly. It has no role: a spinbutton may hold only non-interactive children, so the two steppers are the control’s siblings. className and style reach this element."
+        },
+        {
+          "part": "input",
+          "element": "input[type=text][role=spinbutton]",
+          "required": true,
+          "purpose": "The control. Holds the formatted amount, the identifier, aria-valuenow in major units and aria-valuetext as the reader sees it. It is type=\"text\" because type=\"number\" empties itself whenever the text is not a valid floating-point number, so no grouping separator and no currency symbol survives it. ref reaches it."
+        },
+        {
+          "part": "start",
+          "element": "span",
+          "required": false,
+          "purpose": "An adornment before the amount in the reading direction, and a sibling of it rather than part of it. A symbol here is never selected, never copied and never parsed; a symbol that belongs inside the amount is what currency and currencyDisplay write."
+        },
+        {
+          "part": "end",
+          "element": "span",
+          "required": false,
+          "purpose": "An adornment after the amount: a currency code, a period, or a consumer’s own currency picker until the select family exists."
+        },
+        {
+          "part": "scrub",
+          "element": "span (CurrencyFieldScrub)",
+          "required": false,
+          "purpose": "A mark in start or end that moves the amount when it is dragged sideways: one step per sensitivity pixels towards the inline end, largeStep with Shift, smallStep with Alt. It carries data-scrubbing while dragged, as the frame does, and is hidden from assistive technology because the arrow keys on the input are the same movement."
+        },
+        {
+          "part": "stepper",
+          "element": "span",
+          "required": false,
+          "purpose": "The column the two buttons share under stepper=\"stacked\". It is not rendered at all under stepper=\"none\", which is this family’s default, nor 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 — one major unit by default, not one cent — by largeStep with Shift and by smallStep with Alt. Held, it repeats. Disabled at min, and out of the tab order because the arrow keys reach the same behaviour from the control."
+        },
+        {
+          "part": "increment",
+          "element": "button[type=button][tabindex=-1]",
+          "required": false,
+          "purpose": "Steps up by the same three amounts, disabled at max. Both buttons carry a translatable name and aria-controls pointing at the amount they move."
+        }
+      ],
+      "api": [
+        {
+          "name": "currency",
+          "type": "string",
+          "defaultValue": "from the provider",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "An ISO 4217 code. It decides the symbol, the minor units and therefore how far a digit shifts under cents-first entry. Required here or on the provider: a field that guessed two minor digits would write ¥12,34"
+        },
+        {
+          "name": "currencyDisplay",
+          "type": "'symbol' | 'narrowSymbol' | 'code' | 'name'",
+          "defaultValue": "symbol",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "How the currency is written beside the amount, and none writes nothing at all: the amount becomes a plain decimal with the currency’s own fraction digits, so the symbol can live in a start adornment instead of inside the value. It is the one arrangement Intl has no option for"
+        },
+        {
+          "name": "value",
+          "type": "number | null",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Present means the consumer owns the amount, for the life of the component. It is in major units — reais, not centavos — and null is empty: a required total left blank and a total of nought are different facts"
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "What an uncontrolled control starts from, read once. A native form reset returns to it"
+        },
+        {
+          "name": "entry",
+          "type": "'cents' | 'natural'",
+          "defaultValue": "cents",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "How the reader types. cents is the cash register: digits enter at the minor unit and shift left, the separator is never typed and the caret has one legal position. natural is the spreadsheet, and the model number-field uses"
+        },
+        {
+          "name": "formatOn",
+          "type": "'change' | 'commit'",
+          "defaultValue": "change",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "When the text takes the locale’s shape under entry=\"natural\". change regroups on every keystroke; commit holds the reader’s own text until blur, Enter or a step. Cents-first entry generates the text after every edit, so it decides nothing there"
+        },
+        {
+          "name": "align",
+          "type": "'end' | 'start'",
+          "defaultValue": "end",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "Which edge the amount is set against. end by default: a column of amounts is compared on its last digit, and the cents-first caret already lives there"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "CurrencyField",
+          "description": "BCP 47. It decides the separators, where the symbol goes and the numbering system — never the symbol itself, which is the currency’s"
+        },
+        {
+          "name": "format",
+          "type": "Intl.NumberFormatOptions",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Any other Intl option: currencySign for accounting parentheses, signDisplay, useGrouping, roundingMode. Every key here wins over the family’s own; style and currency are the family’s"
+        },
+        {
+          "name": "fractionDigits",
+          "type": "number",
+          "defaultValue": "the currency’s minor units",
+          "appliesTo": "CurrencyField",
+          "description": "Overrides how many fraction digits the amount is written with, for a unit price quoted finer than the currency’s cent"
+        },
+        {
+          "name": "min",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "The smallest amount the control holds, in major units. It disables the decrement button at the bound, gives Home somewhere to go, and is the one thing that refuses a debit: min={0} is why there is no allowNegative"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "The largest amount the control holds. It disables the increment button at the bound and gives End somewhere to go"
+        },
+        {
+          "name": "step",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "CurrencyField",
+          "description": "What the arrows and the two buttons move by, in major units: one real, not one centavo"
+        },
+        {
+          "name": "largeStep",
+          "type": "number",
+          "defaultValue": "step * 10",
+          "appliesTo": "CurrencyField",
+          "description": "What Shift and the page keys move by"
+        },
+        {
+          "name": "smallStep",
+          "type": "number",
+          "defaultValue": "step / 10",
+          "appliesTo": "CurrencyField",
+          "description": "What Alt moves by"
+        },
+        {
+          "name": "stepFrom",
+          "type": "number",
+          "defaultValue": "min, or 0",
+          "appliesTo": "CurrencyField",
+          "description": "Where an empty control starts stepping from. Pressing increment on a blank amount produces the amount named here rather than that amount plus a step"
+        },
+        {
+          "name": "clamp",
+          "type": "'blur' | 'strict' | 'none'",
+          "defaultValue": "blur",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "Where an amount outside the range goes, and when. blur returns it at the commit, strict refuses the keystroke that would leave the range, none keeps it and reports aria-invalid"
+        },
+        {
+          "name": "allowEmpty",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CurrencyField",
+          "description": "Lets the control hold nothing. Off by default, because an amount is not an optional number: cleared, the control shows 0,00 and emits 0, and every consumer is spared writing value ?? 0. On, an emptied control stays empty and emits null"
+        },
+        {
+          "name": "wheel",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CurrencyField",
+          "description": "Lets the wheel move the amount while the control has focus and the pointer is over it. Off by default: a reader scrolling a form must not change a total by passing over it"
+        },
+        {
+          "name": "stepper",
+          "type": "'stacked' | 'split' | 'none'",
+          "defaultValue": "none",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "Where the two buttons sit, and whether they sit at all. none by default, where number-field ships them: an invoice total is typed rather than nudged"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "The type step, read from the field first when there is one, then from the provider. Height, padding, type and glyph all come from the control scales the theme restates per density"
+        },
+        {
+          "name": "variant",
+          "type": "'outline' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "CurrencyField, CurrencyFieldDefaultsProvider",
+          "description": "How much frame the control shows. plain paints no border at rest and keeps the same box, which is what a table of amounts needs"
+        },
+        {
+          "name": "start",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "An adornment before the amount in the reading direction. It is a sibling of the number: never selected, never copied and never parsed"
+        },
+        {
+          "name": "end",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "An adornment after the amount: a currency code, a period, or a consumer’s own currency picker"
+        },
+        {
+          "name": "CurrencyFieldScrub sensitivity",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "CurrencyFieldScrub",
+          "description": "Pixels of horizontal travel per step. A wide range wants fewer pixels per step; a fine one, more"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "CurrencyField",
+          "description": "Unstated rather than false, so the control defers to the field around it. Stated, it wins, and it is the native attribute: out of the tab order and out of submission"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "CurrencyField",
+          "description": "Unstated rather than false. The native readonly, which stays focusable, selectable and submitted, and which disables both steppers"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "CurrencyField",
+          "description": "Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "The element’s own attribute, passed straight through and never written by the family. A field marks necessity with aria-required instead, because the native attribute engages browser constraint validation"
+        },
+        {
+          "name": "name / form",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Reach a hidden input beside the visible one, which carries the raw number in major units. Submitting \"R$ 1.480,00\" to a server expecting 1480 is the defect this avoids"
+        },
+        {
+          "name": "autoComplete",
+          "type": "string",
+          "defaultValue": "off",
+          "appliesTo": "CurrencyField",
+          "description": "The element’s own attribute. transaction-amount is the standard autofill field name for a payment amount, and transaction-currency for the currency beside it; the default is off, because a browser offering to fill an invoice total is worse than no help at all"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<CurrencyFieldMessages>",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Words laid over the language in force, key by key: increment and decrement are what the two buttons announce"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: CurrencyFieldRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Substitutes the frame and hands it every attribute. The props are typed against HTMLAttributes<HTMLElement>, so they can be spread onto a label or a fieldset. The control and the two buttons are fixed: substituting the element that holds the amount and the role would leave the family with nothing to be"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLInputElement>",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Reaches the input. focus(), select() and setSelectionRange() are the element’s own, so no imperative handle is invented for what the platform already ships"
+        },
+        {
+          "name": "handle",
+          "type": "Ref<CurrencyFieldHandle>",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "increment() and decrement(), the two actions a consumer cannot express by passing a value. Both report reason \"programmatic\""
+        },
+        {
+          "name": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "CurrencyField",
+          "description": "Reach the frame, because the frame is what a consumer sees. Every other native prop reaches the input"
+        },
+        {
+          "name": "CurrencyFieldDefaultsProvider",
+          "type": "{ currency, currencyDisplay, entry, align, size, variant, stepper, clamp }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once. currency is the one worth setting first, and the only one a field cannot be built without: a product has one currency in nine screens out of ten, and the tenth states its own"
+        },
+        {
+          "name": "useField()",
+          "type": "() => FieldContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a Field",
+          "description": "What the control reads to wire itself: the identifier, the description and the four shared states. A control that wires itself cannot be written wrong"
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: number | null, request: CurrencyChangeRequest)",
+          "when": "Before the amount moves. The request carries the new amount in major units, the amount it replaces, the currency, minorUnits — the exact integer a payment API is charged in — the reason (\"keyboard\" for typing, an arrow, a page key, Home or End; \"pointer\" for a stepper press or a wheel turn; \"blur\" for the commit that formats and clamps; \"programmatic\" for handle.increment()), the originating event, and cancel(), which refuses the move before anything commits. A request for the amount the family already holds is not emitted."
+        },
+        {
+          "name": "onChange, onBlur, onKeyDown, onFocus",
+          "payload": "the element’s own events",
+          "when": "Whenever the element fires them. The family composes with a consumer’s handler rather than replacing it: the consumer’s runs first, always runs, and calling preventDefault() on a key stops the family from acting on it."
+        }
+      ],
+      "accessibility": [
+        "The pattern is the WAI-ARIA APG’s Spinbutton (w3.org/WAI/ARIA/apg/patterns/spinbutton/), taken whole: role=\"spinbutton\" on the focusable element with aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext, Up and Down stepping, Home and End reaching the bounds, and Page Up and Page Down as the larger step the pattern lists as optional.",
+        "aria-valuenow is the amount in major units and aria-valuetext is the string the reader sees, because aria-valuenow alone announces 1480 for a control showing R$ 1.480,00. When the control is empty neither property is set: no amount is not an amount of nought.",
+        "The frame carries no role. WAI-ARIA requires the children of a spinbutton to be non-interactive and presentational, so the two steppers are the control’s siblings inside a box that announces nothing.",
+        "Under cents-first entry the caret is put back after the last digit on every edit, and it decides nothing while it is anywhere else: a digit typed against the front of R$ 0,00 is two cents, not twenty reais, because the digits that changed are read from the difference between the text before the edit and the text after it. That is legal here and forbidden in number-field for one reason: the text is generated rather than typed, so there is no reader’s caret to preserve and exactly one position where the next keystroke means something. A separator keystroke is refused outright rather than silently swallowed, and the sign is a key of its own so it never enters the digit run.",
+        "inputMode is numeric under cents-first entry — the separator is never typed and the sign is a single key, so the numeric keypad is complete for the task — and derived from the format under natural entry. It is never derived from the user agent, which would be a hydration mismatch.",
+        "aria-required, never the native required. The native attribute engages browser constraint validation and changes submit behaviour, which the library must not impose as a side effect of describing a field. disabled and readonly are native, because that is what those two words mean.",
+        "transaction-amount and transaction-currency are the standard autofill field names for a payment amount, and naming a field’s purpose is what WCAG 2.2 SC 1.3.5 asks for. The family leaves autoComplete off by default and documents the token, because most amounts in a back office are not payment amounts.",
+        "The invalid state is never colour alone: aria-invalid announces it and the field’s error says it in words. In the high-contrast scheme the border cannot carry it at all, which is why it never has to."
+      ]
+    }
+  },
+  "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-currency-field-action-size",
+    "--slotted-currency-field-adornment-color",
+    "--slotted-currency-field-background",
+    "--slotted-currency-field-border-color",
+    "--slotted-currency-field-color",
+    "--slotted-currency-field-disabled-background",
+    "--slotted-currency-field-disabled-border-color",
+    "--slotted-currency-field-disabled-color",
+    "--slotted-currency-field-hover-border-color",
+    "--slotted-currency-field-icon-size-min",
+    "--slotted-currency-field-invalid-border-color",
+    "--slotted-currency-field-invalid-edge-width",
+    "--slotted-currency-field-invalid-focus-ring-color",
+    "--slotted-currency-field-placeholder-color",
+    "--slotted-currency-field-plain-hover-background",
+    "--slotted-currency-field-radius",
+    "--slotted-currency-field-readonly-background",
+    "--slotted-currency-field-readonly-border-color",
+    "--slotted-currency-field-scrub-active-color",
+    "--slotted-currency-field-shadow",
+    "--slotted-currency-field-stepper-active-background",
+    "--slotted-currency-field-stepper-color",
+    "--slotted-currency-field-stepper-disabled-background",
+    "--slotted-currency-field-stepper-disabled-color",
+    "--slotted-currency-field-stepper-hover-background",
+    "--slotted-currency-field-stepper-size",
+    "--slotted-currency-field-subtle-background",
+    "--slotted-currency-field-subtle-border-color",
+    "--slotted-currency-field-subtle-hover-background",
+    "--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-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 1, 2, 3, 4 without touching a separator: the digits enter at the cent and shift left.",
+      "language": "tsx",
+      "source": "<Field>\n  <FieldLabel>Total do pedido</FieldLabel>\n  <CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" min={0} />\n  <FieldDescription>Digite apenas os números: 1234 vira R$ 12,34.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "entry",
+      "title": "The two ways an amount is typed",
+      "note": "Type 1234 into each. On the left the digits shift left from the cent, as a cash register does; on the right the text is yours until you leave the field, as a spreadsheet is — regrouped as it arrives, which is what formatOn decides and what cents-first entry has always done.",
+      "language": "tsx",
+      "source": "// The default. 1234 is R$ 12,34, the separator is never typed,\n// and the caret has one legal position: after the last digit.\n<CurrencyField currency=\"BRL\" entry=\"cents\" locale=\"pt-BR\" />;\n\n// The model number-field uses: the text is the reader's until a commit.\n<CurrencyField currency=\"BRL\" entry=\"natural\" locale=\"pt-BR\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "currency",
+      "title": "The currency decides how far a digit shifts",
+      "note": "Type 1234 into each of the four. A real has two minor digits, a yen none and a dinar three, so the same four keystrokes are R$ 12,34, ¥1.234 and KWD 1,234.",
+      "language": "tsx",
+      "source": "<CurrencyField currency=\"BRL\" locale=\"pt-BR\" />;\n<CurrencyField currency=\"JPY\" locale=\"pt-BR\" />;\n<CurrencyField currency=\"KWD\" locale=\"pt-BR\" />;\n\n// The display is an axis of its own: the symbol, the narrow symbol,\n// the ISO code, or the currency written out.\n<CurrencyField currency=\"USD\" currencyDisplay=\"code\" locale=\"pt-BR\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "locale",
+      "title": "The currency governs; the locale writes",
+      "note": "A Brazilian back office paying a US invoice: Brazilian separators around an American currency. The numbering system comes from the locale too, so an Arabic field reads back its own digits.",
+      "language": "tsx",
+      "source": "// US$ 1.480,00 — the symbol from the currency, the separators from the locale.\n<CurrencyField currency=\"USD\" defaultValue={1480} locale=\"pt-BR\" />;\n\n// The same amount, written where the symbol goes last.\n<CurrencyField currency=\"EUR\" defaultValue={1480} locale=\"fr-FR\" />;\n\n// Set once for an application, rather than on every amount in a form.\n<SlottedProvider locale=\"pt-BR\">\n  <CurrencyFieldDefaultsProvider currency=\"BRL\">\n    <CurrencyField defaultValue={1480} />\n  </CurrencyFieldDefaultsProvider>\n</SlottedProvider>;\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": "<CurrencyField currency=\"BRL\" defaultValue={89.9} locale=\"pt-BR\" size=\"sm\" />;\n<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" size=\"md\" />;\n<CurrencyField currency=\"BRL\" defaultValue={24900} locale=\"pt-BR\" size=\"lg\" />;\n\n// Inside a field the field decides, and the control follows.\n<Field size=\"sm\">\n  <CurrencyField currency=\"BRL\" defaultValue={12} locale=\"pt-BR\" />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "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 at rest — which is what a table of amounts needs, where the border of every row would be the loudest thing on the page.",
+      "language": "tsx",
+      "source": "<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" variant=\"outline\" />;\n<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" variant=\"subtle\" />;\n\n// A cell that is only a control while it is being used.\n<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" variant=\"plain\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "alignment",
+      "title": "Which edge the amount is set against",
+      "note": "Read the two columns down rather than across: aligned to the end, the cents of every row line up and a magnitude is one glance; aligned to the start, they do not.",
+      "language": "tsx",
+      "source": "// The default: a column of amounts is compared on its last digit.\n<CurrencyField align=\"end\" currency=\"BRL\" defaultValue={12} locale=\"pt-BR\" />;\n<CurrencyField align=\"end\" currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" />;\n\n// One amount inside a form that reads as a sentence.\n<CurrencyField align=\"start\" currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "range",
+      "title": "The bounds, and what happens at them",
+      "note": "blur returns the amount to the range when you leave the field; strict refuses the keystroke that would leave it; none keeps what you typed and says so with aria-invalid. min={0} is also what refuses a debit.",
+      "language": "tsx",
+      "source": "<CurrencyField clamp=\"blur\" currency=\"BRL\" locale=\"pt-BR\" max={1000} min={0} />;\n<CurrencyField clamp=\"strict\" currency=\"BRL\" locale=\"pt-BR\" max={1000} min={0} />;\n<CurrencyField clamp=\"none\" currency=\"BRL\" locale=\"pt-BR\" max={1000} min={0} />;\n\n// A refund, where a debit is the point. There is no allowNegative:\n// the range already says it, and two ways to say it can disagree.\n<CurrencyField currency=\"BRL\" locale=\"pt-BR\" min={-1000} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "stepper",
+      "title": "Two buttons, when an amount is nudged rather than typed",
+      "note": "Withdrawn by default: an invoice total is typed, and two buttons that move it by one real invite a mis-click that costs money. A price a reader adjusts is the case they are for.",
+      "language": "tsx",
+      "source": "<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" />;\n\n// step is one major unit, not one cent. Shift and the page keys move by\n// largeStep, Alt by smallStep.\n<CurrencyField currency=\"BRL\" defaultValue={25} locale=\"pt-BR\" step={1} stepper=\"stacked\" />;\n<CurrencyField currency=\"BRL\" defaultValue={25} locale=\"pt-BR\" stepper=\"split\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "adornments",
+      "title": "The symbol inside the amount, and the symbol beside it",
+      "note": "Both are here because choosing wrongly is the mistake: the symbol from currency is selected, copied and parsed with the amount, and the one in start is none of those things.",
+      "language": "tsx",
+      "source": "// Inside: R$ moves with the locale, is copied with the amount and is\n// what aria-valuetext announces.\n<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" />;\n\n// Beside: a label rather than part of the number. The amount is written\n// without a symbol, and the adornment is never parsed.\n<CurrencyField\n  currency=\"BRL\"\n  currencyDisplay=\"none\"\n  defaultValue={1480}\n  end=\"por mês\"\n  locale=\"pt-BR\"\n  start=\"R$\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "scrub",
+      "title": "Drag the symbol to move the amount",
+      "note": "The sibling’s gesture on a currency mark. Press R$ and drag sideways: two pixels per step of one real, Shift for ten, Alt for ten centavos. A right-to-left document steps up towards the left, the inline end.",
+      "language": "tsx",
+      "source": "<CurrencyField\n  currency=\"BRL\"\n  currencyDisplay=\"none\"\n  defaultValue={1480}\n  locale=\"pt-BR\"\n  min={0}\n  start={<CurrencyFieldScrub>R$</CurrencyFieldScrub>}\n/>;\n\n<CurrencyField\n  currency=\"BRL\"\n  currencyDisplay=\"none\"\n  defaultValue={250}\n  locale=\"pt-BR\"\n  max={1000}\n  min={0}\n  start={<CurrencyFieldScrub sensitivity={4}>R$</CurrencyFieldScrub>}\n  step={10}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Every state the frame paints",
+      "note": "Hover the first, tab into the second, then compare read-only with disabled: one keeps its ink because the amount is real and still submitted, the other mutes it because nobody can reach it.",
+      "language": "tsx",
+      "source": "<CurrencyField currency=\"BRL\" defaultValue={1480} invalid locale=\"pt-BR\" />;\n<CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" readOnly />;\n<CurrencyField currency=\"BRL\" defaultValue={1480} disabled locale=\"pt-BR\" />;\n\n// Unstated means \"ask the field\": the control defers rather than\n// overriding a field that is already disabled.\n<Field disabled>\n  <FieldLabel>Total</FieldLabel>\n  <CurrencyField currency=\"BRL\" defaultValue={1480} locale=\"pt-BR\" />\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "The ceiling amount, a currency written as a name, and a debit in accounting parentheses — each in a 320-pixel column, where the frame scrolls its own text and keeps the leading digits.",
+      "language": "tsx",
+      "source": "// Fifteen digits is where a double stops holding a cent, and the\n// keystroke past it is refused rather than rounded.\n<CurrencyField currency=\"BRL\" defaultValue={9999999999999.99} locale=\"pt-BR\" />;\n\n<CurrencyField currency=\"BRL\" currencyDisplay=\"name\" defaultValue={1480} locale=\"pt-BR\" />;\n\n// Intl writes ($1,234.56) and the parser reads it back as a debit.\n<CurrencyField\n  currency=\"USD\"\n  defaultValue={-1234.56}\n  format={{ currencySign: 'accounting' }}\n  locale=\"en-US\"\n  min={-100000}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, reaching past it, and putting it in a form",
+      "note": "The provider carries the decisions an application takes once; the hidden input submits 1480.5 rather than \"R$ 1.480,50\"; the request carries the integer a payment API is charged in.",
+      "language": "tsx",
+      "source": "<CurrencyFieldDefaultsProvider currency=\"BRL\">\n  <CurrencyField defaultValue={1480} name=\"total\" />\n</CurrencyFieldDefaultsProvider>;\n\n// The request carries the exact minor-unit integer, so nobody writes\n// Math.round(value * 100) — the line where a half cent is lost.\n<CurrencyField\n  currency=\"BRL\"\n  locale=\"pt-BR\"\n  onValueChange={(value, request) => charge(request.minorUnits, request.currency)}\n/>;\n\n// A currency picker beside the amount, until the select family exists.\n<CurrencyField currency={currency} end={<CurrencyPicker onChange={setCurrency} />} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and what it deliberately does not",
+      "note": "Digits shift left, Backspace shifts right, the minus key sets the sign without entering the digits, and the arrows step. Tab never lands on a stepper.",
+      "language": "tsx",
+      "source": "// ArrowUp/ArrowDown: step. Shift or PageUp/PageDown: largeStep.\n// Alt: smallStep. Home: min. End: max. Enter: commits, then submits.\n// \"-\" and \"+\": the sign, never a digit. A separator is refused outright.\n<CurrencyField currency=\"BRL\" locale=\"pt-BR\" max={100000} min={-100000} step={1} />;\n\n// The wheel is not bound unless it is asked for, and even then only\n// while the control has focus.\n<CurrencyField currency=\"BRL\" defaultValue={50} locale=\"pt-BR\" wheel />;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}