# 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

```svelte
<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)