System Design #7: Design a Calendar / Date Picker

// Pop quiz: what does this return?
new Date(2024, 1, 30) // → March 1, 2024 (not Feb 30, it overflows!)
new Date("2024-01-15") // → Jan 14 in UTC-5 timezones (midnight UTC = previous day local)
new Date("01/15/2024") // → Jan 15 local time (different parsing!)

DatePicker
├── DatePickerTrigger    // Button showing selected date(s)
├── DatePickerPopover    // Floating panel (via floating-ui)
│   ├── CalendarHeader   // Month/Year nav + view switcher
│   ├── CalendarGrid     // The actual day grid
│   │   ├── WeekdayHeaders
│   │   └── DayCell[]    // Individual day buttons
│   ├── PresetPanel      // "Last 7 days", "This month"
│   └── TimePicker       // Optional HH:MM selector
└── HiddenInput          // For form submission

type RangeState = 
  | { phase: 'idle' }
  | { phase: 'selecting-start'; hoveredDate: string | null }
  | { phase: 'selecting-end'; start: string; hoveredDate: string | null }
  | { phase: 'complete'; start: string; end: string };

function rangeReducer(state: RangeState, action: RangeAction): RangeState {
  switch (action.type) {
    case 'CLICK_DATE':
      if (state.phase === 'idle' || state.phase === 'complete') {
        return { phase: 'selecting-end', start: action.date, hoveredDate: null };
      }
      if (state.phase === 'selecting-end') {
        const [start, end] = action.date < state.start
          ? [action.date, state.start]  // Auto-swap if end < start
          : [state.start, action.date];
        return { phase: 'complete', start, end };
      }
      return state;
      
    case 'HOVER_DATE':
      if (state.phase === 'selecting-end') {
        return { ...state, hoveredDate: action.date };
      }
      return state;
      
    case 'RESET':
      return { phase: 'idle' };
  }
}

interface CalendarMonth {
  year: number;
  month: number; // 0-indexed to match JS Date API
  weeks: CalendarWeek[];
}

interface CalendarWeek {
  days: CalendarDay[];
}

interface CalendarDay {
  date: string;           // "2024-03-15" — the source of truth
  dayOfMonth: number;     // 15
  isCurrentMonth: boolean; // false for leading/trailing days
  isToday: boolean;
  isDisabled: boolean;
  isSelected: boolean;
  isInRange: boolean;      // For range highlighting
  isRangeStart: boolean;
  isRangeEnd: boolean;
}

function generateMonth(year: number, month: number, weekStartsOn: 0 | 1 = 0): CalendarDay[][] {
  const firstDay = new Date(year, month, 1);
  const lastDay = new Date(year, month + 1, 0);
  
  // Calculate leading days from previous month
  let startOffset = firstDay.getDay() - weekStartsOn;
  if (startOffset < 0) startOffset += 7;
  
  const days: CalendarDay[] = [];
  const startDate = new Date(firstDay);
  startDate.setDate(startDate.getDate() - startOffset);
  
  // Always generate 42 cells (6 weeks) for consistent grid height
  for (let i = 0; i < 42; i++) {
    const current = new Date(startDate);
    current.setDate(current.getDate() + i);
    const dateStr = formatDateString(current);
    
    days.push({
      date: dateStr,
      dayOfMonth: current.getDate(),
      isCurrentMonth: current.getMonth() === month,
      isToday: dateStr === getTodayString(),
      isDisabled: false, // Applied later via props
      isSelected: false, // Applied later via state
      isInRange: false,
      isRangeStart: false,
      isRangeEnd: false,
    });
  }
  
  // Chunk into weeks of 7
  return Array.from({ length: 6 }, (_, i) => days.slice(i * 7, (i + 1) * 7));
}

function formatDateString(d: Date): string {
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

interface DatePickerProps {
  mode: 'single' | 'range';
  value: string | null;                    // "YYYY-MM-DD" for single
  range?: { start: string; end: string }; // For range mode
  onChange: (date: string | null) => void;
  onRangeChange?: (range: { start: string; end: string } | null) => void;
  
  // Constraints
  minDate?: string;
  maxDate?: string;
  disabledDates?: string[] | ((date: string) => boolean);
  
  // Locale
  locale?: string;           // "en-US", "de-DE"
  weekStartsOn?: 0 | 1;     // 0 = Sunday, 1 = Monday
  
  // Display
  placeholder?: string;
  format?: string;           // "MM/dd/yyyy", "dd.MM.yyyy"
  presets?: DatePreset[];    // Quick-select options
  showTimePicker?: boolean;
  
  // Form integration
  name?: string;
  required?: boolean;
  disabled?: boolean;
}

<div role="grid" aria-label={`${monthName} ${year}`}>
  <div role="row">
    {weekdays.map(day => (
      <div key={day} role="columnheader" abbr={day.full}>{day.short}</div>
    ))}
  </div>
  {weeks.map((week, i) => (
    <div key={i} role="row">
      {week.map(day => (
        <button
          key={day.date}
          role="gridcell"
          tabIndex={day.date === focusedDate ? 0 : -1}
          aria-selected={day.isSelected}
          aria-disabled={day.isDisabled}
          aria-current={day.isToday ? 'date' : undefined}
          onClick={() => handleSelect(day.date)}
        >
          {day.dayOfMonth}
        </button>
      ))}
    </div>
  ))}
</div>
<div aria-live="polite" className="sr-only">
  {announcement} {/* "March 2024" on month change */}
</div>

function handleGridKeyDown(e: KeyboardEvent, currentDate: string) {
  const d = parseDate(currentDate);
  let next: string | null = null;
  
  switch (e.key) {
    case 'ArrowRight': next = addDays(d, 1); break;
    case 'ArrowLeft':  next = addDays(d, -1); break;
    case 'ArrowDown':  next = addDays(d, 7); break;  // Next week
    case 'ArrowUp':    next = addDays(d, -7); break;  // Prev week
    case 'Home':       next = startOfWeek(d); break;
    case 'End':        next = endOfWeek(d); break;
    case 'PageDown':   next = addMonths(d, 1); break; // Next month
    case 'PageUp':     next = addMonths(d, -1); break;
    case 'Enter':
    case ' ':
      e.preventDefault();
      handleSelect(currentDate);
      return;
  }
  
  if (next) {
    e.preventDefault();
    setFocusedDate(next);
    // If next is outside current month view, navigate the month
    if (getMonth(next) !== displayedMonth) {
      setDisplayedMonth(getMonth(next));
    }
  }
}

const calendarGrid = useMemo(() => {
  const weeks = generateMonth(displayYear, displayMonth, weekStartsOn);
  
  // Apply selection state
  return weeks.map(week =>
    week.map(day => ({
      ...day,
      isDisabled: isDateDisabled(day.date, minDate, maxDate, disabledDates),
      isSelected: mode === 'single' ? day.date === value : false,
      isInRange: mode === 'range' ? isInRange(day.date, rangeStart, rangeEndOrHovered) : false,
      isRangeStart: day.date === rangeStart,
      isRangeEnd: day.date === (rangeEnd || hoveredDate),
    }))
  );
}, [displayYear, displayMonth, weekStartsOn, value, rangeStart, rangeEnd, hoveredDate, minDate, maxDate]);

// Slide direction based on month navigation
const [direction, setDirection] = useState<'left' | 'right'>('left');

function navigateMonth(delta: number) {
  setDirection(delta > 0 ? 'left' : 'right');
  setDisplayedMonth(prev => {
    const d = new Date(prev.year, prev.month + delta);
    return { year: d.getFullYear(), month: d.getMonth() };
  });
}

// In render — CSS transition or framer-motion
<AnimatePresence mode="popLayout" initial={false}>
  <motion.div
    key={`${displayYear}-${displayMonth}`}
    initial={{ x: direction === 'left' ? 50 : -50, opacity: 0 }}
    animate={{ x: 0, opacity: 1 }}
    exit={{ x: direction === 'left' ? -50 : 50, opacity: 0 }}
    transition={{ duration: 0.2 }}
  >
    <CalendarGrid weeks={calendarGrid} />
  </motion.div>
</AnimatePresence>

// Skip date-fns/moment — these 5 functions cover 95% of calendar needs
function addDays(dateStr: string, days: number): string {
  const [y, m, d] = dateStr.split('-').map(Number);
  const date = new Date(y, m - 1, d + days);
  return formatDateString(date);
}

function addMonths(dateStr: string, months: number): string {
  const [y, m, d] = dateStr.split('-').map(Number);
  const date = new Date(y, m - 1 + months, d);
  // Clamp: if March 31 + 1 month → April 30 (not May 1)
  const targetMonth = (m - 1 + months) % 12;
  if (date.getMonth() !== (targetMonth < 0 ? targetMonth + 12 : targetMonth)) {
    date.setDate(0); // Go to last day of previous month
  }
  return formatDateString(date);
}

function diffDays(a: string, b: string): number {
  const da = new Date(a + 'T00:00:00');
  const db = new Date(b + 'T00:00:00');
  return Math.round((db.getTime() - da.getTime()) / 86400000);
}

function isInRange(date: string, start: string | null, end: string | null): boolean {
  if (!start || !end) return false;
  return date >= start && date <= end;
}

function getTodayString(): string {
  const now = new Date();
  return formatDateString(now);
}