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

package/docs/currency-field.md

@@ -0,0 +1,128 @@
+<!-- index: ./index.md -->
+# currency-field
+
+`data-ui="currency-field"` · Number input for amounts in a currency.
+
+## Import
+
+```ts
+import {
+  provideCurrencyFieldDefaults,
+  SlCurrencyField,
+  SlCurrencyFieldEnd,
+  SlCurrencyFieldInput,
+  SlCurrencyFieldScrub,
+  SlCurrencyFieldStart,
+} from '@slotted/angular/currency-field';
+```
+
+Selector: `[slCurrencyField]` · exportAs: `slCurrencyField`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Total do pedido</label>
+  <div slCurrencyField>
+    <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" min="0" />
+  </div>
+  <span slFieldDescription>Digite apenas os números: 1234 vira R$ 12,34.</span>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slCurrencyField | yes |
+| `input` | input[slCurrencyFieldInput], as text with role="spinbutton" | yes |
+| `start` | the element carrying slCurrencyFieldStart | no |
+| `end` | the element carrying slCurrencyFieldEnd | no |
+| `scrub` | any element carrying slCurrencyFieldScrub, inside an adornment | no |
+| `stepper` | span, rendered by the frame under stepper="stacked" | no |
+| `decrement` | button[type=button][tabindex=-1], rendered by the frame | no |
+| `increment` | button[type=button][tabindex=-1], rendered by the frame | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `currency` | `string` | from the token | slCurrencyFieldInput, provideCurrencyFieldDefaults | 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 token: a field that guessed two minor digits would write ¥12,34 |
+| `currencyDisplay` | `'symbol' \| 'narrowSymbol' \| 'code' \| 'name'` | symbol | slCurrencyFieldInput, provideCurrencyFieldDefaults | 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 slCurrencyFieldStart adornment instead of inside the value. It is the one arrangement Intl has no option for |
+| `value` | `number \| null` | — | slCurrencyFieldInput | 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` | — | slCurrencyFieldInput | What an uncontrolled control starts from, read once. A Reactive Form writes over it through ControlValueAccessor |
+| `entry` | `'cents' \| 'natural'` | cents | slCurrencyFieldInput, provideCurrencyFieldDefaults | 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. The frame paints what the control resolved |
+| `formatOn` | `'change' \| 'commit'` | change | slCurrencyField, provideCurrencyFieldDefaults | 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 | slCurrencyField, provideCurrencyFieldDefaults | 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 | slCurrencyFieldInput | 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` | — | slCurrencyFieldInput | 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 | slCurrencyFieldInput | Overrides how many fraction digits the amount is written with, for a unit price quoted finer than the currency’s cent |
+| `min` | `number` | — | slCurrencyFieldInput | 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` | — | slCurrencyFieldInput | The largest amount the control holds. It disables the increment button at the bound and gives End somewhere to go |
+| `step` | `number` | 1 | slCurrencyFieldInput | What the arrows and the two buttons move by, in major units: one real, not one centavo |
+| `largeStep` | `number` | step * 10 | slCurrencyFieldInput | What Shift and the page keys move by |
+| `smallStep` | `number` | step / 10 | slCurrencyFieldInput | What Alt moves by |
+| `stepFrom` | `number` | min, or 0 | slCurrencyFieldInput | 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 | slCurrencyFieldInput, provideCurrencyFieldDefaults | 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 | slCurrencyFieldInput | 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 | slCurrencyFieldInput | 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 | slCurrencyField, provideCurrencyFieldDefaults | 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 | slCurrencyField, provideCurrencyFieldDefaults | The type step, read from the field first when there is one, then from the token. Height, padding, type and glyph all come from the control scales the theme restates per density |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | slCurrencyField, provideCurrencyFieldDefaults | 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` | `slCurrencyFieldStart` | — | projected content | An adornment before the amount in the reading direction. It is a sibling of the number: never selected, never copied and never parsed |
+| `end` | `slCurrencyFieldEnd` | — | projected content | An adornment after the amount: a currency code, a period, or a consumer’s own currency picker |
+| `sensitivity` | `number` | 2 | slCurrencyFieldScrub | 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 | slCurrencyFieldInput | 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. A Reactive Form reaches the same state through setDisabledState |
+| `readOnly` | `boolean` | from the field, or false | slCurrencyFieldInput | 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 | slCurrencyFieldInput | Unstated rather than false. Writes aria-invalid on the control and data-invalid on the frame |
+| `required` | `boolean` | — | slCurrencyFieldInput | 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` | — | slCurrencyFieldInput | Static attributes read with HostAttributeToken and moved to a hidden input the frame renders, 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 | slCurrencyFieldInput | The element’s own attribute, read before the host binding computes. transaction-amount is the standard autofill field name for a payment amount, and transaction-currency for the currency beside it |
+| `messages` | `Partial<CurrencyFieldMessages>` | — | slCurrencyField | Words laid over the language in force, key by key: increment and decrement are what the two buttons announce |
+| `slCurrencyField` | `attribute directive` | — | the consumer’s own element | The frame is a directive on an element the consumer wrote, so the box is already theirs. Angular pays one element for it where React pays none: a directive cannot create a wrapper around its own host |
+| `exportAs` | `'slCurrencyField' / 'slCurrencyFieldInput'` | — | a template reference | Reaches the instance from the template. The control exposes inputElement — focus(), select() and setSelectionRange() are the element’s own — plus increment() and decrement(), the two actions a consumer cannot express by passing a value |
+| `ng-content` | `[slCurrencyFieldStart], [slCurrencyFieldEnd]` | — | projected content | Two named slots, projected lazily. The frame writes data-part on the consumer’s own element rather than wrapping it |
+| `provideCurrencyFieldDefaults` | `{ currency, currencyDisplay, entry, align, size, variant, stepper, clamp }` | — | an injector | 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 |
+| `NG_VALUE_ACCESSOR` | `ControlValueAccessor` | — | slCurrencyFieldInput | Reactive Forms and template forms both reach the amount in major units. There is no Validator: min, max and step are reported, and when an error shows is the form’s policy |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `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 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. |
+| `ControlValueAccessor` | `number \| null` | Whenever the amount moves, so [formControl], [(ngModel)] and a template form all receive it. setDisabledState answers a form that disables the control, and the frame paints data-disabled from it. There is no [(value)]: a two-way binding has one slot and can carry neither a reason nor cancel(). |
+| `the element’s own events` | `(input), (blur), (keydown), (focus)` | Whenever the element fires them. The directive listens on the host rather than replacing them, and a consumer’s handler that calls 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, 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 — and derived from the format under natural entry. A static inputmode the consumer wrote is read with HostAttributeToken before the binding computes, so it survives.
+- 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.
+- 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).