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

Date format presets

(no submodules)

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

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

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.