@base-ui/react 1.2.0 → 1.4.0

package/esm/calendar/store/selectors.js

@@ -0,0 +1,192 @@
+import { createSelector, createSelectorMemoized } from '@base-ui/utils/store';
+import { getInitialReferenceDate } from "../../utils/temporal/getInitialReferenceDate.js";
+import { validateDate } from "../../utils/temporal/validateDate.js";
+const timezoneToRenderSelector = createSelectorMemoized(state => state.adapter, state => state.manager, state => state.value, state => state.timezoneProp, state => state.referenceDateProp, (adapter, manager, value, timezoneProp, referenceDateProp) => {
+  if (timezoneProp != null) {
+    return timezoneProp;
+  }
+  const valueTimezone = manager.getTimezone(value);
+  if (valueTimezone) {
+    return valueTimezone;
+  }
+  if (referenceDateProp) {
+    return adapter.getTimezone(referenceDateProp);
+  }
+  return 'default';
+});
+const validationPropsSelector = createSelectorMemoized(state => state.minDate, state => state.maxDate, (minDate, maxDate) => ({
+  minDate,
+  maxDate
+}));
+const referenceDateSelector = createSelectorMemoized(state => state.adapter, timezoneToRenderSelector, state => state.initialReferenceDateFromValue, validationPropsSelector, state => state.referenceDateProp, (adapter, timezone, initialReferenceDateFromValue, validationProps, referenceDateProp) => getInitialReferenceDate({
+  adapter,
+  timezone,
+  validationProps,
+  externalReferenceDate: referenceDateProp,
+  externalDate: initialReferenceDateFromValue
+}));
+const valueWithTimezoneToRenderSelector = createSelectorMemoized(timezoneToRenderSelector, state => state.manager, state => state.value, (timezone, manager, value) => manager.setTimezone(value, timezone));
+const selectedDatesSelector = createSelectorMemoized(state => state.manager, state => state.value, timezoneToRenderSelector, (manager, value, timezone) => manager.getDatesFromValue(value).map(date => {
+  if (manager.getTimezone(date) === timezone) {
+    return date;
+  }
+  return manager.setTimezone(date, timezone);
+}));
+const isDayCellDisabledSelector = createSelector((state, value) => {
+  if (state.disabled) {
+    return true;
+  }
+  const validationError = validateDate({
+    adapter: state.adapter,
+    value,
+    validationProps: validationPropsSelector(state)
+  });
+  return validationError != null;
+});
+const isDayCellUnavailableSelector = createSelector((state, value) => state.isDateUnavailable?.(value) ?? false);
+const isDayButtonSelectedSelector = createSelector(state => state.adapter, selectedDatesSelector, (adapter, selectedDates, cellValue) => {
+  return selectedDates.some(date => adapter.isSameDay(cellValue, date));
+});
+const isSetMonthButtonDisabledSelector = createSelector(state => state.adapter, validationPropsSelector, state => state.disabled, (adapter, validationProps, isCalendarDisabled, targetDate, disabledProp) => {
+  // short-circuit if the disabled prop is explicitly provided.
+  if (disabledProp !== undefined) {
+    return disabledProp;
+  }
+  if (isCalendarDisabled) {
+    return true;
+  }
+
+  // The month targeted and all the months before are fully disabled, we disable the button.
+  if (validationProps.minDate != null && adapter.isBefore(adapter.endOfMonth(targetDate), validationProps.minDate)) {
+    return true;
+  }
+
+  // The month targeted and all the months after are fully disabled, we disable the button.
+  return validationProps.maxDate != null && adapter.isAfter(adapter.startOfMonth(targetDate), validationProps.maxDate);
+});
+const visibleDateSelector = createSelectorMemoized(state => state.visibleDateProp, state => state.visibleDate, state => state.adapter, timezoneToRenderSelector, (visibleDateProp, visibleDate, adapter, timezone) => adapter.setTimezone(visibleDateProp ?? visibleDate, timezone));
+const visibleMonthSelector = createSelectorMemoized(state => state.adapter, visibleDateSelector, (adapter, date) => adapter.startOfMonth(date));
+const isValueInvalidSelector = createSelectorMemoized(state => state.manager, state => state.invalidProp, valueWithTimezoneToRenderSelector, validationPropsSelector, (manager, invalidProp, value, validationProps) => {
+  if (invalidProp != null) {
+    return invalidProp;
+  }
+  const error = manager.getValidationError(value, validationProps);
+  return !manager.isValidationErrorEmpty(error);
+});
+const rootElementStateSelector = createSelectorMemoized(state => state.manager, state => state.readOnly, state => state.disabled, state => state.navigationDirection, isValueInvalidSelector, valueWithTimezoneToRenderSelector, (manager, readOnly, disabled, navigationDirection, invalid, value) => ({
+  empty: manager.areValuesEqual(value, manager.emptyValue),
+  invalid,
+  disabled,
+  readOnly,
+  navigationDirection
+}));
+const publicContextSelector = createSelectorMemoized(visibleDateSelector, visibleDate => ({
+  visibleDate
+}));
+const getMonthKey = (adapter, date) => `${adapter.getYear(date)}-${adapter.getMonth(date)}`;
+const getDateKey = (adapter, date) => adapter.getTime(date);
+const tabbableCellsPerMonthSelector = createSelectorMemoized(state => state.adapter, selectedDatesSelector, referenceDateSelector, (adapter, selectedDates, referenceDate) => {
+  const months = new Map();
+
+  // Each month that contains selected dates has these selected dates as tabbable cells.
+  for (const date of selectedDates) {
+    const monthKey = getMonthKey(adapter, date);
+    if (!months.has(monthKey)) {
+      months.set(monthKey, new Set());
+    }
+    months.get(monthKey).add(getDateKey(adapter, date));
+  }
+
+  // If the month containing the reference dates has no selected dates, then the reference date will be tabbable in this month.
+  const referenceDateMonthKey = getMonthKey(adapter, referenceDate);
+  if (!months.has(referenceDateMonthKey)) {
+    months.set(referenceDateMonthKey, new Set([getDateKey(adapter, referenceDate)]));
+  }
+  return months;
+});
+const isDayButtonTabbableSelector = createSelector(tabbableCellsPerMonthSelector, state => state.adapter, (tabbableCellsPerMonth, adapter, date, month) => {
+  // If the date is not in the current month, it cannot be tabbable.
+  if (!adapter.isSameMonth(date, month)) {
+    return false;
+  }
+  const monthKey = getMonthKey(adapter, date);
+
+  // If the month has registered tabbable cells, we check if the date is one of them.
+  if (tabbableCellsPerMonth.has(monthKey)) {
+    const dateKey = getDateKey(adapter, date);
+    return tabbableCellsPerMonth.get(monthKey).has(dateKey);
+  }
+
+  // Otherwise, only the first day of the month is tabbable.
+  const firstDayOfMonth = adapter.startOfMonth(date);
+  return adapter.isSameDay(date, firstDayOfMonth);
+});
+export const selectors = {
+  /**
+   * Returns the timezone to use for rendering.
+   */
+  timezoneToRender: timezoneToRenderSelector,
+  /**
+   * Returns the state of the root element.
+   */
+  rootElementState: rootElementStateSelector,
+  /**
+   * Returns the context to publicly expose in render functions and hooks.
+   */
+  publicContext: publicContextSelector,
+  /**
+   * Returns the props to check if a date is valid or not.
+   */
+  validationProps: validationPropsSelector,
+  /**
+   * Returns the amount of months to navigate by when pressing `<Calendar.IncrementMonth>` or `<Calendar.DecrementMonth>`.
+   */
+  monthPageSize: createSelector(state => state.monthPageSize),
+  /**
+   * Returns the date currently visible.
+   */
+  visibleDate: visibleDateSelector,
+  /**
+   * Returns the current visible month.
+   */
+  visibleMonth: visibleMonthSelector,
+  /**
+   * Returns the navigation direction.
+   */
+  navigationDirection: createSelector(state => state.navigationDirection),
+  /**
+   * Returns the current value with the timezone to render applied.
+   */
+  valueWithTimezoneToRender: valueWithTimezoneToRenderSelector,
+  /**
+   * Returns the reference date.
+   */
+  referenceDate: referenceDateSelector,
+  /**
+   * Returns the list of currently selected dates.
+   * When used inside the Calendar component, it contains the current value if not null.
+   * When used inside the RangeCalendar component, it contains the selected start and/or end dates if not null.
+   */
+  selectedDates: selectedDatesSelector,
+  /**
+   * Checks if a day cell should be disabled.
+   */
+  isDayCellDisabled: isDayCellDisabledSelector,
+  /**
+   * Checks if a day cell should be selected.
+   */
+  isDayButtonSelected: isDayButtonSelectedSelector,
+  /**
+   * Checks if a specific dates is unavailable.
+   * If so, this date should not be selectable but should still be focusable with the keyboard.
+   */
+  isDayCellUnavailable: isDayCellUnavailableSelector,
+  /**
+   * Checks if a month navigation button should be disabled.
+   */
+  isSetMonthButtonDisabled: isSetMonthButtonDisabledSelector,
+  /**
+   * Checks if a day should be reachable using tab navigation.
+   */
+  isDayButtonTabbable: isDayButtonTabbableSelector
+};

package/esm/calendar/use-context/CalendarContext.d.ts

@@ -0,0 +1,6 @@
+import { useSharedCalendarRootContext } from "../root/SharedCalendarRootContext.js";
+import { selectors } from "../store/index.js";
+export type CalendarContext = ReturnType<typeof selectors.publicContext> & {
+  setVisibleDate: ReturnType<typeof useSharedCalendarRootContext>['setVisibleDate'];
+};
+export declare function useCalendarContext(): CalendarContext;

package/esm/calendar/use-context/CalendarContext.js

@@ -0,0 +1,14 @@
+'use client';
+
+import * as React from 'react';
+import { useStore } from '@base-ui/utils/store';
+import { useSharedCalendarRootContext } from "../root/SharedCalendarRootContext.js";
+import { selectors } from "../store/index.js";
+export function useCalendarContext() {
+  const store = useSharedCalendarRootContext();
+  const calendarPublicContext = useStore(store, selectors.publicContext);
+  return React.useMemo(() => ({
+    ...calendarPublicContext,
+    setVisibleDate: store.setVisibleDate
+  }), [calendarPublicContext, store.setVisibleDate]);
+}

package/esm/calendar/use-day-list/getDayList.d.ts

@@ -0,0 +1,9 @@
+import { TemporalAdapter, TemporalSupportedObject } from "../../types/temporal/index.js";
+/**
+ * Computes a list of consecutive days starting from the given date.
+ * This is a pure function — no React hooks required.
+ */
+export declare function getDayList(adapter: TemporalAdapter, params: {
+  date: TemporalSupportedObject;
+  amount: number;
+}): TemporalSupportedObject[];

package/esm/calendar/use-day-list/getDayList.js

@@ -0,0 +1,34 @@
+/**
+ * Computes a list of consecutive days starting from the given date.
+ * This is a pure function — no React hooks required.
+ */
+export function getDayList(adapter, params) {
+  const {
+    date,
+    amount
+  } = params;
+  if (process.env.NODE_ENV !== 'production') {
+    if (amount <= 0) {
+      throw new Error(`getDayList: The 'amount' parameter must be a positive number, but received ${amount}.`);
+    }
+  }
+  const start = adapter.startOfDay(date);
+  const end = adapter.endOfDay(adapter.addDays(start, amount - 1));
+  let current = start;
+  let currentDayNumber = adapter.getDayOfWeek(current);
+  const days = [];
+  while (adapter.isBefore(current, end)) {
+    days.push(current);
+    const prevDayNumber = currentDayNumber;
+    current = adapter.addDays(current, 1);
+    currentDayNumber = adapter.getDayOfWeek(current);
+
+    // If there is a TZ change at midnight, adding 1 day may only increase the date by 23 hours to 11pm
+    // To fix, bump the date into the next day (add 12 hours) and then revert to the start of the day
+    // See https://github.com/moment/moment/issues/4743#issuecomment-811306874 for context.
+    if (prevDayNumber === currentDayNumber) {
+      current = adapter.startOfDay(adapter.addHours(current, 12));
+    }
+  }
+  return days;
+}

package/esm/calendar/use-day-list/useCalendarDayList.d.ts

@@ -0,0 +1,12 @@
+import { TemporalSupportedObject } from "../../types/temporal/index.js";
+export declare function useCalendarDayList(): UseCalendarDayListReturnValue;
+export type UseCalendarDayListReturnValue = (parameters: {
+  /**
+   * The date to get the weeks in month for.
+   */
+  date: TemporalSupportedObject;
+  /**
+   * The amount of days to return.
+   */
+  amount: number;
+}) => TemporalSupportedObject[];

package/esm/calendar/use-day-list/useCalendarDayList.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { useTemporalAdapter } from "../../temporal-adapter-provider/TemporalAdapterContext.js";
+import { getDayList } from "./getDayList.js";
+export function useCalendarDayList() {
+  const adapter = useTemporalAdapter();
+  return React.useCallback(params => getDayList(adapter, params), [adapter]);
+}

package/esm/calendar/use-week-list/getWeekList.d.ts

@@ -0,0 +1,9 @@
+import { TemporalSupportedObject, TemporalAdapter } from "../../types/temporal/index.js";
+/**
+ * Computes a list of week-start dates for the given month/date.
+ * This is a pure function — no React hooks required.
+ */
+export declare function getWeekList(adapter: TemporalAdapter, params: {
+  date: TemporalSupportedObject;
+  amount: number | 'end-of-month';
+}): TemporalSupportedObject[];

package/esm/calendar/use-week-list/getWeekList.js

@@ -0,0 +1,34 @@
+/**
+ * Computes a list of week-start dates for the given month/date.
+ * This is a pure function — no React hooks required.
+ */
+export function getWeekList(adapter, params) {
+  const {
+    date,
+    amount
+  } = params;
+  if (process.env.NODE_ENV !== 'production') {
+    if (typeof amount === 'number' && amount <= 0) {
+      throw new Error(`getWeekList: The 'amount' parameter must be a positive number, but received ${amount}.`);
+    }
+  }
+  const start = adapter.startOfWeek(date);
+  const end = amount === 'end-of-month' ? adapter.endOfWeek(adapter.endOfMonth(date)) : adapter.endOfWeek(adapter.addWeeks(start, amount - 1));
+  let current = start;
+  let currentWeekNumber = adapter.getWeekNumber(current);
+  const weeks = [];
+  while (adapter.isBefore(current, end)) {
+    weeks.push(current);
+    const prevWeekNumber = currentWeekNumber;
+    current = adapter.addWeeks(current, 1);
+    currentWeekNumber = adapter.getWeekNumber(current);
+
+    // If there is a TZ change at midnight, adding 1 week may only increase the date by 6 days and 23 hours to 11pm
+    // To fix, bump the date into the next day (add 12 hours) and then revert to the start of the day
+    // See https://github.com/moment/moment/issues/4743#issuecomment-811306874 for context.
+    if (prevWeekNumber === currentWeekNumber) {
+      current = adapter.startOfDay(adapter.addHours(current, 12));
+    }
+  }
+  return weeks;
+}

package/esm/calendar/use-week-list/useCalendarWeekList.d.ts

@@ -0,0 +1,17 @@
+import { TemporalSupportedObject } from "../../types/temporal/temporal.js";
+export declare function useCalendarWeekList(): UseWeekListReturnValue;
+export type UseWeekListReturnValue = (parameters: UseWeekListReturnValueParameters) => TemporalSupportedObject[];
+interface UseWeekListReturnValueParameters {
+  /**
+   * The date to get the weeks in month for.
+   */
+  date: TemporalSupportedObject;
+  /**
+   * The amount of weeks to return.
+   * When equal to "end-of-month", the method will return all the weeks until the end of the month.
+   * When equal to a number, the method will return that many weeks.
+   * Set it to 6 to create a Gregorian calendar where all months have the same number of weeks.
+   */
+  amount: number | 'end-of-month';
+}
+export {};

package/esm/calendar/use-week-list/useCalendarWeekList.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import { useTemporalAdapter } from "../../temporal-adapter-provider/TemporalAdapterContext.js";
+import { getWeekList } from "./getWeekList.js";
+export function useCalendarWeekList() {
+  const adapter = useTemporalAdapter();
+  return React.useCallback(params => getWeekList(adapter, params), [adapter]);
+}

package/esm/calendar/utils/computeMonthDayGrid.d.ts

@@ -0,0 +1,6 @@
+import { TemporalSupportedObject, TemporalAdapter } from "../../types/temporal/index.js";
+/**
+ * Computes a flat, chronologically ordered array of all days in a month's grid.
+ * Composes `getWeekList` and `getDayList` to produce the same result as the rendered grid.
+ */
+export declare function computeMonthDayGrid(adapter: TemporalAdapter, month: TemporalSupportedObject, fixedWeekNumber?: number, weeks?: TemporalSupportedObject[]): TemporalSupportedObject[];

package/esm/calendar/utils/computeMonthDayGrid.js

@@ -0,0 +1,17 @@
+import { getDayList } from "../use-day-list/getDayList.js";
+import { getWeekList } from "../use-week-list/getWeekList.js";
+
+/**
+ * Computes a flat, chronologically ordered array of all days in a month's grid.
+ * Composes `getWeekList` and `getDayList` to produce the same result as the rendered grid.
+ */
+export function computeMonthDayGrid(adapter, month, fixedWeekNumber, weeks) {
+  const weeksList = weeks ?? getWeekList(adapter, {
+    date: month,
+    amount: fixedWeekNumber ?? 'end-of-month'
+  });
+  return weeksList.flatMap(week => getDayList(adapter, {
+    date: week,
+    amount: 7
+  }));
+}

package/esm/calendar/utils/useCalendarMonthButton.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { SharedCalendarStore } from "../store/SharedCalendarStore.js";
+import type { TemporalSupportedValue, TemporalAdapter } from "../../types/temporal/index.js";
+interface UseCalendarMonthButtonParameters {
+  direction: 1 | -1;
+  disabled: boolean;
+  disabledProp?: boolean | undefined;
+  store: SharedCalendarStore<TemporalSupportedValue, unknown>;
+  adapter: TemporalAdapter;
+  monthPageSize: number;
+}
+/**
+ * Adds press-and-hold behavior to Calendar month navigation buttons.
+ * On pointer down, performs one navigation immediately, then after a delay
+ * starts continuous navigation at a fixed interval.
+ */
+export declare function useCalendarMonthButton(params: UseCalendarMonthButtonParameters): {
+  pointerHandlers: {
+    onTouchStart: React.TouchEventHandler<HTMLElement>;
+    onTouchEnd: React.TouchEventHandler<HTMLElement>;
+    onPointerDown: React.PointerEventHandler<HTMLElement>;
+    onPointerUp: React.PointerEventHandler<HTMLElement>;
+    onPointerMove: React.PointerEventHandler<HTMLElement>;
+    onMouseEnter: React.MouseEventHandler<HTMLElement>;
+    onMouseLeave: React.MouseEventHandler<HTMLElement>;
+    onMouseUp: React.MouseEventHandler<HTMLElement>;
+  };
+  autoChangeButtonRef: React.RefObject<HTMLElement | null>;
+  shouldSkipClick: (event: React.MouseEvent) => boolean;
+};
+export {};

package/esm/calendar/utils/useCalendarMonthButton.js

@@ -0,0 +1,47 @@
+'use client';
+
+import * as React from 'react';
+import { usePressAndHold } from "../../utils/usePressAndHold.js";
+import { REASONS } from "../../utils/reasons.js";
+import { selectors } from "../store/index.js";
+const CHANGE_MONTH_TICK_DELAY = 100;
+/**
+ * Adds press-and-hold behavior to Calendar month navigation buttons.
+ * On pointer down, performs one navigation immediately, then after a delay
+ * starts continuous navigation at a fixed interval.
+ */
+export function useCalendarMonthButton(params) {
+  const {
+    direction,
+    disabled,
+    disabledProp,
+    store,
+    adapter,
+    monthPageSize
+  } = params;
+  const autoChangeButtonRef = React.useRef(null);
+  const {
+    pointerHandlers,
+    shouldSkipClick
+  } = usePressAndHold({
+    disabled,
+    elementRef: autoChangeButtonRef,
+    tickDelay: CHANGE_MONTH_TICK_DELAY,
+    tick(triggerNativeEvent) {
+      const button = autoChangeButtonRef.current;
+      const currentVisibleDate = selectors.visibleDate(store.state);
+      const targetDate = adapter.addMonths(currentVisibleDate, direction * monthPageSize);
+      const wouldBeDisabled = selectors.isSetMonthButtonDisabled(store.state, targetDate, disabledProp);
+      if (wouldBeDisabled) {
+        return false;
+      }
+      store.setVisibleDate(targetDate, triggerNativeEvent, button ?? undefined, REASONS.monthChange);
+      return true;
+    }
+  });
+  return {
+    pointerHandlers,
+    autoChangeButtonRef,
+    shouldSkipClick
+  };
+}

package/esm/calendar/viewport/CalendarViewport.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+import { CalendarNavigationDirection } from "../store/index.js";
+/**
+ * A viewport for displaying calendar month transitions.
+ * This component is only required if you want to animate certain part of a calendar when navigating between months.
+ * The first rendered child element has to handle a ref.
+ * Passes `data-current` to the currently visible content and `data-previous` to the previous content when animating between two.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Calendar](https://base-ui.com/react/components/calendar)
+ */
+export declare function CalendarViewport({
+  children
+}: CalendarViewport.Props): React.JSX.Element;
+export interface CalendarViewportProps {
+  /**
+   * The content to render inside the transition container.
+   */
+  children: React.JSX.Element;
+}
+export interface CalendarViewportState {
+  /**
+   * Indicates the direction of the navigation (based on the month navigating to).
+   */
+  navigationDirection: CalendarNavigationDirection;
+}
+export declare namespace CalendarViewport {
+  type Props = CalendarViewportProps;
+  type State = CalendarViewportState;
+}

package/esm/calendar/viewport/CalendarViewport.js

@@ -0,0 +1,165 @@
+'use client';
+
+import * as React from 'react';
+import { inertValue } from '@base-ui/utils/inertValue';
+import { useAnimationFrame } from '@base-ui/utils/useAnimationFrame';
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { ownerDocument } from '@base-ui/utils/owner';
+import { useStore } from '@base-ui/utils/store';
+import { useAnimationsFinished } from "../../utils/useAnimationsFinished.js";
+import { CalendarViewportDataAttributes } from "./CalendarViewportDataAttributes.js";
+import { useSharedCalendarRootContext } from "../root/SharedCalendarRootContext.js";
+import { selectors } from "../store/index.js";
+import { useTemporalAdapter } from "../../temporal-adapter-provider/TemporalAdapterContext.js";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const getNavigationDirectionAttribute = navigationDirection => {
+  switch (navigationDirection) {
+    case 'none':
+      return null;
+    default:
+      return {
+        [CalendarViewportDataAttributes.navigationDirection]: navigationDirection
+      };
+  }
+};
+const ALLOWED_TAGS = new Set(['div', 'section', 'span', 'tbody']);
+function getSafeTag(localName) {
+  return ALLOWED_TAGS.has(localName) ? localName : 'div';
+}
+function getVisibleMonthKey(adapter, visibleMonth) {
+  if (!visibleMonth) {
+    return 'empty';
+  }
+  return `${adapter.getYear(visibleMonth)}-${adapter.getMonth(visibleMonth)}`;
+}
+const DATA_ATTRIBUTES = [CalendarViewportDataAttributes.current, CalendarViewportDataAttributes.startingStyle, CalendarViewportDataAttributes.endingStyle, CalendarViewportDataAttributes.navigationDirection];
+
+/**
+ * A viewport for displaying calendar month transitions.
+ * This component is only required if you want to animate certain part of a calendar when navigating between months.
+ * The first rendered child element has to handle a ref.
+ * Passes `data-current` to the currently visible content and `data-previous` to the previous content when animating between two.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Calendar](https://base-ui.com/react/components/calendar)
+ */
+export function CalendarViewport({
+  children
+}) {
+  const store = useSharedCalendarRootContext();
+  const adapter = useTemporalAdapter();
+  const navigationDirection = useStore(store, selectors.navigationDirection);
+  const visibleMonth = useStore(store, selectors.visibleMonth);
+  // Remount the entering month on visible-month changes so interrupted transitions
+  // restart from the correct starting styles instead of reusing the previous DOM.
+  const currentContentKey = getVisibleMonthKey(adapter, visibleMonth);
+  const lastHandledVisibleMonth = React.useRef(visibleMonth);
+  const capturedNodeRef = React.useRef(null);
+  const [previousContentNode, setPreviousContentNode] = React.useState(null);
+  const currentContainerRef = React.useRef(null);
+  const previousContainerRef = React.useRef(null);
+  const onAnimationsFinished = useAnimationsFinished(currentContainerRef, true, false);
+  const cleanupTimeout = useAnimationFrame();
+  const abortControllerRef = React.useRef(null);
+  const [showStartingStyleAttribute, setShowStartingStyleAttribute] = React.useState(false);
+  useIsoLayoutEffect(() => {
+    // When the visible month changes,
+    // set the captured children HTML to state,
+    // so we can render both new and old month when transitioning.
+    if (visibleMonth && lastHandledVisibleMonth.current && !adapter.isEqual(lastHandledVisibleMonth.current, visibleMonth) && capturedNodeRef.current) {
+      // Cancel the previous transition's pending animation-finished callback
+      abortControllerRef.current?.abort();
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      setPreviousContentNode(capturedNodeRef.current);
+      setShowStartingStyleAttribute(true);
+      cleanupTimeout.request(() => {
+        setShowStartingStyleAttribute(false);
+        onAnimationsFinished(() => {
+          setPreviousContentNode(null);
+          capturedNodeRef.current = null;
+        }, abortController.signal);
+      });
+      lastHandledVisibleMonth.current = visibleMonth;
+    }
+  }, [adapter, cleanupTimeout, onAnimationsFinished, visibleMonth]);
+
+  // Capture a clone of the current content DOM subtree when not transitioning.
+  // We can't store previous React nodes as they may be stateful; instead we capture DOM clones for visual continuity.
+  useIsoLayoutEffect(() => {
+    // When a transition is in progress, we store the next content in capturedNodeRef.
+    // This handles the case where the trigger changes multiple times before the transition finishes.
+    // We want to always capture the latest content for the previous snapshot.
+    // So clicking quickly on T1, T2, T3 will result in the following sequence:
+    // 1. T1 -> T2: previousContent = T1, currentContent = T2
+    // 2. T2 -> T3: previousContent = T2, currentContent = T3
+    const source = currentContainerRef.current;
+    if (!source) {
+      return;
+    }
+
+    // Create the wrapper element of the same type as the source element.
+    // It has to be an element of the same tag, especially if it's the calendar body (`tbody`).
+    const wrapper = ownerDocument(source).createElement(getSafeTag(source.localName));
+    for (const child of Array.from(source.childNodes)) {
+      wrapper.appendChild(child.cloneNode(true));
+    }
+    capturedNodeRef.current = wrapper;
+  });
+  const currentChildren = /*#__PURE__*/React.cloneElement(children, {
+    ref: currentContainerRef,
+    key: currentContentKey
+  });
+  const isTransitioning = previousContentNode != null;
+  let childrenToRender;
+  if (!isTransitioning) {
+    childrenToRender = currentChildren;
+  } else {
+    childrenToRender = /*#__PURE__*/_jsxs(React.Fragment, {
+      children: [navigationDirection === 'previous' && currentChildren, /*#__PURE__*/React.createElement(getSafeTag(previousContentNode.localName), {
+        className: currentContainerRef?.current?.className,
+        key: 'previous',
+        ref: previousContainerRef,
+        'data-previous': '',
+        'data-starting-style': showStartingStyleAttribute ? '' : undefined,
+        'data-ending-style': showStartingStyleAttribute ? undefined : '',
+        inert: inertValue(true),
+        ...getNavigationDirectionAttribute(navigationDirection)
+      }), navigationDirection === 'next' && currentChildren]
+    });
+  }
+
+  // Avoids remounting the current month after transition ends.
+  useIsoLayoutEffect(() => {
+    if (!currentContainerRef.current) {
+      return;
+    }
+    if (isTransitioning) {
+      currentContainerRef.current.setAttribute('data-current', '');
+      if (showStartingStyleAttribute) {
+        currentContainerRef.current.setAttribute('data-starting-style', '');
+      } else {
+        currentContainerRef.current.setAttribute('data-ending-style', '');
+        currentContainerRef.current.removeAttribute('data-starting-style');
+      }
+      const navigationDirectionAttribute = getNavigationDirectionAttribute(navigationDirection);
+      if (navigationDirectionAttribute) {
+        currentContainerRef.current.setAttribute(...Object.entries(navigationDirectionAttribute)[0]);
+      }
+    } else {
+      for (const attribute of DATA_ATTRIBUTES) {
+        currentContainerRef.current.removeAttribute(attribute);
+      }
+    }
+  }, [isTransitioning, showStartingStyleAttribute, navigationDirection]);
+
+  // When previousContentNode is present, imperatively populate the previous container with the cloned children.
+  useIsoLayoutEffect(() => {
+    const container = previousContainerRef.current;
+    if (!container || !previousContentNode) {
+      return;
+    }
+    container.replaceChildren(...Array.from(previousContentNode.childNodes));
+  }, [previousContentNode]);
+  return childrenToRender;
+}