Formatted number

<script lang="ts" module>
	/*
	 * One formatter per locale and options, shared by every instance. Building an
	 * Intl.NumberFormat is the expensive part; a table of a few hundred cells reuses a handful.
	 * The cache is capped, because on a server it lives as long as the process.
	 */
	const CACHE_LIMIT = 200;
	// eslint-disable-next-line svelte/prefer-svelte-reactivity -- a plain cache, never read reactively
	const formatters = new Map<string, Intl.NumberFormat | null>();

	/**
	 * The formatter, or null when it cannot format predictably: a malformed locale, a locale
	 * the runtime has no data for (Intl would quietly use the runtime's own, so the server and
	 * the browser could disagree), or options Intl rejects.
	 */
	function formatterFor(locale: string, options: Intl.NumberFormatOptions) {
		let key: string;
		try {
			key = `${locale}\u0000${JSON.stringify(options)}`;
		} catch {
			return null;
		}
		if (!formatters.has(key)) {
			let formatter: Intl.NumberFormat | null = null;
			try {
				if (Intl.NumberFormat.supportedLocalesOf(locale).length > 0) {
					formatter = new Intl.NumberFormat(locale, options);
				}
			} catch {
				// RangeError or TypeError from Intl: render the fallback rather than throw mid-page.
			}
			if (formatters.size >= CACHE_LIMIT) formatters.delete(formatters.keys().next().value!);
			formatters.set(key, formatter);
		}
		return formatters.get(key) ?? null;
	}

	/**
	 * The options a screen reader hears. Compact, scientific and engineering output ("1.5M")
	 * are spoken as the whole value, and short or narrow units ("km/h") by their long names,
	 * so no abbreviation is announced without its expansion. Digit options are dropped with
	 * the notation: they were set for the abbreviated mantissa, and kept they would read
	 * 1.23E-7 as "0".
	 */
	function spokenOptions(options: Intl.NumberFormatOptions): Intl.NumberFormatOptions {
		const spoken: Intl.NumberFormatOptions = { ...options };
		if (spoken.notation && spoken.notation !== 'standard') {
			for (const digits of [
				'compactDisplay',
				'minimumFractionDigits',
				'maximumFractionDigits',
				'minimumSignificantDigits',
				'roundingIncrement',
				'roundingPriority'
			] as const) {
				delete spoken[digits];
			}
			spoken.notation = 'standard';
			spoken.maximumSignificantDigits = 21;
		}
		if (spoken.style === 'unit') spoken.unitDisplay = 'long';
		return spoken;
	}
</script>

<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		/** The number to format. NaN, null or anything that is not a number renders the fallback. */
		value: number | bigint | null | undefined;
		/** BCP 47 locale. Required, so the server and the browser format the same way. */
		locale: string;
		/** Intl.NumberFormat options: style, currency, unit, notation, fraction digits. */
		options?: Intl.NumberFormatOptions;
		/** Text shown when there is no valid number to format. */
		fallback?: string;
		/** What a screen reader hears instead of the fallback. */
		fallbackLabel?: string;
		/** Tabular figures, so digits line up in columns and do not shift as they change. */
		tabular?: boolean;
		/** Extra classes on the element. */
		class?: string;
		/** Custom rendering of the formatToParts output, to set a symbol or fraction apart. */
		parts?: Snippet<[Intl.NumberFormatPart[]]>;
	}

	let {
		value,
		locale,
		options,
		fallback = '—',
		fallbackLabel,
		tabular = true,
		class: className,
		parts
	}: Props = $props();

	// -0 is a rounding artefact, not a value anyone means to show as "−0".
	const number = $derived(
		typeof value === 'bigint' || (typeof value === 'number' && !Number.isNaN(value))
			? Object.is(value, -0)
				? 0
				: value
			: null
	);
	// One snapshot of the options, so the cache key and the formatter read the same values.
	const settings = $derived<Intl.NumberFormatOptions>({ ...options });
	const formatter = $derived(number === null ? null : formatterFor(locale, settings));
	const text = $derived(formatter && number !== null ? formatter.format(number) : null);
	const spoken = $derived.by(() => {
		if (text === null || number === null) return null;
		const full = formatterFor(locale, spokenOptions(settings))?.format(number);
		return full && full !== text ? full : null;
	});
	// The default dash is not a word, so it is announced as "Not available" unless told otherwise.
	const label = $derived(fallbackLabel ?? (fallback === '—' ? 'Not available' : undefined));
</script>

{#snippet visible()}
	{#if parts && formatter && number !== null}
		{@render parts(formatter.formatToParts(number))}
	{:else}
		{text}
	{/if}
{/snippet}

{#if text !== null && number !== null}
	<!-- dir="auto" isolates the number with its own direction, so -1,234.5 keeps its sign in RTL text. -->
	<data
		value={String(number)}
		lang={locale}
		dir="auto"
		class={[
			'formatted-number whitespace-nowrap text-(--_ink)',
			tabular && 'tabular-nums',
			className
		]}
	>
		{#if spoken}
			<span aria-hidden="true">{@render visible()}</span><span class="sr-only select-none"
				>{spoken}</span
			>
		{:else}
			{@render visible()}
		{/if}
	</data>
{:else}
	<span
		class={[
			'formatted-number formatted-number--fallback whitespace-nowrap text-(--_ink)',
			className
		]}
	>
		{#if label}
			<span aria-hidden="true" class="text-(--_muted)">{fallback}</span><span
				class="sr-only select-none">{label}</span
			>
		{:else}
			{fallback}
		{/if}
	</span>
{/if}

<style>
	/*
	 * Public tokens: by default the number takes the surrounding text colour and the fallback
	 * dash a softer mix of it, so it sits in a table, a price or a dark band without a change.
	 * Only the dash is softened: a fallback written as words is text, and keeps the full ink.
	 */
	.formatted-number {
		--_ink: var(--formatted-number-ink, currentColor);
		--_muted: var(--formatted-number-muted, color-mix(in srgb, currentColor 64%, transparent));
	}
</style>

<script lang="ts" module>
	/*
	 * One formatter per locale and options, shared by every instance. Building an
	 * Intl.NumberFormat is the expensive part; a table of a few hundred cells reuses a handful.
	 * The cache is capped, because on a server it lives as long as the process.
	 */
	const CACHE_LIMIT = 200;
	// eslint-disable-next-line svelte/prefer-svelte-reactivity -- a plain cache, never read reactively
	const formatters = new Map<string, Intl.NumberFormat | null>();

	/**
	 * The formatter, or null when it cannot format predictably: a malformed locale, a locale
	 * the runtime has no data for (Intl would quietly use the runtime's own, so the server and
	 * the browser could disagree), or options Intl rejects.
	 */
	function formatterFor(locale: string, options: Intl.NumberFormatOptions) {
		let key: string;
		try {
			key = `${locale}\u0000${JSON.stringify(options)}`;
		} catch {
			return null;
		}
		if (!formatters.has(key)) {
			let formatter: Intl.NumberFormat | null = null;
			try {
				if (Intl.NumberFormat.supportedLocalesOf(locale).length > 0) {
					formatter = new Intl.NumberFormat(locale, options);
				}
			} catch {
				// RangeError or TypeError from Intl: render the fallback rather than throw mid-page.
			}
			if (formatters.size >= CACHE_LIMIT) formatters.delete(formatters.keys().next().value!);
			formatters.set(key, formatter);
		}
		return formatters.get(key) ?? null;
	}

	/**
	 * The options a screen reader hears. Compact, scientific and engineering output ("1.5M")
	 * are spoken as the whole value, and short or narrow units ("km/h") by their long names,
	 * so no abbreviation is announced without its expansion. Digit options are dropped with
	 * the notation: they were set for the abbreviated mantissa, and kept they would read
	 * 1.23E-7 as "0".
	 */
	function spokenOptions(options: Intl.NumberFormatOptions): Intl.NumberFormatOptions {
		const spoken: Intl.NumberFormatOptions = { ...options };
		if (spoken.notation && spoken.notation !== 'standard') {
			for (const digits of [
				'compactDisplay',
				'minimumFractionDigits',
				'maximumFractionDigits',
				'minimumSignificantDigits',
				'roundingIncrement',
				'roundingPriority'
			] as const) {
				delete spoken[digits];
			}
			spoken.notation = 'standard';
			spoken.maximumSignificantDigits = 21;
		}
		if (spoken.style === 'unit') spoken.unitDisplay = 'long';
		return spoken;
	}
</script>

<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		/** The number to format. NaN, null or anything that is not a number renders the fallback. */
		value: number | bigint | null | undefined;
		/** BCP 47 locale. Required, so the server and the browser format the same way. */
		locale: string;
		/** Intl.NumberFormat options: style, currency, unit, notation, fraction digits. */
		options?: Intl.NumberFormatOptions;
		/** Text shown when there is no valid number to format. */
		fallback?: string;
		/** What a screen reader hears instead of the fallback. */
		fallbackLabel?: string;
		/** Tabular figures, so digits line up in columns and do not shift as they change. */
		tabular?: boolean;
		/** Extra classes on the element. */
		class?: string;
		/** Custom rendering of the formatToParts output, to set a symbol or fraction apart. */
		parts?: Snippet<[Intl.NumberFormatPart[]]>;
	}

	let {
		value,
		locale,
		options,
		fallback = '—',
		fallbackLabel,
		tabular = true,
		class: className,
		parts
	}: Props = $props();

	// -0 is a rounding artefact, not a value anyone means to show as "−0".
	const number = $derived(
		typeof value === 'bigint' || (typeof value === 'number' && !Number.isNaN(value))
			? Object.is(value, -0)
				? 0
				: value
			: null
	);
	// One snapshot of the options, so the cache key and the formatter read the same values.
	const settings = $derived<Intl.NumberFormatOptions>({ ...options });
	const formatter = $derived(number === null ? null : formatterFor(locale, settings));
	const text = $derived(formatter && number !== null ? formatter.format(number) : null);
	const spoken = $derived.by(() => {
		if (text === null || number === null) return null;
		const full = formatterFor(locale, spokenOptions(settings))?.format(number);
		return full && full !== text ? full : null;
	});
	// The default dash is not a word, so it is announced as "Not available" unless told otherwise.
	const label = $derived(fallbackLabel ?? (fallback === '—' ? 'Not available' : undefined));
</script>

{#snippet visible()}
	{#if parts && formatter && number !== null}
		{@render parts(formatter.formatToParts(number))}
	{:else}
		{text}
	{/if}
{/snippet}

{#if text !== null && number !== null}
	<!-- dir="auto" isolates the number with its own direction, so -1,234.5 keeps its sign in RTL text. -->
	<data
		value={String(number)}
		lang={locale}
		dir="auto"
		class={[
			'formatted-number whitespace-nowrap text-(--_ink)',
			tabular && 'tabular-nums',
			className
		]}
	>
		{#if spoken}
			<span aria-hidden="true">{@render visible()}</span><span class="sr-only select-none"
				>{spoken}</span
			>
		{:else}
			{@render visible()}
		{/if}
	</data>
{:else}
	<span
		class={[
			'formatted-number formatted-number--fallback whitespace-nowrap text-(--_ink)',
			className
		]}
	>
		{#if label}
			<span aria-hidden="true" class="text-(--_muted)">{fallback}</span><span
				class="sr-only select-none">{label}</span
			>
		{:else}
			{fallback}
		{/if}
	</span>
{/if}

<style>
	/*
	 * Public tokens: by default the number takes the surrounding text colour and the fallback
	 * dash a softer mix of it, so it sits in a table, a price or a dark band without a change.
	 * Only the dash is softened: a fallback written as words is text, and keeps the full ink.
	 */
	.formatted-number {
		--_ink: var(--formatted-number-ink, currentColor);
		--_muted: var(--formatted-number-muted, color-mix(in srgb, currentColor 64%, transparent));
	}
</style>