Functional Weave
Code in Rust

form.validate-input@1.0.0

README.md

4,383 bytes · view raw

# form.validate-input

`validateInput(value, rules)` checks one input the way the GOV.UK Design
System asks a service to, and gives the message to show. The rules are the
browser's constraint attributes as data (`required`, `minlength`,
`maxlength`, `pattern`, `min`, `max`, and the input's type), so the component
that renders the input (`react.form.validated-input`) and the API that
receives the form check exactly the same thing: TypeScript in the browser,
Python or Rust on the server.

```ts
validateInput("17", { label: "Age", kind: "integer", required: true, min: "18", max: "120" });
// { valid: false, value: null, code: "too-small", message: "Age must be between 18 and 120" }

validateInput("  Ada ", { label: "Full name", kind: "text", required: true });
// { valid: true, value: "Ada", code: null, message: null }
```

## Order of the checks

The first rule broken is the one reported, in this order:

1. **required**: the value, trimmed of ASCII whitespace, is empty. Empty and
   not required is valid (`value: ""`) and nothing else is checked.
2. **too-long**, then **too-short**: `maxLength` and `minLength`.
3. the kind's format: **email** (validation.email's `isEmail`), **number**
   or **integer**.
4. **pattern**: text.pattern-match on the trimmed value.
5. **too-small** / **too-large**: `min` and `max`, number and integer only.

So a too-long email address is told it is too long rather than malformed, and
a PIN typed as letters is told it must be a whole number before the pattern
is tried.

## Messages

GOV.UK's wording, with the label as it starts a sentence ("Full name"):

| code | message |
|------|---------|
| required | Enter full name (the label's first letter lowered, unless it starts with an acronym: "Enter UK phone number") |
| too-long | Full name must be 35 characters or less |
| too-short | Reference must be 3 characters or more |
| email | Enter an email address in the correct format, like name@example.com |
| number | Temperature must be a number |
| integer | Number of children must be a whole number |
| pattern | `patternMessage` when given, else "Enter postcode in the correct format". Give one: only the caller knows what the format is |
| too-small / too-large | Rating must be between 1 and 5; Age must be 18 or more; Age must be 120 or less (`code` says which side) |

`min` and `max` are shown exactly as given, so give them as they should read.

## Decisions

- **Numbers are decimal strings, compared exactly.** `min`, `max` and the
  value are compared digit by digit, never as floats, so `0.3` is not below
  `0.30` and `10.000000000000000001` is above `10` in every language. The
  value accepted is what a person types: ASCII digits, one optional point, an
  optional leading minus (`-12.5`, `.5`, `007`). No `+`, no grouping commas,
  no exponent, no trailing point; those are "must be a number". A money
  amount, with its currency and grouping, is form.money-input's job.
- **integer** refuses any point, even `2.0`: the person typed a decimal.
- **The value is trimmed** of ASCII whitespace (GOV.UK asks services to
  accept leading and trailing spaces), and the trimmed value is returned to
  store. Unicode spaces are not trimmed, so the three languages agree.
- **Length counts Unicode code points**, so `"😀"` is one character in every
  language. The browser's `maxlength` counts UTF-16 code units, where an
  emoji is two: for text outside the Basic Multilingual Plane the browser
  stops typing earlier than this check would refuse, never later.
- **The pattern applies to every kind**, after the kind's own format check.
  The browser ignores `pattern` on `type="number"`, which is one more reason
  react.form.validated-input renders numbers as text with an input mode.
- **Bad rules throw** whatever was typed: an empty label, an unknown kind, a
  negative or crossed length, `min`/`max` on a text or email input, a bound
  that is not a decimal, `min` above `max`, or a pattern text.pattern-match
  refuses (its "unsupported pattern" message). They are programming errors,
  so the first test catches them, not the first user.

## Notices

Error message wording follows the GOV.UK Design System. Portions derived from GOV.UK Frontend (https://github.com/alphagov/govuk-frontend), Copyright (c) 2017 Crown Copyright (Government Digital Service), under the MIT License; the full notice is in NOTICE.