svelte-kit-vice/src/uix/eidos/components/format-date/README.md

# Eidos FormatDate

`<FormatDate>` es un **service component** — un wrapper greppable de
`getActiveUix().format.dates.formatDate / formatTime / formatDateTime`.
Renderiza un valor `Date | number | string` a traves del runtime activo
de UIX y emite `<time datetime="ISO 8601">` por defecto para asistencia
tecnica y SEO.

Familia con `<Trans>`, `<FormatNumber>`, `<RelativeTime>`: todos son
wrappers tipados del runtime para que un audit i18n/l10n encuentre cada
sitio de formateo con `grep "<FormatDate"`.

## Superficie

```svelte
<FormatDate value={post.publishedAt} />
<FormatDate value={meeting.startsAt} mode="dateTime" dateStyle="short" timeStyle="short" />
<FormatDate value={createdAt} mode="time" timeZone="UTC" timeZoneName="short" />
<FormatDate value={anniversary} weekday="long" day="numeric" month="long" />
<FormatDate value={now} locale="ja-JP" dateStyle="full" />
<FormatDate value={start} mode="time" hourCycle="h12" />
```

## Props clave

| Prop | Tipo | Default | Notas |
| --- | --- | --- | --- |
| `value` | `Date \| number \| string \| null` | — | `null` o invalid → renderiza `fallback`. |
| `mode` | `'date' \| 'time' \| 'dateTime'` | `'date'` | Decide a que metodo del runtime se rutea. |
| `dateStyle` | `'short' \| 'medium' \| 'long' \| 'full'` | — | Preset. Por defecto `'medium'` cuando aplique. |
| `timeStyle` | idem | — | Preset. Por defecto `'short'` cuando aplique. |
| `weekday / era / year / month / day` | per-axis | — | Override fino. Drop-ea los presets. |
| `hour / minute / second / dayPeriod / fractionalSecondDigits` | per-axis | — | Idem para axis temporal. |
| `timeZone` | `string` | local | IANA zone (`Europe/Madrid`, …). |
| `timeZoneName` | `'short' \| 'long' \| 'shortOffset' \| 'longOffset' \| 'shortGeneric' \| 'longGeneric'` | — | Label de zona. Drop-ea presets. |
| `hourCycle` | `'h11' \| 'h12' \| 'h23' \| 'h24'` | — | Caller gana sobre preferencia del engine. |
| `calendar / numberingSystem` | `string` | — | Orthogonal a presets. |
| `locale` | `SupportedLocale` | runtime | Override por llamada. No muta el runtime. |
| `fallback` | `string` | `''` | Render cuando `value` es `null` / invalid. |
| `as` | `keyof HTMLElementTagNameMap` | `'time'` | Tag HTML. |

## Decisiones

- **Siempre rutea por `uix.format.dates`** (no llama a `Intl` directamente
  excepto cuando no hay runtime). Esto preserva el cache
  (`getCachedDateFormat`), la preferencia de `hourCycle` del engine, el
  conflict handling, y la reactividad del locale activo.
- **`locale` se pasa como tercer arg al runtime** (`dates.formatDate(value,
  options, locale)`) — el engine acepta override por llamada sin mutar
  state. El cache keyea por `(locale × options)`.
- **Mode + presets**: `mode` decide a que metodo del runtime se rutea
  (`formatDate / formatTime / formatDateTime`). Cada uno inyecta su
  preset default (`dateStyle: 'medium'`, `timeStyle: 'short'`) solo si
  no hay conflict con per-axis fields o `timeZoneName`.
- **`<time datetime="ISO 8601">` por defecto**: el ISO original queda
  disponible para asistencia tecnica y crawlers. Si el caller pasa
  `as="span"`, el `datetime` se aplica al span (validado por Svelte) pero
  pierde la semantica nativa.
- **No CSS recipe**: el marker `[data-format-date]` existe solo para
  tooling — no hay estilos a nivel de eidos porque el output es texto
  puro.
- **No emite eventos sema**: no es una acto perceptivo del usuario.

## Conflict handling (Intl rules)

`Intl.DateTimeFormat` lanza si mezclas `dateStyle` / `timeStyle` con
cualquier per-axis field (`weekday`, `era`, `year`, `month`, `day`,
`dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits`) o con
`timeZoneName`. El engine drop-ea los defaults cuando detecta conflict —
**ambos presets** caen juntos porque la regla es estricta.

Si quieres mostrar timezone label (`timeZoneName`), usa per-axis:

```svelte
<FormatDate
  value={createdAt}
  year="numeric" month="short" day="numeric"
  hour="2-digit" minute="2-digit"
  timeZone="UTC" timeZoneName="short"
/>
<!-- '25 may 2026, 14:30 UTC' -->
```

## Comparativa

| Capacidad | Eidos | date-fns | Day.js | luxon | Intl.DateTimeFormat |
| --- | --- | --- | --- | --- | --- |
| Modo `date`/`time`/`dateTime` | Si | Manual via format strings | Manual | Si (`toLocaleString`) | Manual |
| Locale reactivo desde runtime | Si | No | No | No | No |
| Cache de instancias por options | Si | No | No | No | No (creas instancia) |
| Conflict handling automatico | Si | N/A | N/A | N/A | No (lanza error) |
| HourCycle preference + override | Si | Manual | Manual | Si | No persistencia |
| `<time datetime>` semantico | Si | No | No | No | No |
| Per-call locale override | Si | Cambia DateLocale global | Manual | Manual | Si por instancia |

## Referencias

- Intl.DateTimeFormat: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
- Engine wiring: `src/arts/format/dates/engine-dates.ts`
- Active runtime: `src/arts/format/dates/active-dates.svelte.ts`
- Conflict tests: `src/arts/format/dates/test/engine-dates.test.ts`