Skip to main content

Formatting values

One function turns a stored value into the text a reader sees: a date column, a date input and a report cell all format the same field the same way. The formatter is formatValue in core/blong-browser/src/lib/format.ts, and a component reaches it through the useFormatValue hook, which resolves the configuration first.

The specification​

With nobody configuring anything, a value reads like this:

TypeWhat it showsEnglish example
datethe locale's medium date — a month name, not numbersApr 2, 2026
timemedium, seconds kept7:15:32 AM
dateTimeboth of the aboveApr 2, 2026, …
numbera measure: grouped, up to three decimals1,275.456
integera count, rank or year: not grouped2032
currencythe configured currency, grouped€450.50
percentup to two decimals92.5%

A date is never numeric by default: 04/02/2026 is April 2nd in one locale and 4 February in another, so the locale's own month name is the only spelling that needs no key beside it.

The locale is a setting, not an accident. It defaults to the UI language, so a table cell agrees with the Calendar beside it, and it is never taken from the machine — a record must not render differently on two developers' screens.

Where the settings come from​

Four layers, most specific first. They resolve key by key, so a user who only chose a clock still gets the system's date style, and a column that only sets decimals keeps everything else from below it.

#LayerSet by
1the columnwidget.formatOptions on the field — raw Intl options for its type
2the usersetFormat('user', …) — the person's own preference, loaded with the profile
3the systemsetFormat('system', …) — the app's configuration
4the languagelanguageDefaults(language) — the fallbacks above, plus the language's currency

The language layer is the only one that carries a value nobody asked for: bg falls back to BGN, en to EUR. A currency has no locale-wide answer, so a language may state its own.

import {resolveFormatConfig, formatValue} from './lib/format.js';

const config = resolveFormatConfig({
user: {hourCycle: 'h23'},
system: {dateStyle: 'short', currency: 'BGN'},
language: 'bg',
});
// {locale: 'bg', dateStyle: 'short', timeStyle: 'medium', hourCycle: 'h23',
// currency: 'BGN', grouping: 'auto'}

formatValue('2026-04-02T07:15:32', 'dateTime', undefined, undefined, config);

The configuration​

IFormatConfig is one layer; every key is optional.

KeyTypeMeaning
localeBCP-47 tagthe language dates and numbers are written in
dateStylefull | long | medium | shortthe preset a date cell uses
timeStylefull | long | medium | shortthe preset a time cell uses
hourCycleh12 | h2312- or 24-hour clock; unset leaves the locale's own choice
currencyISO 4217 codethe code a currency cell falls back to
groupingauto | always | neverauto groups a measure and not a count

These are the words a settings UI offers — a preset per row, not a builder for Intl options.

In a component​

import {useFormatValue} from '../hooks/useFormat.js';

function Total({amount}: {amount: number}) {
const format = useFormatValue();
return <span>{format(amount, 'currency')}</span>;
}

The hook subscribes to the language and to both configuration layers, so a language switch or a settings change re-renders the text instead of leaving yesterday's month names on screen.

Setting a layer​

The layers live in the app store, so an app sets them where it already owns its settings:

import {useAppStore} from './state/appStore.js';

// on load, from the app's configuration
useAppStore.getState().setFormat('system', {dateStyle: 'short', currency: 'BGN'});

// from a settings screen, or from the profile
useAppStore.getState().setFormat('user', {hourCycle: 'h23'});

// back to the layer below
useAppStore.getState().setFormat('user', undefined);

Per-column options​

A column may override any of it. widget.formatOptions takes the Intl options of its own type, so it can say anything the presets cannot:

area: {
title: 'Area (m²)',
widget: {type: 'number', formatOptions: {number: {maximumFractionDigits: 1}}},
},
fee: {
title: 'Fee',
widget: {type: 'currency', formatOptions: {currency: {currency: 'USD'}}},
},
FieldApplies toOverrides
formatOptions.datedatedateStyle
formatOptions.timetimetimeStyle, hourCycle
formatOptions.dateTimedateTimeboth of the above
formatOptions.numbernumber, integerdecimals and grouping
formatOptions.currencycurrencythe code and its options
formatOptions.percentpercentthe percent options
widget.useGroupingnumber, integergrouping for this column

useGrouping is the shortcut for the common case, and it defaults differently on purpose: a number groups unless it says false, an integer does not unless it says true.

Tests​

src/lib/format.test.ts covers the chain — the language defaults, the per-key precedence, and the four types against a resolved configuration. A test that cares about the text asserts on a locale it names, never on the machine's:

expect(formatValue(date, 'date', undefined, undefined, {locale: 'bg'})).toContain('.05.2024');

See it working​

The Editor/TableColumns stories show each layer on the same row — FormattingSystem, FormattingUser and FormattingBG — beside Formatting, which is the specification alone:

cd core/blong-browser
node --run storybook
npx test-storybook --includeTags table-columns

See Foreign key labels for the label a key column shows instead of the key itself.