@burglekitt/gmt/dist/utc/format/formatCalendarUtc.d.ts

Temporal-based date and time utilities with timezone support and polyfill integration

export interface FormatCalendarUtcOptions {
    reference?: string;
    /**
     * IANA timezone used for both the calendar-day comparison and the
     * rendered clock time. Resolved via `normalizeTimeZone` — `"local"` for
     * the system zone, an invalid/omitted value falls back to `"UTC"`.
     */
    timeZone?: string;
    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
    timeStyle?: "short" | "medium" | "full";
}
/**
 * Format a UTC ISO string as a relative day label plus time-of-day, e.g.
 * "Tomorrow at 2:30 PM" — the UTC counterpart of `formatCalendar`. See that
 * function's JSDoc for the day-label/threshold/connector design; this
 * variant compares calendar days and renders the clock time in `timeZone`
 * (default `"UTC"`).
 *
 * @param value UTC ISO string to format
 * @param locale optional: BCP 47 locale tag
 * @param options optional: { reference, timeZone, timeStyle }
 * @returns the formatted calendar string, or "" on invalid input
 *
 * @example formatCalendarUtc("2026-03-16T18:30:00Z", "en-US", { timeZone: "America/New_York", reference: "2026-03-15T13:00:00Z" }) // "tomorrow at 2:30 PM"
 * @example formatCalendarUtc(value, "fr-FR", { timeZone: "Europe/Paris" }) // "demain à 14:30"
 * @example formatCalendarUtc("not-a-date") // ""
 */
export declare function formatCalendarUtc(value: string, locale?: string, options?: FormatCalendarUtcOptions): string;