svelte-kit-vice/src/uix/soma/components/relative-time/README.md

Soma RelativeTime

<RelativeTime> es un service component que envuelve Intl.RelativeTimeFormat con auto-refresh tick. Renderiza frases relativas como "hace 2 horas" / "in 3 days" y se refresca a si mismo cuando pasa el tiempo.

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

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

<RelativeTime value={post.publishedAt} />
<RelativeTime value={createdAt} style="short" />
<RelativeTime value={dueDate} unit="day" />
<RelativeTime value={deadline} now={projectStart} unit="week" />
<RelativeTime value={start} updateInterval={0} />
<RelativeTime value={now} locale="ja-JP" />

Props clave

Prop	Tipo	Default	Notas
value	Date | number | string | null	—	null o invalid → fallback.
now	Date | number | string	Date.now()	Punto de referencia. Permite anclar el "ahora".
unit	'auto' | 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second'	'auto'	'auto' escoge la granularidad mas natural.
numeric	'auto' | 'always'	'auto'	'auto' colapsa 0/-1/+1 en palabras ("yesterday", "today").
style	'long' | 'short' | 'narrow'	'long'	Flavor del label.
updateInterval	'auto' | number	'auto'	Cadencia de tick en ms; 0 = sin auto-refresh.
locale	SupportedLocale	runtime dates	Override por instancia.
fallback	string	''	Render cuando value es invalid.
as	keyof HTMLElementTagNameMap	'time'	Tag HTML.

Decisiones

• Auto-unit: cuando unit='auto', el componente escoge la unidad de mayor magnitud que aplique (year → quarter → month → week → day → hour → minute → second). Cae a 'second' si la magnitud no llega a 60s.
• Auto-tick cadence: cuando updateInterval='auto', la cadencia se deriva del unit resuelto: 1s para second, 30s para minute, 5min para hour, 1h para day. Para units mayores no hay tick.
• updateInterval={0} apaga el auto-refresh — util para snapshots estaticos en tablas / patterns.
• Siempre rutea por uix.format.dates.formatRelative (no llama a Intl.RelativeTimeFormat directamente excepto cuando no hay runtime). El engine envuelve el cache compartido (getCachedRelativeTimeFormat en $libs/days), preserva la reactividad del locale activo, y acepta el locale prop como override por llamada sin mutar engine state.
• El componente sigue haciendo la matematica del delta + auto-unit + magnitud — el engine solo expone la operacion atomica (magnitude, unit, options, locale) → string.
• <time datetime="ISO 8601"> por defecto para a11y / SEO.
• data-unit expuesto en el DOM para CSS/tooling que quiera estilar por granularidad (ej. iconos diferentes para "second" vs "year").
• No emite eventos sema.

Comparativa

Capacidad	Soma	date-fns formatDistance	Day.js from	luxon toRelative	Intl.RelativeTimeFormat
Auto-unit	Si	Si	Si	Si	No (manual)
Auto-tick	Si	No	No	No	No
Numeric=auto ("yesterday")	Si	No	No	No	Si
Style short/narrow	Si	No	No	Manual	Si
Reactivo al locale UIX	Si	No	No	No	No
<time datetime> semantico	Si	No	No	No	No
data-unit	Si	No	No	No	No

Referencias

• Intl.RelativeTimeFormat: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat
• Dates engine: src/arts/format/dates/engine-dates.ts (de donde lee el locale activo)