Initial Commit

openspec/archive/2026-05-09-i18n-formatter-date/proposal.md

@@ -0,0 +1,106 @@
+# `@suaveplan/i18n-formatter-date` — `Intl.DateTimeFormat` wrapper
+
+**Package**: `@suaveplan/i18n-formatter-date` (NEW)
+**Status**: PROPOSED
+**Type**: feature (new universal-tier package; verbatim port of `formatting/date/` plus class wrapper + Zod schema + observability uplift)
+**Date**: 2026-05-05
+**Wave**: 3 (depends on Wave 1 foundation; required by Wave 6 core slim)
+**Design doc**: `openspec/cross-cutting-designs/2026-05-05-i18n-modular-split.md` (especially §5 formatter package shape, §5b FormatBridge)
+**Path**: `packages/i18n/i18n-formatter-date/`
+**Tier**: universal
+
+## Why
+
+The 14-package i18n modular split lifts each `Intl.*` wrapper out of the monolith into its own sibling package. `@suaveplan/i18n-formatter-date` ports the existing `formatting/date/` module — the broadest of the formatters today — and brings it up to the canonical Wave-3 shape (Zod-validated options, OTel histogram + cache-hit counter, class wrapper for symmetry, sibling test files).
+
+Today `formatting/date/` ships a rich surface (180 LoC):
+
+- `formatDate(date, locale, options?)` standalone with preset-or-options resolution (`packages/i18n/i18n/src/formatting/date/date.ts` L64–L73)
+- `formatTime(date, locale, long?)` standalone (`date.ts` L79–L83) — short / long preset
+- `formatDateOnly(date, locale, long?)` standalone (`date.ts` L89–L97)
+- `formatDateRange(start, end, locale, options?)` standalone using `formatRange` (`date.ts` L104–L116)
+- `getDayNames(locale, style?)` ECMA-402-§10.6-`getWeekInfo()`-aware day-name list (`date.ts` L126–L160)
+- `getMonthNames(locale, style?)` (`date.ts` L166–L180)
+- 8-preset table (`PRESET_MAP` at L4–L41): `short`, `medium`, `long`, `full`, `time-short`, `time-long`, `date-short`, `date-long`
+- BCP-47 normalisation via `LOCALE_BCP47_MAP` from shared constants (`date.ts` L43–L49)
+- Type definitions (`date.types.ts` L1–L24): `DateFormatPreset`, `DateFormatOptions`, `ExtendedDateOptions`
+
+This package introduces no new functionality beyond what the monolith ships — the changes are: (a) wrapping the standalones in a `DateFormatter` class for symmetry with `NumberFormatter`/`RelativeTimeFormatter`/`ListFormatter`, (b) adding Zod-validated options, (c) adding the canonical OTel histogram + cache-hit counter (the monolith's date formatter currently does not emit either), and (d) introducing a per-(locale, options-hash) cache (the monolith currently constructs a fresh `Intl.DateTimeFormat` per call).
+
+## What changes
+
+### New package: `@suaveplan/i18n-formatter-date`
+
+- ADDED: `packages/i18n/i18n-formatter-date/` package scaffold (`package.json`, `tsconfig.json`, `vite.config.ts`, `README.md`).
+- ADDED: `src/formatter.ts` — `DateFormatter` class (NEW); `formatDate` standalone (port of monolith L64–L73) extended with cache and OTel emission; `formatDateRange` standalone (port of L104–L116); `clearDateFormatterCache` test-only helper. `PRESET_MAP` and `resolvePreset` helper (port of L4–L58). `toBcp47` helper (port of L43–L49).
+- ADDED: `src/formatter.types.ts` — `DateFormatPreset`, `DateFormatOptions`, `ExtendedDateOptions`, `DateFormatterCacheKey`. Sourced from monolith `date.types.ts` L1–L24 plus new types for the class surface.
+- ADDED: `src/formatter.schemas.ts` — `DateFormatterOptionsSchema` Zod schema. NEW (the monolith does not currently Zod-validate options).
+- ADDED: `src/helpers.ts` — `formatTime(date, locale, long?)` (port of monolith L79–L83); `formatDateOnly(date, locale, long?)` (port of L89–L97); `getDayNames(locale, style?)` (port of L126–L160); `getMonthNames(locale, style?)` (port of L166–L180).
+- ADDED: `src/observability.ts` — local OTel histogram `i18n.format.date.duration_ms` + counter `i18n.format.cache_hit{formatter="date"}`.
+- ADDED: `src/formatter.test.ts` — port of monolith `date.test.ts` (185 lines) plus new tests for `DateFormatter` class, Zod-validation, cache reuse.
+- ADDED: `src/formatter.spec-conformance.test.ts` — every requirement scenario in this delta.
+- ADDED: `src/helpers.test.ts` — covers `formatTime`, `formatDateOnly`, `getDayNames`, `getMonthNames` (including `getWeekInfo()`-fallback for older runtimes).
+- ADDED: `src/index.ts` — explicit named re-exports.
+- ADDED: `src/formatter.md`, `src/helpers.md`, `src/observability.md` — sibling docs.
+
+### Subpath exports
+
+- `.` — root barrel
+- `./formatter` — `DateFormatter` class + `formatDate` + `formatDateRange` + types + schema only
+- `./helpers` — `formatTime`, `formatDateOnly`, `getDayNames`, `getMonthNames` only
+
+### Dependencies
+
+- `@suaveplan/i18n-shared workspace:^` — `I18N_CODES`, `I18nError`, `LOCALE_BCP47_MAP`
+- `@suaveplan/types workspace:^`
+- `@suaveplan/error workspace:^`
+- `@opentelemetry/api catalog:observability`
+- `tslib catalog:build`
+- `zod catalog:forms`
+- **No** dep on any other formatter package, on `@suaveplan/i18n` core, or on any backend package.
+
+## Out of scope
+
+- **Removing `formatting/date/` from `packages/i18n/i18n/src/`** — happens in Wave 6.
+- **`formatToParts` for date output** — out of scope for Wave 3; can be added as a follow-up if downstream consumers (e.g. `react-data-table` date columns) need part-by-part rendering.
+- **`Temporal` API support** — out of scope; `Intl.DateTimeFormat` accepts `Date | number` today and the monolith's surface matches that. Temporal-aware overloads are a follow-up once Temporal stabilises across runtimes.
+- **Custom calendar systems beyond what `Intl.DateTimeFormat` supports** — out of scope.
+
+## Source mapping
+
+| Requirement | Source file | Source lines | Notes |
+|---|---|---|---|
+| `formatDate` standalone with preset-or-options resolution | `packages/i18n/i18n/src/formatting/date/date.ts` | L64–L73 | Verbatim port; extended with cache + OTel emission |
+| `PRESET_MAP` (8 presets: short/medium/long/full/time-short/time-long/date-short/date-long) | `packages/i18n/i18n/src/formatting/date/date.ts` | L4–L41 | Verbatim port |
+| `formatTime` standalone | `packages/i18n/i18n/src/formatting/date/date.ts` | L79–L83 | Verbatim port (helper) |
+| `formatDateOnly` standalone | `packages/i18n/i18n/src/formatting/date/date.ts` | L89–L97 | Verbatim port (helper) |
+| `formatDateRange` standalone | `packages/i18n/i18n/src/formatting/date/date.ts` | L104–L116 | Verbatim port |
+| `getDayNames` (`getWeekInfo()`-aware) | `packages/i18n/i18n/src/formatting/date/date.ts` | L126–L160 | Verbatim port |
+| `getMonthNames` | `packages/i18n/i18n/src/formatting/date/date.ts` | L166–L180 | Verbatim port |
+| `toBcp47` BCP-47 normalisation | `packages/i18n/i18n/src/formatting/date/date.ts` | L43–L49 | Verbatim port; use `LOCALE_BCP47_MAP` from `@suaveplan/i18n-shared` |
+| `resolvePreset` preset+options merge | `packages/i18n/i18n/src/formatting/date/date.ts` | L51–L58 | Verbatim port |
+| `DateFormatPreset`, `DateFormatOptions`, `ExtendedDateOptions` types | `packages/i18n/i18n/src/formatting/date/date.types.ts` | L1–L24 | Verbatim port |
+
+### Requirements with no source line
+
+| Requirement | Justification |
+|---|---|
+| `DateFormatter` class wrapper | New — symmetric with `NumberFormatter`, `RelativeTimeFormatter`, `ListFormatter`, `DisplayNameFormatter` |
+| `DateFormatterOptionsSchema` Zod schema | New — current monolith does not validate options |
+| `INVALID_FORMATTER_OPTIONS` mapping | Bound to the new Zod schema |
+| Per-(locale, options-hash) cache | New — current monolith constructs a fresh `Intl.DateTimeFormat` per call; Wave-3 formatter shape mandates the cache for parity with sibling packages |
+| OTel histogram `i18n.format.date.duration_ms` + cache-hit counter | New — canonical Wave-3 formatter shape mandates these; monolith date formatter currently does not emit either |
+
+## Verification approach
+
+- `packages/i18n/i18n-formatter-date/src/formatter.test.ts` — port of monolith `date.test.ts`; all 8 presets render correctly; raw `Intl.DateTimeFormatOptions` work; preset + raw merged correctly via `resolvePreset`; class wrapper twins helper output; cache reuse on identical key; bogus locale → `UNSUPPORTED_LOCALE`; Zod failure → `INVALID_FORMATTER_OPTIONS`
+- `packages/i18n/i18n-formatter-date/src/formatter.spec-conformance.test.ts` — every requirement scenario runs as an executable test
+- `packages/i18n/i18n-formatter-date/src/helpers.test.ts` — `formatTime(d, "en-GB", false)` returns short-style time; `formatTime(d, "en-GB", true)` includes seconds; `formatDateOnly(d, "en-GB", false)` short style; `getDayNames("en-GB")` returns 7 strings starting from Monday (en-GB `getWeekInfo()` → 1); `getMonthNames("en-GB")` returns 12 strings; `getDayNames` falls back to Monday-start when `getWeekInfo()` is unavailable
+- `packages/i18n/i18n-formatter-date/src/observability.test.ts` — histogram named `i18n.format.date.duration_ms`; counter `i18n.format.cache_hit{formatter="date"}` increments only on cache hit
+- `packages/i18n/i18n-formatter-date/src/index.test.ts` — every documented public export resolves; subpaths resolve
+
+## Impact
+
+- New universal-tier package — joins the rest of the i18n family.
+- Indirect consumer in Wave 6: `@suaveplan/i18n` slim core wires `formatDate` and `formatTime` into the default `FormatBridge` for ICU `{date, date, short}` and `{ts, time, long}` placeholder rendering.
+- `MANIFEST.md` and `CLAUDE.md` updated post-merge.