Internationalization

/**
 * Locale configuration interface from date-fns
 */
interface Locale {
  code: string;
  formatDistance?: Function;
  formatRelative?: Function;
  localize?: Function;
  formatLong?: Function;
  match?: Function;
  options?: {
    weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
    firstWeekContainsDate?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
  };
}

import { DayPicker } from "react-day-picker";
import { es, fr, de, ja } from "date-fns/locale";

// Spanish locale
<DayPicker locale={es} />

// French locale with Monday as first day of week
<DayPicker 
  locale={fr}
  weekStartsOn={1}
/>

// German locale
<DayPicker locale={de} />

// Japanese locale
<DayPicker locale={ja} />

// Multiple locales for different components
function MultiLingualCalendar({ userLocale }: { userLocale: string }) {
  const localeMap = {
    'es': es,
    'fr': fr, 
    'de': de,
    'ja': ja
  };
  
  return (
    <DayPicker 
      locale={localeMap[userLocale as keyof typeof localeMap]}
      weekStartsOn={userLocale === 'en' ? 0 : 1}
    />
  );
}

/**
 * A wrapper class around date-fns that provides utility methods for date 
 * manipulation and formatting with locale and timezone support
 */
class DateLib {
  /** The options for configuring the date library */
  readonly options: DateLibOptions;
  /** Overrides for the default date library functions */
  readonly overrides?: Partial<typeof DateLib.prototype>;
  
  /**
   * Creates an instance of DateLib
   * @param options - Configuration options for the date library
   * @param overrides - Custom overrides for the date library functions
   */
  constructor(options?: DateLibOptions, overrides?: Partial<typeof DateLib.prototype>);
  
  // Date creation
  /** Creates a new Date object representing today's date */
  today(): Date;
  /** Creates a new Date object with the specified year, month, and day */
  newDate(year: number, monthIndex: number, date: number): Date;
  
  // Date arithmetic
  /** Adds the specified number of days to the given date */
  addDays(date: Date, amount: number): Date;
  /** Adds the specified number of months to the given date */
  addMonths(date: Date, amount: number): Date;
  /** Adds the specified number of weeks to the given date */
  addWeeks(date: Date, amount: number): Date;
  /** Adds the specified number of years to the given date */
  addYears(date: Date, amount: number): Date;
  
  // Date differences
  /** Returns the number of calendar days between the given dates */
  differenceInCalendarDays(dateLeft: Date, dateRight: Date): number;
  /** Returns the number of calendar months between the given dates */
  differenceInCalendarMonths(dateLeft: Date, dateRight: Date): number;
  
  // Date ranges and intervals
  /** Returns the months between the given dates */
  eachMonthOfInterval(interval: { start: Date; end: Date }): Date[];
  
  // Week operations
  /** Returns the end of the broadcast week for the given date */
  endOfBroadcastWeek(date: Date): Date;
  /** Returns the end of the ISO week for the given date */
  endOfISOWeek(date: Date): Date;
  /** Returns the end of the week for the given date */
  endOfWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }): Date;
  /** Returns the start of the broadcast week for the given date */
  startOfBroadcastWeek(date: Date, dateLib: DateLib): Date;
  /** Returns the start of the ISO week for the given date */
  startOfISOWeek(date: Date): Date;
  /** Returns the start of the week for the given date */
  startOfWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 }): Date;
  
  // Period operations
  /** Returns the end of the month for the given date */
  endOfMonth(date: Date): Date;
  /** Returns the end of the year for the given date */
  endOfYear(date: Date): Date;
  /** Returns the start of the day for the given date */
  startOfDay(date: Date): Date;
  /** Returns the start of the month for the given date */
  startOfMonth(date: Date): Date;
  /** Returns the start of the year for the given date */
  startOfYear(date: Date): Date;
  
  // Date formatting and localization
  /** Formats the given date using the specified format string */
  format(date: Date, formatStr: string, options?: DateLibOptions): string;
  /** Formats a number using the configured numbering system */
  formatNumber(value: number | string): string;
  
  // Date getters
  /** Returns the ISO week number for the given date */
  getISOWeek(date: Date): number;
  /** Returns the month of the given date */
  getMonth(date: Date, options?: { locale?: Locale }): number;
  /** Returns the year of the given date */
  getYear(date: Date, options?: { locale?: Locale }): number;
  /** Returns the local week number for the given date */
  getWeek(date: Date, options?: { weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6; firstWeekContainsDate?: 1 | 4; locale?: Locale }): number;
  
  // Date setters
  /** Sets the month of the given date */
  setMonth(date: Date, month: number): Date;
  /** Sets the year of the given date */
  setYear(date: Date, year: number): Date;
  
  // Date comparison
  /** Checks if the first date is after the second date */
  isAfter(date: Date, dateToCompare: Date): boolean;
  /** Checks if the first date is before the second date */
  isBefore(date: Date, dateToCompare: Date): boolean;
  /** Checks if the given dates are on the same day */
  isSameDay(dateLeft: Date, dateRight: Date): boolean;
  /** Checks if the given dates are in the same month */
  isSameMonth(dateLeft: Date, dateRight: Date): boolean;
  /** Checks if the given dates are in the same year */
  isSameYear(dateLeft: Date, dateRight: Date): boolean;
  
  // Array operations
  /** Returns the latest date in the given array of dates */
  max(dates: Date[]): Date;
  /** Returns the earliest date in the given array of dates */
  min(dates: Date[]): Date;
  
  // Type checking
  /** Checks if the given value is a Date object */
  isDate(value: unknown): value is Date;
}

/**
 * Configuration options for the DateLib class
 */
interface DateLibOptions {
  /** A constructor for the Date object */
  Date?: typeof Date;
  /** A locale to use for formatting dates */
  locale?: Locale;
  /** A time zone to use for dates */
  timeZone?: string;
  /** The numbering system to use for formatting numbers */
  numerals?: Numerals;
  /** The index of the first day of the week (0 - Sunday) */
  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
  /** The day of January that is always in the first week of the year */
  firstWeekContainsDate?: 1 | 4;
  /** Enable DD and DDDD for week year tokens */
  useAdditionalWeekYearTokens?: boolean;
  /** Enable YY and YYYY for day of year tokens */
  useAdditionalDayOfYearTokens?: boolean;
}

/**
 * Numeral system types supported for formatting
 */
type Numerals = 
  | "latn"     // Latin (Western Arabic)
  | "arab"     // Arabic-Indic
  | "arabext"  // Eastern Arabic-Indic (Persian)
  | "deva"     // Devanagari
  | "beng"     // Bengali
  | "guru"     // Gurmukhi
  | "gujr"     // Gujarati
  | "orya"     // Oriya
  | "tamldec"  // Tamil
  | "telu"     // Telugu
  | "knda"     // Kannada
  | "mlym";    // Malayalam

import { DateLib } from "react-day-picker";
import { fr } from "date-fns/locale";

// Create custom DateLib with French locale
const frenchDateLib = new DateLib({
  locale: fr,
  weekStartsOn: 1, // Monday
  firstWeekContainsDate: 4
});

// Use with DayPicker
<DayPicker dateLib={frenchDateLib} />

// Custom date operations
const today = new Date();
const nextWeek = frenchDateLib.addDays(today, 7);
const formatted = frenchDateLib.format(nextWeek, "EEEE, d MMMM yyyy");
// Result: "lundi, 15 janvier 2024" (in French)

/**
 * Persian calendar DayPicker component
 * Available from "react-day-picker/persian"
 */
function DayPicker(props: DayPickerProps): React.ReactElement;

/**
 * Get DateLib configured for Persian calendar
 * @param options - Persian calendar options
 * @returns DateLib instance for Persian dates
 */
function getDateLib(options?: PersianDateLibOptions): DateLib;

interface PersianDateLibOptions extends DateLibOptions {
  /** Persian locale (default: faIR) */
  locale?: Locale;
  /** Week starts on Saturday for Persian calendar */
  weekStartsOn?: 6;
}

/** Persian locale */
const faIR: Locale;

/** English locale for Persian calendar */
const enUS: Locale;

// Import Persian calendar variant
import { DayPicker } from "react-day-picker/persian";
import "react-day-picker/style.css";

// Basic Persian calendar
function PersianCalendar() {
  const [selected, setSelected] = useState<Date>();
  
  return (
    <DayPicker
      mode="single"
      selected={selected}
      onSelect={setSelected}
      dir="rtl" // Right-to-left text direction
    />
  );
}

// Persian calendar with custom configuration
import { DayPicker, getDateLib, faIR } from "react-day-picker/persian";

function CustomPersianCalendar() {
  const persianDateLib = getDateLib({
    locale: faIR,
    weekStartsOn: 6 // Saturday
  });
  
  return (
    <DayPicker
      mode="single"
      dateLib={persianDateLib}
      dir="rtl"
      weekStartsOn={6}
    />
  );
}

/**
 * Time zone aware Date class (re-exported from @date-fns/tz)
 */
class TZDate extends Date {
  constructor(date: Date | string | number, timeZone: string);
  
  /** Get the time zone identifier */
  getTimezone(): string;
  /** Convert to different time zone */
  withTimeZone(timeZone: string): TZDate;
}

/**
 * DayPicker props for time zone support
 */
interface PropsBase {
  /** Time zone identifier (e.g., "America/New_York") */
  timeZone?: string;
  /** Current date in the specified time zone */
  today?: Date | TZDate;
  /** Selected dates in the specified time zone */
  selected?: Date | TZDate | (Date | TZDate)[] | DateRange;
}

import { DayPicker, TZDate } from "react-day-picker";

// Calendar with New York time zone
function TimeZoneCalendar() {
  const [selected, setSelected] = useState<Date>();
  const timeZone = "America/New_York";
  
  return (
    <DayPicker
      mode="single"
      selected={selected}
      onSelect={setSelected}
      timeZone={timeZone}
      today={new TZDate(new Date(), timeZone)}
    />
  );
}

// Multi-timezone calendar
function MultiTimezoneCalendar() {
  const [timezone, setTimezone] = useState("UTC");
  const [selected, setSelected] = useState<Date>();
  
  const timezones = [
    "UTC",
    "America/New_York", 
    "Europe/London",
    "Asia/Tokyo"
  ];
  
  return (
    <div>
      <select value={timezone} onChange={(e) => setTimezone(e.target.value)}>
        {timezones.map(tz => (
          <option key={tz} value={tz}>{tz}</option>
        ))}
      </select>
      
      <DayPicker
        mode="single"
        selected={selected}
        onSelect={setSelected}
        timeZone={timezone}
        today={new TZDate(new Date(), timezone)}
      />
    </div>
  );
}

/**
 * Numeral system enumeration
 */
enum Numerals {
  /** Western Arabic numerals (0-9) */
  latn = "latn",
  /** Arabic-Indic numerals (٠-٩) */
  arab = "arab", 
  /** Extended Arabic-Indic numerals */
  arabext = "arabext",
  /** Persian numerals (۰-۹) */
  pers = "pers"
}

/**
 * Props for custom numeral system
 */
interface PropsBase {
  /** Numeral system for date display */
  numerals?: Numerals;
}

import { DayPicker, Numerals } from "react-day-picker";
import { ar } from "date-fns/locale";

// Arabic calendar with Arabic-Indic numerals
<DayPicker
  locale={ar}
  numerals={Numerals.arab}
  dir="rtl"
/>

// Persian calendar with Persian numerals  
import { DayPicker } from "react-day-picker/persian";

<DayPicker
  numerals={Numerals.pers}
  dir="rtl"
/>

/**
 * Props for broadcast calendar support
 */
interface PropsBase {
  /** Enable broadcast calendar (weeks start on Monday, 4-4-5 week pattern) */
  broadcastCalendar?: boolean;
}

/**
 * Helper functions for broadcast calendar
 */
function startOfBroadcastWeek(date: Date): Date;
function endOfBroadcastWeek(date: Date): Date;
function getBroadcastWeeksInMonth(date: Date): CalendarWeek[];

// Broadcast calendar for retail/TV industry
<DayPicker
  broadcastCalendar={true}
  weekStartsOn={1} // Always Monday for broadcast calendar
  showWeekNumber={true}
/>

// Custom broadcast week calculations
import { startOfBroadcastWeek, endOfBroadcastWeek } from "react-day-picker";

const today = new Date();
const weekStart = startOfBroadcastWeek(today);
const weekEnd = endOfBroadcastWeek(today);
console.log(`Broadcast week: ${weekStart} to ${weekEnd}`);