# 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.