Date and Time Formatting

/**
 * Provides localized date formatting for the current locale. Automatically updates when the locale changes,
 * and handles caching of the date formatter for performance.
 * @param options - Formatting options extending Intl.DateTimeFormatOptions
 * @returns DateFormatter instance from @internationalized/date
 */
function useDateFormatter(options?: DateFormatterOptions): DateFormatter;

interface DateFormatterOptions extends Intl.DateTimeFormatOptions {
  /** Calendar system to use (e.g., 'gregory', 'buddhist', 'islamic') */
  calendar?: string;
}

import { useDateFormatter, I18nProvider } from "@react-aria/i18n";

// Basic date formatting
function DateDisplay() {
  const formatter = useDateFormatter({ 
    dateStyle: "long" 
  });
  
  return <p>{formatter.format(new Date())}</p>;
  // US English: "December 25, 2023"
  // Spanish: "25 de diciembre de 2023"
}

// Time formatting with specific options
function TimeDisplay() {
  const formatter = useDateFormatter({
    timeStyle: "medium",
    hour12: false
  });
  
  return <p>{formatter.format(new Date())}</p>;
  // "14:30:00"
}

// Custom format with multiple fields
function CustomDateFormat() {
  const formatter = useDateFormatter({
    weekday: "long",
    year: "numeric",
    month: "long",
    day: "numeric"
  });
  
  return <p>{formatter.format(new Date())}</p>;
  // "Monday, December 25, 2023"
}

// Calendar-specific formatting
function BuddhistCalendarDate() {
  const formatter = useDateFormatter({
    calendar: "buddhist",
    dateStyle: "full"
  });
  
  return <p>{formatter.format(new Date())}</p>;
  // Uses Buddhist calendar era
}

// Responsive to locale changes
function LocaleAwareDateDisplay() {
  return (
    <div>
      <I18nProvider locale="en-US">
        <DateDisplay />
      </I18nProvider>
      <I18nProvider locale="ja-JP">
        <DateDisplay />
      </I18nProvider>
    </div>
  );
}

interface DateFormatter {
  /** Format a date to a string */
  format(date: Date): string;
  /** Format a date to an array of parts with type information */
  formatToParts(date: Date): Intl.DateTimeFormatPart[];
  /** Format a date range between two dates */
  formatRange(startDate: Date, endDate: Date): string;
  /** Format a date range to parts */
  formatRangeToParts(startDate: Date, endDate: Date): Intl.DateTimeFormatPart[];
  /** Get resolved formatting options */
  resolvedOptions(): Intl.ResolvedDateTimeFormatOptions;
}

function AdvancedDateFormatting() {
  const formatter = useDateFormatter({
    year: "numeric",
    month: "long",
    day: "numeric"
  });
  
  const date = new Date();
  const startDate = new Date();
  const endDate = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days later
  
  return (
    <div>
      {/* Basic formatting */}
      <p>Date: {formatter.format(date)}</p>
      
      {/* Parts formatting for custom styling */}
      <p>
        Parts: {formatter.formatToParts(date).map((part, i) => (
          <span key={i} className={`date-${part.type}`}>
            {part.value}
          </span>
        ))}
      </p>
      
      {/* Date range formatting */}
      <p>Range: {formatter.formatRange(startDate, endDate)}</p>
      
      {/* Resolved options inspection */}
      <p>Locale: {formatter.resolvedOptions().locale}</p>
    </div>
  );
}

// Examples with different calendar systems
function MultiCalendarDisplay() {
  const gregorianFormatter = useDateFormatter({
    calendar: "gregory",
    dateStyle: "long"
  });
  
  const islamicFormatter = useDateFormatter({
    calendar: "islamic",
    dateStyle: "long"
  });
  
  const buddhistFormatter = useDateFormatter({
    calendar: "buddhist", 
    dateStyle: "long"
  });
  
  const date = new Date();
  
  return (
    <div>
      <p>Gregorian: {gregorianFormatter.format(date)}</p>
      <p>Islamic: {islamicFormatter.format(date)}</p>  
      <p>Buddhist: {buddhistFormatter.format(date)}</p>
    </div>
  );
}