Temporal Range Formatter

Create a small formatting helper that turns the package's date-time objects into localized strings and ranges. Focus on the package's Temporal-aware formatter so that single values and ranges render correctly without manual string assembly.

Capabilities

Format single temporal value

• Given a zone-less date-time for 2024-03-15T18:30 and locale en-GB with { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hour12: false, timeZone: "Europe/London" }, returns 15/03/2024, 18:30 using the provided time zone instead of the system default. @test
• Given a zone-aware instant for 2024-07-01T00:15Z and locale en-US with { year: "2-digit", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hour12: true, timeZone: "America/New_York" }, returns 06/30/24, 08:15 PM, applying offset conversion from the input's zone. @test

Format temporal range

• For 2024-05-01T09:00Z to 2024-05-01T11:00Z with locale en-GB and { year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hour12: false, timeZone: "UTC" }, returns 01/05/2024, 09:00 – 11:00, collapsing the shared date and zone into a single string. @test
• For 2024-12-31T23:30Z to 2025-01-01T05:30Z with locale en-US and { year: "2-digit", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hour12: true, timeZone: "America/New_York" }, returns 12/31/24, 06:30 PM – 01/01/25, 12:30 AM, showing both dates because the window crosses midnight in the target zone. @test

Range parts output

• Produces an ordered array of parts for the 2024-05-01T09:00Z–2024-05-01T11:00Z window (locale en-GB, options from the same-day range) where the first item contains the start date text and the final item contains the end time text, preserving locale-specific tokens for UI highlighting. @test

Implementation

@generates

API

export type TimePoint = unknown;

export interface FormatterOptions {
  locale: string;
  timeZone?: string;
  dateStyle?: "full" | "long" | "medium" | "short";
  timeStyle?: "full" | "long" | "medium" | "short";
  hour12?: boolean;
  year?: "numeric" | "2-digit";
  month?: "numeric" | "2-digit" | "long" | "short";
  day?: "numeric" | "2-digit";
  hour?: "numeric" | "2-digit";
  minute?: "numeric" | "2-digit";
}

export interface RangeFormatterOptions extends FormatterOptions {
  collapseDate?: boolean;
}

export interface FormattedPart {
  type: string;
  value: string;
  source: "startRange" | "endRange" | "shared";
}

export function formatTimePoint(input: TimePoint, options: FormatterOptions): string;

export function formatTimeRange(
  start: TimePoint,
  end: TimePoint,
  options: RangeFormatterOptions
): string;

export function formatTimeRangeParts(
  start: TimePoint,
  end: TimePoint,
  options: RangeFormatterOptions
): FormattedPart[];

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Temporal-aware date and time formatting, including range and parts output for Temporal objects and legacy dates. @satisfied-by