Temporal Timeline Formatter

Create a small formatting helper that turns the time-based objects produced by the dependency into consistent strings for storage, JSON transport, and locale-aware display. Inputs are the dependency's own time objects created from ISO strings or property bags (points in time with offsets, date-only values, and time-of-day values). The helper should avoid manual string assembly and instead rely on the dependency's built-in string and locale formatting behaviors.

Capabilities

Single value formatting

• Given a point-in-time value parsed from the ISO string 2024-11-19T10:15:30Z and display options { dateStyle: "medium", timeStyle: "long", timeZone: "UTC" }, it returns iso and json fields that exactly match the dependency's default stringification of that value, and a localized field that matches Intl.DateTimeFormat("en-GB", options).format(value) @test

Local fallback for date-only/time-only values

• Given a date-only value parsed from 2025-05-06 and a fallback time zone of America/New_York, the helper keeps the date-only ISO/JSON outputs unchanged while producing a localized string whose zone-aware components align with Intl.DateTimeFormat("en-US", { dateStyle: "full", timeStyle: "short", timeZone: fallback }) applied to that value @test
• Given a time-of-day value parsed from 14:45:00 with display options { timeStyle: "short", timeZone: "Europe/London" }, the helper emits ISO/JSON strings that mirror the dependency defaults and a localized string aligned with the provided locale/timeZone options @test

Range formatting

• Given a start value parsed from 2024-11-19T07:00:00-05:00[America/New_York], an end value parsed from 2024-11-19T09:30:00-05:00[America/New_York], and locale en-US, the helper returns a localizedRange string that matches Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short", timeZone: "America/New_York" }).formatRange(start, end) and preserves the input ordering (start before end) @test

Implementation

@generates

API

export type TemporalValue = unknown;

export interface FormatOptions {
  locale?: string;
  timeZone?: string;
  display?: Intl.DateTimeFormatOptions;
}

export interface SingleFormatInput extends FormatOptions {
  label: string;
  value: TemporalValue;
}

export interface RangeFormatInput extends FormatOptions {
  label: string;
  start: TemporalValue;
  end: TemporalValue;
}

export interface SingleFormatResult {
  label: string;
  iso: string;
  json: string;
  localized: string;
}

export interface RangeFormatResult {
  label: string;
  localizedRange: string;
}

export function formatValue(input: SingleFormatInput, fallbackTimeZone?: string): SingleFormatResult;
export function formatRange(input: RangeFormatInput): RangeFormatResult;
export function formatTimeline(
  values: SingleFormatInput[],
  ranges?: RangeFormatInput[],
  fallbackTimeZone?: string
): { values: SingleFormatResult[]; ranges: RangeFormatResult[] };

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Provides the date/time objects and locale-aware formatting behavior used in this helper.