@burglekitt/gmt/dist/zoned/format/formatCalendarZoned.d.ts

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

export interface FormatCalendarZonedOptions {
    /**
     * Anchor point for the relative diff.
     *
     * - ZonedDateTime ISO string: converted into `value`'s own zone before
     *   comparing calendar days. Unlike `formatRelativeZoned`'s `reference`
     *   (which keeps a ZonedDateTime reference in its own zone for
     *   elapsed-time diffing), a calendar *label* is meaningless without
     *   picking one zone's wall clock — `value`'s zone is the natural choice,
     *   since that is whose "today" is being described.
     * - UTC ISO string or numeric epoch (ms): placed into `value`'s timezone.
     * - Omitted: "now" in `value`'s own timezone.
     */
    reference?: string | number;
    /** `Intl.DateTimeFormatOptions` `timeStyle` for the time-of-day half. */
    timeStyle?: "short" | "medium" | "full";
}
/**
 * Format a zoned date-time as a relative day label plus time-of-day, e.g.
 * "Tomorrow at 2:30 PM" — the zoned counterpart of `formatCalendar`. See
 * that function's JSDoc for the day-label/threshold/connector design; this
 * variant differs only in reading `value`'s IANA timezone for both the
 * calendar-day comparison and the rendered clock time.
 *
 * @param value ZonedDateTime ISO string to format
 * @param locale optional: BCP 47 locale tag
 * @param options optional: { reference, timeStyle }
 * @returns the formatted calendar string, or "" on invalid input
 *
 * @example formatCalendarZoned("2026-03-16T14:30:00-04:00[America/New_York]", "en-US", { reference: "2026-03-15T09:00:00-04:00[America/New_York]" }) // "tomorrow at 2:30 PM"
 * @example formatCalendarZoned(value, "de-DE") // "morgen um 14:30"
 * @example formatCalendarZoned("not-a-date") // ""
 */
export declare function formatCalendarZoned(value: string, locale?: string, options?: FormatCalendarZonedOptions): string;