first commit

docs/localization/i18n/i18n-formatter-date/src/presets/presets.md

@@ -0,0 +1,100 @@
+# Date format presets
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`PRESET_MAP` is the canonical 8-entry table that maps each
+`DateFormatPreset` discriminant to a concrete
+`Intl.DateTimeFormatOptions` payload. `resolvePreset(options)` is the
+merge function used inside `formatDate` to combine a preset's
+defaults with raw caller-supplied options (raw fields override).
+
+The presets exist so consumers can render dates with ergonomic verbs
+(`{ preset: "short" }`) instead of having to memorise the eight or so
+field-style enums `Intl.DateTimeFormat` accepts.
+
+## Features
+
+- 8 frozen presets covering every common UI case (date+time / time-only / date-only, plus `full` for legal-style timestamps)
+- `DATE_FORMAT_PRESETS` array of all preset names — useful for building UI selects
+- `resolvePreset(options?)` merges preset defaults with raw fields; raw fields take precedence
+- Pure functions, side-effect-free
+
+## Usage: Basic Example
+
+```ts
+import {
+    DATE_FORMAT_PRESETS,
+    PRESET_MAP,
+    resolvePreset,
+} from "@suaveplan/i18n-formatter-date";
+
+// Inspect a preset directly.
+PRESET_MAP.short;
+// { year: "numeric", month: "numeric", day: "numeric",
+//   hour: "numeric", minute: "numeric" }
+
+// Build a select.
+DATE_FORMAT_PRESETS.map((p) => ({ value: p, label: p }));
+
+// Resolve a merged options object.
+resolvePreset({ preset: "short", month: "long" });
+// { year: "numeric", month: "long", day: "numeric",
+//   hour: "numeric", minute: "numeric" }
+```
+
+## Usage: Advanced Example
+
+```ts
+import { resolvePreset } from "@suaveplan/i18n-formatter-date";
+
+// Power a custom Intl wrapper that needs the resolved Intl options
+// without going through formatDate.
+function customDate(d: Date, locale: string, preset: "short" | "long") {
+    const opts = resolvePreset({ preset });
+    return new Intl.DateTimeFormat(locale, opts).format(d);
+}
+
+// Override the default fields of a preset.
+const fullWithoutWeekday = resolvePreset({
+    preset: "full",
+    weekday: undefined, // raw fields override; setting to undefined
+                         //   keeps the field in the object but
+                         //   Intl.DateTimeFormat ignores `undefined`.
+});
+```
+
+## API Reference
+
+### `PRESET_MAP: Readonly<Record<DateFormatPreset, Intl.DateTimeFormatOptions>>`
+
+The 8-entry table. Keys: `"short"`, `"medium"`, `"long"`, `"full"`,
+`"time-short"`, `"time-long"`, `"date-short"`, `"date-long"`.
+
+### `DATE_FORMAT_PRESETS: readonly DateFormatPreset[]`
+
+Frozen array of every preset name. Useful for select-box population.
+
+### `resolvePreset(options?): Intl.DateTimeFormatOptions | undefined`
+
+- Returns `undefined` when `options` is `undefined`.
+- Returns `rest` (with `preset` and `locale` stripped) when no
+  `preset` is supplied.
+- Returns `{ ...PRESET_MAP[preset], ...rest }` when `preset` is
+  supplied — raw fields override preset defaults.
+
+## Implementation Notes
+
+- `PRESET_MAP` and `DATE_FORMAT_PRESETS` are sourced verbatim from
+  the monolith `formatting/date/date.ts` L4–L41 (per the source
+  mapping table in the change folder's proposal).
+- `resolvePreset` mirrors the monolith's L51–L58. The function is
+  small, pure, and exported so consumers can build their own Intl
+  wrappers without reinventing the merge.
+- The `locale` field is stripped because `Intl.DateTimeFormat` does
+  not accept `locale` inside the options object — it must be passed
+  as the first constructor argument. Stripping here keeps the
+  resolved options object passable to `Intl.DateTimeFormat` directly.