Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
3.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file getInitialFocusDate.ts
 * @input PlainDate and calendar-system utilities, min/max bounds, today
 * @output Exports getInitialFocusDate — the month Calendar opens on
 * @position Calendar-specific helper; used by Calendar.tsx
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Calendar/getInitialFocusDate.test.ts
 * - /packages/core/src/Calendar/Calendar.tsx (the only caller)
 */

import type {ISODateString, DateRange} from '../utils/dateTypes';
import {
  type PlainDate,
  plainDateFromISO,
  plainDateIsBefore,
  plainDateIsAfter,
} from '../utils/plainDate';
import {
  type CalendarSystem,
  calendarAddMonths,
  calendarMonthOf,
} from '../utils/calendarSystem';

export interface InitialFocusDateOptions {
  /** Controlled visible month, if the consumer supplied one. */
  focusDate?: ISODateString;
  /** Selected value (single date or range), controlled or uncontrolled. */
  value?: ISODateString | DateRange;
  /** Earliest selectable date. */
  min?: ISODateString;
  /** Latest selectable date. */
  max?: ISODateString;
  /** How many month panes the calendar renders (1 or 2). */
  numberOfMonths: number;
  /**
   * Today, injected so the caller keeps one source of "now"; `null` when it is
   * not known yet (server render, hydration).
   */
  today: PlainDate | null;
  /** The calendar system whose months the panes show. Default: `gregory`. */
  calendar?: CalendarSystem;
}

/**
 * Picks the date whose month the calendar opens on.
 *
 * An explicit `focusDate` wins, then the selected value — both are the
 * consumer's own instruction about where to look, so neither is second-guessed
 * against `min`/`max`.
 *
 * Otherwise the calendar opens on today, clamped into the `min`/`max` window,
 * or returns `null` while today is not known yet.
 * Without the clamp a window that doesn't contain today (a 2019 audit range, a
 * booking window opening next spring) opened on today's month with every day
 * disabled, leaving prev/next clicking as the only way in.
 *
 * When clamping forward to `min`, that month leads: the whole selectable window
 * runs ahead of it. When clamping back to `max`, the last pane lands on `max`'s
 * month instead — with `numberOfMonths={2}` opening on `[max, max + 1]` would
 * spend half the calendar on a month that is entirely out of bounds. That
 * shift never crosses `min`'s month.
 */
export function getInitialFocusDate(
  options: InitialFocusDateOptions,
): PlainDate | null {
  const {
    focusDate,
    value,
    min,
    max,
    numberOfMonths,
    today,
    calendar = 'gregory',
  } = options;

  if (focusDate) {
    return plainDateFromISO(focusDate);
  }

  if (value) {
    return plainDateFromISO(typeof value === 'string' ? value : value.start);
  }

  // Without a focus date or a value the month follows today, which is not
  // known yet on the server and while hydrating.
  if (today == null) {
    return null;
  }

  const minDate = min ? plainDateFromISO(min) : null;
  const maxDate = max ? plainDateFromISO(max) : null;

  if (minDate && plainDateIsBefore(today, minDate)) {
    return minDate;
  }

  if (maxDate && plainDateIsAfter(today, maxDate)) {
    const lastPaneOffset = Math.max(0, numberOfMonths - 1);
    const shifted = calendarAddMonths(
      calendar,
      calendarMonthOf(calendar, maxDate),
      -lastPaneOffset,
    ).start;
    if (
      minDate &&
      plainDateIsBefore(shifted, calendarMonthOf(calendar, minDate).start)
    ) {
      return minDate;
    }
    return shifted;
  }

  return today;
}