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

package/dist/docs/currency-field.md

@@ -0,0 +1,117 @@
+<!-- index: ./index.md -->
+# currency-field
+
+`data-ui="currency-field"` · Number input for amounts in a currency.
+
+## Import
+
+```tsx
+import { CurrencyField, CurrencyFieldDefaultsProvider, CurrencyFieldScrub } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Field>
+  <FieldLabel>Total do pedido</FieldLabel>
+  <CurrencyField currency="BRL" defaultValue={1480} locale="pt-BR" min={0} />
+  <FieldDescription>Digite apenas os números: 1234 vira R$ 12,34.</FieldDescription>
+</Field>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `input` | input[type=text][role=spinbutton] | yes |
+| `start` | span | no |
+| `end` | span | no |
+| `scrub` | span (CurrencyFieldScrub) | no |
+| `stepper` | span | no |
+| `decrement` | button[type=button][tabindex=-1] | no |
+| `increment` | button[type=button][tabindex=-1] | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `currency` | `string` | from the provider | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `currencyDisplay` | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | symbol | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `value` | `number \| null` | — | CurrencyField | 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 |
+| `defaultValue` | `number \| null` | — | CurrencyField | What an uncontrolled control starts from, read once. A native form reset returns to it |
+| `entry` | `'cents' \| 'natural'` | cents | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `formatOn` | `'change' \| 'commit'` | change | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `align` | `'end' \| 'start'` | end | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `locale` | `string` | the language in force | CurrencyField | BCP 47. It decides the separators, where the symbol goes and the numbering system — never the symbol itself, which is the currency’s |
+| `format` | `Intl.NumberFormatOptions` | — | CurrencyField | 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 |
+| `fractionDigits` | `number` | the currency’s minor units | CurrencyField | Overrides how many fraction digits the amount is written with, for a unit price quoted finer than the currency’s cent |
+| `min` | `number` | — | CurrencyField | 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 |
+| `max` | `number` | — | CurrencyField | The largest amount the control holds. It disables the increment button at the bound and gives End somewhere to go |
+| `step` | `number` | 1 | CurrencyField | What the arrows and the two buttons move by, in major units: one real, not one centavo |
+| `largeStep` | `number` | step * 10 | CurrencyField | What Shift and the page keys move by |
+| `smallStep` | `number` | step / 10 | CurrencyField | What Alt moves by |
+| `stepFrom` | `number` | min, or 0 | CurrencyField | 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 |
+| `clamp` | `'blur' \| 'strict' \| 'none'` | blur | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `allowEmpty` | `boolean` | false | CurrencyField | 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 |
+| `wheel` | `boolean` | false | CurrencyField | 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 |
+| `stepper` | `'stacked' \| 'split' \| 'none'` | none | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | CurrencyField, CurrencyFieldDefaultsProvider | 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 |
+| `start` | `ReactNode` | — | CurrencyField | An adornment before the amount in the reading direction. It is a sibling of the number: never selected, never copied and never parsed |
+| `end` | `ReactNode` | — | CurrencyField | An adornment after the amount: a currency code, a period, or a consumer’s own currency picker |
+| `CurrencyFieldScrub sensitivity` | `number` | 2 | CurrencyFieldScrub | Pixels of horizontal travel per step. A wide range wants fewer pixels per step; a fine one, more |
+| `disabled` | `boolean` | from the field, or false | CurrencyField | 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 |
+| `readOnly` | `boolean` | from the field, or false | CurrencyField | Unstated rather than false. The native readonly, which stays focusable, selectable and submitted, and which disables both steppers |
+| `invalid` | `boolean` | from the field, or false | CurrencyField | Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame |
+| `required` | `boolean` | — | CurrencyField | 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 / form` | `string` | — | CurrencyField | 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 |
+| `autoComplete` | `string` | off | CurrencyField | 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 |
+| `messages` | `Partial<CurrencyFieldMessages>` | — | CurrencyField | Words laid over the language in force, key by key: increment and decrement are what the two buttons announce |
+| `render` | `(props: CurrencyFieldRootProps) => ReactNode` | — | CurrencyField | 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 |
+| `ref` | `Ref<HTMLInputElement>` | — | CurrencyField | Reaches the input. focus(), select() and setSelectionRange() are the element’s own, so no imperative handle is invented for what the platform already ships |
+| `handle` | `Ref<CurrencyFieldHandle>` | — | CurrencyField | increment() and decrement(), the two actions a consumer cannot express by passing a value. Both report reason "programmatic" |
+| `className / style` | `string / CSSProperties` | — | CurrencyField | Reach the frame, because the frame is what a consumer sees. Every other native prop reaches the input |
+| `CurrencyFieldDefaultsProvider` | `{ currency, currencyDisplay, entry, align, size, variant, stepper, clamp }` | — | a subtree | 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 |
+| `useField()` | `() => FieldContextValue \| undefined` | — | inside a Field | 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 | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: number \| null, request: CurrencyChangeRequest)` | 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. |
+| `onChange, onBlur, onKeyDown, onFocus` | `the element’s own events` | 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. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `entry` | `cents`, `natural` | `cents` |
+| `align` | `end`, `start` | `end` |
+| `stepper` | `none`, `stacked`, `split` | `none` |
+| `clamp` | `blur`, `strict`, `none` | `blur` |
+| `currencyDisplay` | `symbol`, `narrowSymbol`, `code`, `name`, `none` | `symbol` |
+| `formatOn` | `change`, `commit` | `change` |
+
+## Rules
+
+- 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
+
+See [currency-field.examples.md](./currency-field.examples.md).