Functional Weave
Code in TypeScript

form.money-input@1.0.0

README.md

3,904 bytes · view raw

# form.money-input

The logic behind a money input: read what was typed as integer minor units,
check it, and write an amount back for editing, the same way in the browser
(`react.form.money-field` calls it) and on the server (TypeScript, Python or
Rust), so both refuse the same text with the same words.

```ts
parseMoneyInput("£1,234.50", "GBP", "en-GB", { label: "Monthly rent", required: true, min: 1000, max: 500000, allowNegative: false });
// { valid: true, amount: { minor: 123450, currency: "GBP" }, message: null }

parseMoneyInput("1,234.50", "EUR", "de-DE", { label: "Amount", required: true, min: null, max: null, allowNegative: false });
// { valid: false, amount: null, message: "Enter amount in the correct format, like 1.234,50" }

formatMoneyInput({ minor: 123450, currency: "EUR" }, "fr-FR");   // "1 234,50"
moneyInputFormat("SEK", "sv-SE");
// { currency: "SEK", symbol: "kr", symbolBefore: false, digits: 2, groupSeparator: " ", decimalSeparator: ",", example: "1 234,50" }
```

## Built on money.*

- **money.parse** does the conversion to minor units. It is strict and throws;
  a form wants a message instead, so this capability checks the shape first,
  with money.parse's own rules (symbol before or after, at most one space
  beside it, a minus before or after a leading symbol, real thousands grouping
  or none), and hands money.parse only text it is certain to accept.
- **money.currency-digits** says how many decimal places a currency has (2 for
  GBP, 0 for JPY, 3 for KWD). Unknown currencies throw its error.
- **money.format**'s currency table gives the symbol and which side it goes on;
  for a currency it does not list, the first symbol money.parse knows for it
  (put before), else the ISO code. Amounts in messages are written with that
  symbol and the locale's separators: "£10.00", "€1.000,00", "100,00 kr".

## Locales

`locale` picks money.parse's number style from `data/locales.json`: the exact
locale first (case-insensitive, `_` read as `-`), then its language alone
(`de-AT` is listed; `de-LU` falls back to `de`). An unlisted locale throws
`unknown locale`. The styles are comma-dot (en, ja, zh, ko, he, th), dot-comma
(de, es, it, nl, pt-BR, da, id, tr, el), space-comma (fr, pt-PT, sv, nb, fi,
pl, cs, sk, hu, ru, uk) and apostrophe-dot (de-CH, it-CH, de-LI).

Only thousands grouping is read and written: en-IN's lakh grouping
(12,34,567.00) is refused as typed, though the ungrouped number is accepted.
`formatMoneyInput` groups with a plain space in space-comma locales (what a
keyboard types); money.parse also reads the no-break spaces documents use.

## The checks, in order, and their messages

| Typed | Message |
|---|---|
| nothing, `required` | Enter monthly rent |
| not an amount in this locale, or another currency's symbol | Enter monthly rent in the correct format, like 1,234.50 |
| a minus, without `allowNegative` | Monthly rent must not be negative |
| too many decimals | Monthly rent must not have more than 2 decimal places |
| decimals for a currency without them | Monthly rent must be a whole number |
| more than 2^53 - 1 minor units | Monthly rent is too large |
| outside `min`..`max` (minor units, inclusive) | Monthly rent must be between £10.00 and £5,000.00 / must be £10.00 or more / must be £5,000.00 or less |

Text is trimmed of ASCII whitespace; digits are ASCII only, so "١٢" is not an
amount. Nothing typed in an optional input is valid with `amount` null. The
label starts the sentence ("Monthly rent must ..."), and after "Enter" its
first letter is lower-cased unless it starts an acronym ("Enter VAT amount").

The example in `moneyInputFormat` and in the format message is 1234.50 with as
many decimal places as the currency has: "1,234" for yen, "1,234.500" for
Kuwaiti dinar.

## Errors

Thrown, since they are the caller's: an empty label, an unknown currency or
locale, `min` above `max`.