Date and Time Formatting

/**
 * Component for locale-aware date formatting
 * Supports all Intl.DateTimeFormat options plus custom format configurations
 */
const FormattedDate: React.FC<
  Intl.DateTimeFormatOptions & 
  CustomFormatConfig & {
    /** Date value to format (Date object, timestamp, or ISO string) */
    value: string | number | Date | undefined;
    /** Render prop receiving formatted date string */
    children?(formattedDate: string): React.ReactElement | null;
  }
>;

import { FormattedDate } from "react-intl";

// Basic date formatting
<FormattedDate value={new Date()} />

// Custom date format
<FormattedDate 
  value={new Date()} 
  year="numeric" 
  month="long" 
  day="numeric" 
/>

// Named format (requires format definition in IntlProvider)
<FormattedDate value={new Date()} format="short" />

// Render prop pattern
<FormattedDate value={userRegistrationDate}>
  {(formattedDate) => (
    <span className="registration-date">
      Member since {formattedDate}
    </span>
  )}
</FormattedDate>

// Different locales format differently
// en-US: "12/25/2023"
// de-DE: "25.12.2023" 
// ja-JP: "2023/12/25"

/**
 * Component for locale-aware time formatting
 * Supports all Intl.DateTimeFormat time options plus custom configurations
 */
const FormattedTime: React.FC<
  Intl.DateTimeFormatOptions & 
  CustomFormatConfig & {
    /** Time value to format (Date object, timestamp, or ISO string) */
    value: string | number | Date | undefined;
    /** Render prop receiving formatted time string */
    children?(formattedTime: string): React.ReactElement | null;
  }
>;

import { FormattedTime } from "react-intl";

// Basic time formatting  
<FormattedTime value={new Date()} />

// 12-hour format with seconds
<FormattedTime 
  value={new Date()} 
  hour12={true}
  hour="numeric"
  minute="2-digit"
  second="2-digit"
/>

// 24-hour format
<FormattedTime 
  value={new Date()} 
  hour12={false}
  hour="2-digit" 
  minute="2-digit"
/>

/**
 * Component for relative time formatting with optional auto-updating
 * @param props - Relative time configuration and update options
 */
function FormattedRelativeTime(props: FormatRelativeTimeOptions & {
  /** Relative time value (number of units) */
  value?: number;
  /** Time unit for the value */
  unit?: Intl.RelativeTimeFormatUnit;
  /** Interval in seconds for automatic updates */
  updateIntervalInSeconds?: number;
  /** Render prop receiving formatted relative time string */
  children?(value: string): React.ReactElement | null;
}): React.ReactElement;

import { FormattedRelativeTime } from "react-intl";

// Static relative time
<FormattedRelativeTime value={-1} unit="day" />
// Output: "1 day ago"

<FormattedRelativeTime value={2} unit="hour" />
// Output: "in 2 hours"

// Auto-updating relative time
<FormattedRelativeTime 
  value={-30} 
  unit="second"
  updateIntervalInSeconds={1}
/>
// Updates every second: "30 seconds ago", "31 seconds ago", etc.

// Numeric style options
<FormattedRelativeTime 
  value={-1} 
  unit="day"
  numeric="auto"
/>
// Output: "yesterday" (vs "1 day ago" with numeric="always")

// Different locales
// en: "3 minutes ago"
// es: "hace 3 minutos"
// ja: "3分前"

/**
 * Component for formatting date/time ranges
 * @param props - Date range values and formatting options
 */
function FormattedDateTimeRange(props: FormatDateTimeRangeOptions & {
  /** Start date/time of the range */
  from: Parameters<Intl.DateTimeFormat['formatRange']>[0];
  /** End date/time of the range */
  to: Parameters<Intl.DateTimeFormat['formatRange']>[1];
  /** Render prop receiving formatted range string */
  children?(value: React.ReactNode): React.ReactElement | null;
}): React.ReactElement;

import { FormattedDateTimeRange } from "react-intl";

// Date range
<FormattedDateTimeRange 
  from={new Date('2023-12-01')} 
  to={new Date('2023-12-03')}
/>
// Output: "Dec 1 – 3, 2023"

// Time range
<FormattedDateTimeRange
  from={new Date('2023-12-01T09:00:00')}
  to={new Date('2023-12-01T17:00:00')}
  hour="numeric"
  minute="2-digit"
/>
// Output: "9:00 AM – 5:00 PM"

// Cross-day range
<FormattedDateTimeRange
  from={new Date('2023-12-01T22:00:00')}
  to={new Date('2023-12-02T02:00:00')}
  month="short"
  day="numeric"
  hour="numeric"
/>
// Output: "Dec 1, 10 PM – Dec 2, 2 AM"

/**
 * Component for accessing formatted date parts
 * Useful for custom date rendering and styling
 */
const FormattedDateParts: React.FC<
  FormatDateOptions & {
    /** Date value to format into parts */
    value: Parameters<Intl.DateTimeFormat['format']>[0] | string;
    /** Render prop receiving array of date parts */
    children(val: Intl.DateTimeFormatPart[]): React.ReactElement | null;
  }
>;

/**
 * Component for accessing formatted time parts
 * Useful for custom time rendering and styling
 */
const FormattedTimeParts: React.FC<
  FormatDateOptions & {
    /** Time value to format into parts */
    value: Parameters<Intl.DateTimeFormat['format']>[0] | string;
    /** Render prop receiving array of time parts */
    children(val: Intl.DateTimeFormatPart[]): React.ReactElement | null;
  }
>;

import { FormattedDateParts, FormattedTimeParts } from "react-intl";

// Custom date rendering with parts
<FormattedDateParts 
  value={new Date()} 
  year="numeric" 
  month="long" 
  day="numeric"
>
  {(parts) => (
    <div className="custom-date">
      {parts.map((part, index) => (
        <span 
          key={index} 
          className={`date-${part.type}`}
        >
          {part.value}
        </span>
      ))}
    </div>
  )}
</FormattedDateParts>

// Custom time with highlighted hours
<FormattedTimeParts 
  value={new Date()} 
  hour="2-digit" 
  minute="2-digit"
>
  {(parts) => (
    <div>
      {parts.map((part, index) => (
        <span 
          key={index}
          className={part.type === 'hour' ? 'highlight' : ''}
        >
          {part.value}
        </span>
      ))}
    </div>
  )}
</FormattedTimeParts>

interface FormatDateOptions extends Intl.DateTimeFormatOptions {
  format?: string;
}

interface FormatRelativeTimeOptions {
  /** Formatting style for relative time */
  style?: 'long' | 'short' | 'narrow';
  /** Whether to use numeric format always or auto (yesterday vs 1 day ago) */
  numeric?: 'always' | 'auto';
  /** Locale matcher algorithm */
  localeMatcher?: 'best fit' | 'lookup';
}

interface FormatDateTimeRangeOptions extends Intl.DateTimeFormatOptions {
  format?: string;
}

// Standard Intl.RelativeTimeFormatUnit
type RelativeTimeFormatUnit = 
  | 'year' | 'years'
  | 'quarter' | 'quarters' 
  | 'month' | 'months'
  | 'week' | 'weeks'
  | 'day' | 'days'
  | 'hour' | 'hours'
  | 'minute' | 'minutes'
  | 'second' | 'seconds';

// Date/time format parts
interface DateTimeFormatPart {
  type: 'era' | 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'weekday' | 'dayPeriod' | 'timeZoneName' | 'literal';
  value: string;
}