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

package/docs/currency-field.examples.md

@@ -0,0 +1,321 @@
+<!-- index: ./index.md -->
+# currency-field
+
+`data-ui="currency-field"` · Number input for amounts in a currency.
+
+## Examples
+
+### The two ways an amount is typed
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- The default. 1234 is R$ 12,34, the separator is never typed, and the
+     caret has one legal position: after the last digit. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" entry="cents" />
+</div>
+
+<!-- The model number-field uses: the text is the reader's until a commit. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" entry="natural" />
+</div>
+```
+
+### The currency decides how far a digit shifts
+
+Type 1234 into each of the three. 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.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField><input slCurrencyFieldInput currency="BRL" locale="pt-BR" /></div>
+<div slCurrencyField><input slCurrencyFieldInput currency="JPY" locale="pt-BR" /></div>
+<div slCurrencyField><input slCurrencyFieldInput currency="KWD" locale="pt-BR" /></div>
+
+<!-- The display is an axis of its own: symbol, narrowSymbol, code or name. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="USD" locale="pt-BR" currencyDisplay="code" />
+</div>
+```
+
+### The currency governs; the locale writes
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- US$ 1.480,00 — the symbol from the currency, the separators from the locale. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="USD" locale="pt-BR" defaultValue="1480" />
+</div>
+
+<!-- The same amount, written where the symbol goes last. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="EUR" locale="fr-FR" defaultValue="1480" />
+</div>
+```
+
+### The step the control sits at
+
+Three steps, and inside a field the control takes the field’s rather than its own: a small field holding a medium control is a field and a control disagreeing about one row.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField size="sm">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="89.9" />
+</div>
+<div slCurrencyField size="lg">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="24900" />
+</div>
+
+<!-- Inside a field the field decides, and the control follows. -->
+<div slField size="sm">
+  <div slCurrencyField>
+    <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="12" />
+  </div>
+</div>
+```
+
+### How much frame the control shows
+
+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 a border on every row would be the loudest thing on the page.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField variant="outline">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+<div slCurrencyField variant="subtle">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+
+<!-- A cell that is only a control while it is being used. -->
+<div slCurrencyField variant="plain">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+```
+
+### Which edge the amount is set against
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- The default: a column of amounts is compared on its last digit. -->
+<div slCurrencyField align="end">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="12" />
+</div>
+
+<!-- One amount inside a form that reads as a sentence. -->
+<div slCurrencyField align="start">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+```
+
+### The bounds, and what happens at them
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" clamp="strict" min="0" max="1000" />
+</div>
+
+<!-- A refund, where a debit is the point. There is no allowNegative: the
+     range already says it, and two ways to say it can disagree. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" min="-1000" />
+</div>
+```
+
+### Two buttons, when an amount is nudged rather than typed
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+
+<!-- step is one major unit, not one cent. -->
+<div slCurrencyField stepper="stacked">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="25" step="1" min="0" />
+</div>
+<div slCurrencyField stepper="split">
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="25" min="0" />
+</div>
+```
+
+### The symbol inside the amount, and the symbol beside it
+
+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 slCurrencyFieldStart is none of those things.
+
+Excerpt — not a complete module
+
+```html
+<!-- Inside: R$ moves with the locale and is copied with the amount. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+</div>
+
+<!-- Beside: a label rather than part of the number, never parsed. -->
+<div slCurrencyField>
+  <span slCurrencyFieldStart>R$</span>
+  <input
+    slCurrencyFieldInput
+    currency="BRL"
+    locale="pt-BR"
+    defaultValue="1480"
+    currencyDisplay="none"
+  />
+  <span slCurrencyFieldEnd>por mês</span>
+</div>
+```
+
+### Drag the symbol to move the amount
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField>
+  <span slCurrencyFieldStart><span slCurrencyFieldScrub>R$</span></span>
+  <input
+    slCurrencyFieldInput
+    aria-label="Preço"
+    currency="BRL"
+    currencyDisplay="none"
+    locale="pt-BR"
+    defaultValue="1480"
+    min="0"
+  />
+</div>
+
+<div slCurrencyField>
+  <span slCurrencyFieldStart><span slCurrencyFieldScrub [sensitivity]="4">R$</span></span>
+  <input
+    slCurrencyFieldInput
+    aria-label="Orçamento"
+    currency="BRL"
+    currencyDisplay="none"
+    locale="pt-BR"
+    defaultValue="250"
+    min="0"
+    max="1000"
+    step="10"
+  />
+</div>
+```
+
+### Every state the frame paints
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" invalid />
+</div>
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" readonly />
+</div>
+
+<!-- Unstated means "ask the field": the control defers rather than
+     overriding a field that is already disabled. -->
+<div slField disabled>
+  <label slFieldLabel>Total</label>
+  <div slCurrencyField>
+    <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="1480" />
+  </div>
+</div>
+```
+
+### Content the family did not choose
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- Fifteen digits is where a double stops holding a cent, and the
+     keystroke past it is refused rather than rounded. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="9999999999999.99" />
+</div>
+
+<!-- Intl writes ($1,234.56) and the parser reads it back as a debit. -->
+<div slCurrencyField>
+  <input
+    slCurrencyFieldInput
+    currency="USD"
+    locale="en-US"
+    defaultValue="-1234.56"
+    min="-100000"
+    [format]="{ currencySign: 'accounting' }"
+  />
+</div>
+```
+
+### Setting it once, reaching past it, and putting it in a form
+
+The token carries the decisions an application takes once; ControlValueAccessor puts the amount in a Reactive Form; the hidden input submits 1480.5 rather than "R$ 1.480,50".
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [
+    provideSlotted({ locale: 'pt-BR' }),
+    provideCurrencyFieldDefaults({ currency: 'BRL' }),
+  ],
+});
+
+@Component({
+  template: `<div slCurrencyField>
+    <input slCurrencyFieldInput name="total" [formControl]="total" (valueChange)="charge($event)" />
+  </div>`,
+})
+export class Checkout {
+  readonly total = new FormControl<number | null>(1480);
+
+  // The request carries the exact minor-unit integer, so nobody writes
+  // Math.round(value * 100) — the line where a half cent is lost.
+  charge(request: CurrencyChangeRequest) {
+    this.gateway.charge(request.minorUnits, request.currency);
+  }
+}
+```
+
+### What the keyboard does, and what it deliberately does not
+
+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.
+
+Excerpt — not a complete module
+
+```html
+<!-- ArrowUp/ArrowDown: step. Shift or PageUp/PageDown: largeStep.
+     Alt: smallStep. Home: min. End: max. Enter: commits, then submits.
+     "-" and "+": the sign, never a digit. A separator is refused outright. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" min="-100000" max="100000" step="1" />
+</div>
+
+<!-- The wheel is not bound unless it is asked for, and even then only
+     while the control has focus. -->
+<div slCurrencyField>
+  <input slCurrencyFieldInput currency="BRL" locale="pt-BR" defaultValue="50" wheel />
+</div>
+```