Reading input

Read typed dates, numbers and times back with the same grammar that writes them.

Display and parsing come from one source, so what a field shows and what it accepts cannot drift apart. Every reader returns a status instead of guessing:

Status	Meaning
`empty`	nothing typed
`incomplete`	a prefix of a valid value: keep typing
`invalid`	cannot become a valid value; numbers also say why (`rejection`)
`valid`	a value, in its canonical form

Numbers#

classifyNumberInput(text, presentation, contract?) reads a number in the reader's notation. The contract can limit decimals, refuse negatives, check a currency or allow a percent sign; mode distinguishes typing from pasting.

Reading a typed numberClient

status: valid
value: 1234.5
number: 1234.5
rejection: (none)

Full source examples/format/number-input.tsx

// apps/docs/examples/format/number-input.tsx'use client';
import {useId, useState} from 'react';
import {  classifyNumberInput,  getNumberInputPlaceholder,} from '@workspace/active-format';import {  DescriptionItem,  DescriptionList,} from '@workspace/active-ui/components/composed/description-list';import {  Field,  FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Input} from '@workspace/active-ui/components/primitives/input';import {  NativeSelect,  NativeSelectOption,} from '@workspace/active-ui/components/primitives/native-select';
/** * Reading a typed number back with the same grammar that writes it. The * result says whether the text is empty, incomplete, invalid or valid, and * why a text is refused. Grouping separators are refused while typing and * accepted in pasted text. */export default function NumberInput() {  const inputId = useId();  const languageId = useId();  const modeId = useId();  const [language, setLanguage] = useState('nl');  const [mode, setMode] = useState<'typing' | 'paste'>('typing');  const [text, setText] = useState('1234,5');  const result = classifyNumberInput(text, language, {mode, maxDecimals: 2});  return (    <div className="flex flex-col gap-4">      <div className="grid gap-3 sm:grid-cols-3">        <Field>          <FieldLabel htmlFor={languageId}>Language</FieldLabel>          <NativeSelect            id={languageId}            value={language}            onChange={(event) => setLanguage(event.target.value)}          >            {['nl', 'en', 'de', 'fr'].map((option) => (              <NativeSelectOption key={option} value={option}>                {option}              </NativeSelectOption>            ))}          </NativeSelect>        </Field>        <Field>          <FieldLabel htmlFor={modeId}>Input</FieldLabel>          <NativeSelect            id={modeId}            value={mode}            onChange={(event) =>              setMode(event.target.value === 'paste' ? 'paste' : 'typing')            }          >            <NativeSelectOption value="typing">Typed</NativeSelectOption>            <NativeSelectOption value="paste">Pasted</NativeSelectOption>          </NativeSelect>        </Field>        <Field>          <FieldLabel htmlFor={inputId}>            Amount (at most two decimals)          </FieldLabel>          <Input            id={inputId}            value={text}            placeholder={getNumberInputPlaceholder(language, 2)}            onChange={(event) => setText(event.target.value)}            inputMode="decimal"          />        </Field>      </div>      <DescriptionList orientation="inline" columns={1}>        <DescriptionItem label="status">          <span className="font-mono" data-testid="number-status">            {result.status}          </span>        </DescriptionItem>        <DescriptionItem label="value">          <span className="font-mono">{result.value || '(none)'}</span>        </DescriptionItem>        <DescriptionItem label="number">          <span className="font-mono">{result.number ?? 'null'}</span>        </DescriptionItem>        <DescriptionItem label="rejection">          <span className="font-mono">{result.rejection ?? '(none)'}</span>        </DescriptionItem>      </DescriptionList>    </div>  );}

value is the canonical text form (plain dot decimal); number is its number, or null.
Typed or pasted. While typing (mode: 'typing', the default) a grouping separator is refused (grouping-while-typing): 1.234 in Dutch could be a slip. The same text is valid when pasted (mode: 'paste'). Try 1.234,56 with both settings above.
A refused text names its rejection, for example cross-convention (a separator from another notation), grouping-position or precision-exceeded.
formatNumberForInput(value, presentation, decimals?) writes a canonical value back as editable text, and getNumberInputPlaceholder(presentation, decimals?) shows the notation itself.

Dates#

getDateInputPattern(presentation): the numeric pattern with a four-digit year, such as dd-MM-yyyy (nl), dd.MM.yyyy (de) or dd/MM/yyyy (en).
classifyDateInput(text, presentation): valid with the ISO calendar day, or why not.
parseIsoDateFromInput(text, presentation): strict; impossible dates and short years are null.
formatIsoDateForInput(isoDate, presentation): an ISO day as input text.

Reading a typed dateClient

status: valid
value: 2028-02-29
read as: Dienstag, 29. Februar 2028

Full source examples/format/date-input.tsx

// apps/docs/examples/format/date-input.tsx'use client';
import {useId, useState} from 'react';
import {  classifyDateInput,  formatDateOnly,  getDateInputPattern,} from '@workspace/active-format';import {  DescriptionItem,  DescriptionList,} from '@workspace/active-ui/components/composed/description-list';import {  Field,  FieldLabel,} from '@workspace/active-ui/components/primitives/field';import {Input} from '@workspace/active-ui/components/primitives/input';import {  NativeSelect,  NativeSelectOption,} from '@workspace/active-ui/components/primitives/native-select';
/** * A typed date in the reader's notation, read back as an ISO calendar day. * Impossible dates are invalid, never moved to the next valid day. */export default function DateInput() {  const inputId = useId();  const languageId = useId();  const [language, setLanguage] = useState('de');  const [text, setText] = useState('29.02.2028');  const pattern = getDateInputPattern(language);  const result = classifyDateInput(text, language);  return (    <div className="flex flex-col gap-4">      <div className="grid gap-3 sm:grid-cols-2">        <Field>          <FieldLabel htmlFor={languageId}>Language</FieldLabel>          <NativeSelect            id={languageId}            value={language}            onChange={(event) => setLanguage(event.target.value)}          >            {['de', 'nl', 'en', 'fr'].map((option) => (              <NativeSelectOption key={option} value={option}>                {option}              </NativeSelectOption>            ))}          </NativeSelect>        </Field>        <Field>          <FieldLabel htmlFor={inputId}>Date ({pattern})</FieldLabel>          <Input            id={inputId}            value={text}            placeholder={pattern}            onChange={(event) => setText(event.target.value)}          />        </Field>      </div>      <DescriptionList orientation="inline" columns={1}>        <DescriptionItem label="status">          <span className="font-mono" data-testid="date-status">            {result.status}          </span>        </DescriptionItem>        <DescriptionItem label="value">          <span className="font-mono">{result.value || '(none)'}</span>        </DescriptionItem>        <DescriptionItem label="read as">          <span suppressHydrationWarning>            {result.status === 'valid'              ? formatDateOnly(result.value, 'full', language)              : '(none)'}          </span>        </DescriptionItem>      </DescriptionList>    </div>  );}

Try 29.02.2027: there is no 29 February in 2027, so the text is invalid. It is never moved to 1 March.

Times of day#

classifyTimeInput(text, presentation, constraints?) reads a wall-clock time in the presentation's clock and separator. A valid value is a LocalTimeString (HH:mm or HH:mm:ss): a clock reading, never a moment. Constraints set the precision, a step grid and inclusive bounds; a time off the step grid is invalid, never rounded.