svelte-kit-vice/src/uix/soma/components/format-number/README.md

Soma FormatNumber

<FormatNumber> es un service component — un wrapper greppable de getActiveUix().format.numbers. Renderiza un numero a traves del runtime activo de UIX (cache de Intl.NumberFormat + locale reactivo + preferencias de moneda / sistema de unidades).

Familia con <Trans>, <FormatDate>, <RelativeTime>.

Vive en soma/components/ (no eidos/components/) porque es una pieza de comportamiento alrededor de getActiveUix(). La invariante "Eidos no importa runtime" se preserva sacando los 4 service components a Soma.

Superficie

<FormatNumber value={1234.56} />
<FormatNumber value={1499} formatStyle="currency" currency="EUR" />
<FormatNumber value={2048} formatStyle="unit" unit="byte" notation="compact" />
<FormatNumber value={42.5} formatStyle="percent" valueAsPercent />
<FormatNumber value={1234567} notation="compact" compactDisplay="long" />
<FormatNumber value={3.14159} maximumFractionDigits={2} />
<FormatNumber value={-99.5} formatStyle="currency" currency="USD" currencySign="accounting" />

Props clave

Prop	Tipo	Default	Notas
value	number | null	—	null → renderiza fallback.
formatStyle	'decimal' | 'percent' | 'currency' | 'unit'	'decimal'	Familia Intl.
currency	ISO 4217	runtime currency	Required cuando formatStyle='currency'.
unit	sanctioned unit	—	Required cuando formatStyle='unit'.
currencyDisplay	'symbol' | 'narrowSymbol' | 'code' | 'name'	'symbol'	Flavor de label.
currencySign	'standard' | 'accounting'	'standard'	Accounting envuelve negativos en parentesis.
unitDisplay	'long' | 'short' | 'narrow'	'short'	Flavor de unit label.
notation	'standard' | 'compact' | 'scientific' | 'engineering'	'standard'	Compact = "1.2K" / "1 million".
compactDisplay	'short' | 'long'	'short'	Solo aplica si notation='compact'.
signDisplay	'auto' | 'never' | 'always' | 'exceptZero' | 'negative'	'auto'	Politica del signo.
useGrouping	boolean	true	Separador de millares.
minimumFractionDigits / maximumFractionDigits	number	—	Precision fraccional.
minimumIntegerDigits	number	—	Padding de ceros a la izquierda.
minimumSignificantDigits / maximumSignificantDigits	number	—	Digitos significativos.
valueAsPercent	boolean	false	Shortcut para 'percent' con 42.5 → 42.5%.
locale	SupportedLocale	runtime	Override de locale por instancia.
fallback	string	''	Render cuando value es null / undefined.
as	keyof HTMLElementTagNameMap	'span'	Tag HTML.

Decisiones

• Siempre rutea por uix.format.numbers (no llama a Intl directamente excepto cuando no hay runtime). Esto preserva el cache (getCachedNumberFormat), los separadores activos, el defaultFormat y la reactividad del locale activo.
• locale se pasa como tercer arg al runtime (numbers.format(value, options, locale)) — el engine acepta override por llamada sin mutar state. El cache keyea por (locale × options) asi cada override es su propio slot.
• valueAsPercent: shortcut para callers que ya escalaron el valor a 0-100 (42.5 debe renderizar '42.5%'). Internamente divide por 100 antes de pasar a Intl.
• Currency fallback: cuando formatStyle='currency' sin currency prop, lee el currency activo de uix.format.currency.getCurrency().
• No CSS recipe: marker [data-format-number] solo para tooling.
• No emite eventos sema.

Comparativa

Capacidad	Soma	numbro	accounting.js	Intl.NumberFormat
Locale reactivo desde runtime	Si	No	No	No
Cache de instancias por options	Si	No	No	No
<FormatNumber> greppable	Si	N/A	N/A	N/A
Currency / Unit / Percent / Compact	Si	Si	Solo currency	Si
Per-call locale override	Si	Manual	Manual	Si
Accounting sign	Si	Si	Si	Si

Referencias

• Intl.NumberFormat: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat
• Engine: src/arts/format/numbers/engine-numbers.ts
• Active runtime: src/arts/format/numbers/active-numbers.svelte.ts