rn-grid-date-time-picker 1.0.0 → 1.2.0

package/src/components/DateTimePicker.tsx

@@ -6,20 +6,33 @@ import React, {
   useState,
 } from 'react';
 import { DateTime } from 'luxon';
+import { View } from 'react-native';
 import { resolveAdapter } from '../adapters';
-import { daysBetween, isSameDay } from '../core/calendarDate';
+import {
+  compareCalendarDates,
+  daysBetween,
+  isSameDay,
+} from '../core/calendarDate';
 import { createConstraints } from '../core/constraints';
 import {
+  clearDraft as emptied,
   createDraft,
   DEFAULT_TIME,
   draftToWire,
+  sameDayRangeOk,
   setTime as applyTime,
   validateDraft,
   type Draft,
   type DraftOptions,
   type DraftTarget,
 } from '../core/draft';
-import { resolveCalendarSystem } from '../core/calendarSystem';
+import {
+  hijriDateText,
+  hijriPeriods,
+  isHijriSupported,
+  resolveCalendarSystem,
+  type CalendarSystem,
+} from '../core/calendarSystem';
 import {
   defaultLocale,
   deriveDateFormat,
@@ -27,6 +40,7 @@ import {
   deriveTimeFormat,
   normalizeDateFormat,
 } from '../core/locale';
+import { arabicDigits, latinDigits, localeDigits } from '../core/numerals';
 import { withSelectionRules } from '../core/selectionRules';
 import type { ParsedSegments } from '../core/segments';
 import { checkTime, type TimeEntryIssue } from '../core/timeEntry';
@@ -38,13 +52,18 @@ import type {
   ValueAdapter,
 } from '../core/types';
 import Calendar from './calendar/Calendar';
+import CalendarSwitch from './calendar/CalendarSwitch';
 import { localeNames } from './calendar/localeNames';
-import type { CalendarSelection } from './calendar/selection';
+import { RtlContext } from './theme/direction';
+import { NumeralsContext } from './theme/numerals';
+import { firstSelectedDay, type CalendarSelection } from './calendar/selection';
 import PickerContainer from './container/PickerContainer';
 import {
+  formatDateText,
   formatMultipleText,
   formatRangeText,
   formatValueText,
+  type DateTextFormatter,
 } from './field/fieldText';
 import FieldMessages from './field/FieldMessages';
 import RangeFields, { type RangeEnd } from './field/RangeFields';
@@ -54,7 +73,11 @@ import { useOpenPicker } from './hooks/useOpenPicker';
 import { usePickerDraft } from './hooks/usePickerDraft';
 import { useTodayTick } from './hooks/useTodayTick';
 import TimeRows, { type PendingTimes } from './time/TimeRows';
-import { resolveStrings } from './theme/defaultStrings';
+import {
+  DEFAULT_STRINGS,
+  compactStrings,
+  resolveStrings,
+} from './theme/defaultStrings';
 import { buildTokens } from './theme/tokens';
 import {
   DEFAULT_YEAR_RANGE,
@@ -68,9 +91,29 @@ const sameValue = (a: DateTimeValue, b: DateTimeValue): boolean =>
   (a.time?.hour ?? -1) === (b.time?.hour ?? -1) &&
   (a.time?.minute ?? -1) === (b.time?.minute ?? -1);
 
+const ALL_SYSTEMS: CalendarSystem[] = ['gregory', 'hijri', 'dual'];
+const RTL = { direction: 'rtl' } as const;
+
+/** The same kind of selection with nothing in it. */
+const emptySelection = (sel: CalendarSelection): CalendarSelection =>
+  sel.kind === 'single'
+    ? { kind: 'single', day: null }
+    : sel.kind === 'range'
+      ? { kind: 'range', from: null, to: null }
+      : { ...sel, days: [] };
+
 /** Minute steps that divide the hour. */
 const MINUTE_STEPS = [1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30, 60];
 
+/** A folded calendar stays mounted, so it comes back on the month and view it showed. */
+const FOLDED = { display: 'none' } as const;
+
+/** The later / earlier of a limit and a bound; the bound when there's no limit. */
+const later = (a: CalendarDate | undefined, b: CalendarDate): CalendarDate =>
+  a && compareCalendarDates(a, b) > 0 ? a : b;
+const earlier = (a: CalendarDate | undefined, b: CalendarDate): CalendarDate =>
+  a && compareCalendarDates(a, b) < 0 ? a : b;
+
 /**
  * A date & time picker: a value field that opens a sheet (or an inline panel)
  * with a calendar and, for date-time values, a time row. Single, range and
@@ -110,6 +153,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     disabled = false,
     readOnly = false,
     allowTyping,
+    hideCalendarOnKeyboard = true,
     allowFieldTyping,
     allowClear,
     errorMessage,
@@ -141,6 +185,11 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     initialVisibleDate,
     enableMonthSwipe = true,
     calendarSystem,
+    calendarSwitch,
+    onCalendarSystemChange,
+    dualDefaultTab = 'gregory',
+    hijriLocale = 'ar-SA',
+    renderCalendarSwitch,
     showToday = false,
     showHolidays = true,
     onVisibleMonthChange,
@@ -148,6 +197,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     validate,
     yearRange: yearRangeProp = DEFAULT_YEAR_RANGE,
     locale,
+    numerals: numeralsProp,
     timeZone,
     now,
     timeFormat: timeFormatProp,
@@ -167,6 +217,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     theme,
     styles,
     strings: stringOverrides,
+    hijriStrings: hijriOverrides,
     testID,
   } = props;
 
@@ -184,6 +235,87 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   // Month and year picks are for single dates only.
   const precision =
     type === 'date' && mode === 'single' ? precisionProp : 'day';
+  // The calendars the switch offers: none for month and year picks (always
+  // Gregorian), or when the platform has no Hijri calendar.
+  const switchKey = Array.isArray(calendarSwitch)
+    ? calendarSwitch.join(',')
+    : String(!!calendarSwitch);
+  const switchSystems = useMemo((): CalendarSystem[] | null => {
+    if (!calendarSwitch || precision !== 'day' || !isHijriSupported())
+      return null;
+    const list =
+      calendarSwitch === true
+        ? ALL_SYSTEMS
+        : ALL_SYSTEMS.filter((x) => calendarSwitch.includes(x)).sort(
+            (a, b) => calendarSwitch.indexOf(a) - calendarSwitch.indexOf(b)
+          );
+    return list.length > 1 ? list : null;
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- the list is compared by content
+  }, [switchKey, precision]);
+  const startSystem = (): CalendarSystem => {
+    const wanted = calendarSystem ?? 'gregory';
+    return switchSystems && !switchSystems.includes(wanted)
+      ? (switchSystems[0] ?? wanted)
+      : wanted;
+  };
+  // The switch changes this; a new calendarSystem prop starts over from it.
+  const [chosenSystem, setChosenSystem] = useState(startSystem);
+  // The calendar the props open on, which a value from outside counts as
+  // picked in. The switch's own choice coming back as the calendarSystem prop
+  // (onCalendarSystemChange={setSystem}) isn't a new one.
+  const [openedOn, setOpenedOn] = useState(startSystem);
+  const echo = useRef<CalendarSystem | null>(null);
+  useEffect(
+    () => {
+      const next = startSystem();
+      const own = echo.current === next;
+      echo.current = null;
+      if (own) return;
+      setChosenSystem(next);
+      setOpenedOn(next);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- only when the props change
+    [calendarSystem, switchKey]
+  );
+  // Month and year picks are Gregorian whatever the calendar system.
+  const system =
+    precision === 'day' ? resolveCalendarSystem(chosenSystem) : 'gregory';
+  // A dual calendar shows one of its two tabs; each open starts on dualDefaultTab.
+  const [dualTab, setDualTab] = useState(dualDefaultTab);
+  /** The calendar on screen. */
+  const shownSystem = system === 'dual' ? dualTab : system;
+  // A value from outside counts as picked in the calendar the props open on,
+  // not the one the user has since chosen in the switch.
+  const propSystem =
+    precision === 'day' ? resolveCalendarSystem(openedOn) : 'gregory';
+  const outsideSystem = propSystem === 'dual' ? dualDefaultTab : propSystem;
+  // Picks say which calendar they were made in only when one can be Hijri.
+  const hijriInPlay = switchSystems !== null || system !== 'gregory';
+  /**
+   * The digits for one calendar: a Hijri calendar (and a date picked in it)
+   * shows Arabic digits (١٢٣) in any language; a Gregorian one shows 0–9.
+   * `numerals` sets both.
+   */
+  const digitsFor = (sys: 'gregory' | 'hijri') => {
+    const kind = numeralsProp ?? (sys === 'hijri' ? 'arabic' : 'latin');
+    if (kind === 'arabic') return arabicDigits;
+    if (kind === 'latin') return latinDigits;
+    return localeDigits(sys === 'hijri' ? hijriLocale : loc);
+  };
+  /**
+   * The strings for one calendar. A Hijri one takes `hijriStrings` first, then
+   * AM / PM in `hijriLocale` (ص / م), then `strings`.
+   */
+  const hijriStrings = useMemo(
+    () => ({
+      ...strings,
+      ...hijriPeriods(hijriLocale),
+      ...compactStrings(hijriOverrides),
+    }),
+    [strings, hijriLocale, hijriOverrides]
+  );
+  const stringsFor = (sys: 'gregory' | 'hijri') =>
+    sys === 'hijri' ? hijriStrings : strings;
   const monthNames = useMemo(() => localeNames(loc).monthsLong, [loc]);
   /** A month or year pick shown as text: "March 2026" or "2026". */
   const periodText = (v: DateTimeValue | null): string => {
@@ -272,7 +404,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   const {
     isOpen: sheetOpen,
     open,
-    close,
+    close: closePicker,
   } = useOpenPicker({
     disabled,
     readOnly,
@@ -282,7 +414,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     onClose,
   });
   const isOpen = isInline || sheetOpen;
-  const keyboardUp = useKeyboardFold(isOpen);
+  const keyboardUp = useKeyboardFold(isOpen && hideCalendarOnKeyboard);
   // The picker's own boxes that have focus. Inline, another field on the
   // screen can raise the keyboard, so the calendar folds only for these.
   const [focusedParts, setFocusedParts] = useState<Record<string, boolean>>({});
@@ -349,6 +481,17 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     },
     [loadHolidays]
   );
+  // A month's grid also shows days of the months either side, and a Hijri
+  // month can run from December into January, so a month at either end of a
+  // year loads the year next to it too.
+  const loadHolidaysAround = useCallback(
+    (year: number, month: number) => {
+      loadHolidaysFor(year);
+      if (month >= 11 && year < yearRange.last) loadHolidaysFor(year + 1);
+      if (month === 1 && year > yearRange.first) loadHolidaysFor(year - 1);
+    },
+    [loadHolidaysFor, yearRange.first, yearRange.last]
+  );
   const holidays = useMemo(
     () => [...(holidaysProp ?? []), ...Object.values(loadedHolidays).flat()],
     [holidaysProp, loadedHolidays]
@@ -357,11 +500,15 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   // Limits are worked out when the picker opens (the screen's own validation
   // after Confirm stays the final check).
   const weekdaysKey = disabledWeekdays?.join(',');
+  // Limits built with `dependsOnNow` ("from now on") are rebuilt every minute
+  // while the picker is open.
+  const [minuteTick, setMinuteTick] = useState(0);
   const constraints = useMemo(() => {
     const nowDate = now?.() ?? new Date();
+    // yearRange bounds the limits too, so days outside it are greyed.
     const limits = {
-      minDate,
-      maxDate,
+      minDate: later(minDate, { year: yearRange.first, month: 1, day: 1 }),
+      maxDate: earlier(maxDate, { year: yearRange.last, month: 12, day: 31 }),
       disabledDates,
       enabledDates,
       timeBounds,
@@ -383,8 +530,8 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
           type,
           timeZone: zone,
           now: nowDate,
-          minDate,
-          maxDate,
+          minDate: limits.minDate,
+          maxDate: limits.maxDate,
           isDisabled: disabledDates,
           isEnabled: enabledDates,
           timeBounds,
@@ -392,10 +539,11 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
           holidays,
           disableHolidays,
         });
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- `isOpen` and `today` refresh the limits on open and at midnight; weekdays are compared by content
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- `isOpen`, `today` and `minuteTick` refresh the limits on open, at midnight and each minute; weekdays are compared by content
   }, [
     isOpen,
     today,
+    minuteTick,
     type,
     zone,
     now,
@@ -408,8 +556,27 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     weekdaysKey,
     disableHolidays,
     getConstraints,
+    yearRange,
   ]);
 
+  const followsClock = isOpen && constraints.dependsOnNow;
+  useEffect(() => {
+    if (!followsClock) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const arm = () => {
+      const ms = 60_000 - ((now?.() ?? new Date()).getTime() % 60_000);
+      timer = setTimeout(() => {
+        setMinuteTick((n) => n + 1);
+        arm();
+      }, ms);
+      // Under Node (e.g. Jest) the timer must not keep the process alive.
+      (timer as { unref?: () => void }).unref?.();
+    };
+    arm();
+    return () => clearTimeout(timer);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- armed while open with a clock-bound limit
+  }, [followsClock]);
+
   // A typed field that doesn't parse blocks Confirm, per field: one end of a
   // range can't hide the other end's problem.
   const [typingBlocks, setTypingBlocks] = useState<
@@ -444,14 +611,30 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   const [wheelSpinning, setWheelSpinning] = useState(false);
   // From/To layout: the end that calendar taps fill. perDate: the day the time row edits.
   const [activeEnd, setActiveEnd] = useState<RangeEnd>('from');
+  // From/To layout: a From or To field was tapped, so the next day tap edits that end only.
+  const [endPicked, setEndPicked] = useState(false);
+  const activateEnd = useCallback((end: RangeEnd) => {
+    setActiveEnd(end);
+    setEndPicked(true);
+  }, []);
   const [activeDay, setActiveDay] = useState<CalendarDate | null>(null);
   const resetSelectionUi = useCallback(() => {
+    // What was typed is gone with the selection, so nothing blocks Confirm.
+    setTypingBlocks({});
     setPendingTimes({});
     setActiveEnd('from');
+    setEndPicked(false);
     setActiveDay(null);
   }, []);
+  // A day in the month the calendar last showed, so a switch to the other
+  // calendar opens on the same days. Each open starts from the value again.
+  const shownAnchor = useRef<CalendarDate | null>(null);
+  const rememberAnchor = useCallback((day: CalendarDate) => {
+    shownAnchor.current = day;
+  }, []);
   // Opening or closing starts fresh: nothing edited, nothing blocked.
   useEffect(() => {
+    shownAnchor.current = null;
     edited.current = false;
     setTypingBlocks({});
     setTimeCheck(0);
@@ -529,6 +712,63 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   latest.current = { validate, onError, value };
   const valueKey = JSON.stringify(value ?? '');
 
+  // A selection belongs to the calendar it was picked in (Gregorian or Hijri):
+  // it shows only there, and the field writes it in that calendar. A saved
+  // value remembers its calendar; one from outside counts as picked in the
+  // calendar the picker opens on.
+  // The saved value as a draft, for the on-screen field and for comparing
+  // values by what they hold.
+  const saved = useMemo(
+    () => createDraft(mode, value, draftOptions),
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- the value is compared by content (`valueKey`)
+    [valueKey, mode, draftOptions]
+  );
+  /** A draft's days and times, so a value written another way ({to, from}) still matches. */
+  const contentOf = (dr: Draft): string => JSON.stringify(valuesOf(dr));
+  const savedContent = contentOf(saved);
+  const savedSystemRef = useRef<{
+    content: string;
+    system: 'gregory' | 'hijri';
+  } | null>(null);
+  const savedSystem =
+    savedSystemRef.current?.content === savedContent
+      ? savedSystemRef.current.system
+      : outsideSystem;
+  const [draftSystem, setDraftSystem] = useState(savedSystem);
+  // The draft is rebuilt on open and on a new value; so is its calendar. A new
+  // calendarSystem prop while the user is picking starts the selection over,
+  // since a selection is one calendar's.
+  const systemSeen = useRef({ isOpen, valueKey, savedSystem });
+  useEffect(() => {
+    const seen = systemSeen.current;
+    systemSeen.current = { isOpen, valueKey, savedSystem };
+    setDraftSystem(savedSystem);
+    const systemOnly =
+      seen.isOpen === isOpen &&
+      seen.valueKey === valueKey &&
+      seen.savedSystem !== savedSystem;
+    if (systemOnly && isOpen && edited.current) {
+      draft.clear();
+      resetSelectionUi();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- the draft's actions are stable
+  }, [isOpen, valueKey, savedSystem]);
+  useEffect(() => setDualTab(dualDefaultTab), [isOpen, dualDefaultTab]);
+  const selectionShown = draftSystem === shownSystem;
+  /** Saves a value: with the calendar it was picked in, when one can be Hijri. */
+  const emitChange = useCallback(
+    (wire: PickerValue, picked: 'gregory' | 'hijri') => {
+      savedSystemRef.current = {
+        content: contentOf(createDraft(mode, wire, draftOptions)),
+        system: picked,
+      };
+      if (hijriInPlay) onChange(wire, { calendarSystem: picked });
+      else onChange(wire);
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- contentOf reads only `type` and the options listed
+    [hijriInPlay, onChange, mode, draftOptions]
+  );
+
   /**
    * Whether a draft can be saved as it stands: complete, every day allowed,
    * every time allowed and on the minute step, and nothing being typed or
@@ -555,18 +795,18 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   // Every save: Confirm, an 'instant' edit (onConfirm is added by `confirm`).
   const commit = useCallback(
     (wire: PickerValue) => {
-      onChange(wire);
+      emitChange(wire, draftSystem);
       onBlur?.();
     },
-    [onChange, onBlur]
+    [emitChange, draftSystem, onBlur]
   );
 
   const confirm = useCallback(() => {
     if (!canConfirm) return;
-    const { validate: check, onError: report, value: saved } = latest.current;
+    const { validate: check, onError: report, value: current } = latest.current;
     if (timeBlocked) {
       setTimeCheck((n) => n + 1);
-      report?.(timeIssue ?? 'TIME_NOT_ALLOWED', saved);
+      report?.(timeIssue ?? 'TIME_NOT_ALLOWED', current);
       return;
     }
     const wire = draftToWire(preview, draftOptions);
@@ -579,7 +819,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     commit(wire);
     onConfirm?.(wire);
     edited.current = false;
-    if (!isInline) close();
+    if (!isInline) closePicker();
   }, [
     canConfirm,
     timeBlocked,
@@ -589,15 +829,15 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     preview,
     draftOptions,
     isInline,
-    close,
+    closePicker,
   ]);
 
   const clearValue = useCallback(() => {
     draft.clear();
     resetSelectionUi();
     edited.current = false;
-    onChange('');
-  }, [draft, onChange, resetSelectionUi]);
+    emitChange('', draftSystem);
+  }, [draft, emitChange, draftSystem, resetSelectionUi]);
 
   const clearDraft = useCallback(() => {
     edited.current = true;
@@ -607,10 +847,11 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
 
   // × in the field above the calendar. 'instant' saves every edit, so it
   // clears the saved value too (once; an empty value isn't saved again).
+  const hasSaved = valuesOf(saved).some((v) => v !== null);
   const clearInSheet = useCallback(() => {
-    if (commitMode === 'instant' && valueKey !== '""') clearValue();
+    if (commitMode === 'instant' && hasSaved) clearValue();
     else clearDraft();
-  }, [commitMode, valueKey, clearValue, clearDraft]);
+  }, [commitMode, hasSaved, clearValue, clearDraft]);
 
   // Opening or closing starts without the last `validate` message.
   useEffect(() => setValidation(null), [isOpen]);
@@ -621,15 +862,32 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   // An edit equal to the saved value isn't saved again; one `validate`
   // rejected waits until the selection or the saved value changes.
   const lastRejected = useRef<string | null>(null);
+  // The last value saved: not saved again while the parent's `value` catches
+  // up (a slow store, a server round trip) or when it never does.
+  const lastEmitted = useRef<string | null>(null);
   useEffect(() => {
     lastRejected.current = null;
-  }, [valueKey]);
-  useEffect(() => {
+    lastEmitted.current = null;
+  }, [valueKey, isOpen]);
+  // The field in the sheet saves once typing there is done (focus leaves it),
+  // so 09:30 isn't saved as 09:00 and 09:03 on the way.
+  const sheetTyping = !!(
+    focusedParts.value ||
+    focusedParts['value-from'] ||
+    focusedParts['value-to']
+  );
+  /** Saves the draft in instant mode; `typingDone` once the sheet's field is left. */
+  const saveInstant = (typingDone: boolean) => {
     if (commitMode !== 'instant' || !isOpen || !edited.current) return;
-    if (timeIssue || !canSave(draft.draft)) return;
+    if (!typingDone || timeIssue || !canSave(draft.draft)) return;
     const wire = draft.toWire();
     const key = JSON.stringify(wire);
-    if (key === valueKey || key === lastRejected.current) return;
+    if (key === lastRejected.current || key === lastEmitted.current) return;
+    // The same dates picked in the same calendar aren't saved again; the same
+    // dates picked in the other calendar are.
+    const unchanged =
+      key === valueKey || contentOf(draft.draft) === savedContent;
+    if (unchanged && draftSystem === savedSystem) return;
     const message = latest.current.validate?.(wire);
     if (message) {
       lastRejected.current = key;
@@ -637,18 +895,35 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       latest.current.onError?.('VALIDATION', wire);
       return;
     }
+    lastEmitted.current = key;
     commit(wire);
+  };
+  // Only typing waits for the field to be left; a tap is a finished edit.
+  const typedLast = useRef(false);
+  useEffect(
+    () => saveInstant(!sheetTyping || !typedLast.current),
     // eslint-disable-next-line react-hooks/exhaustive-deps -- when the draft or what blocks it changes, not when callbacks are re-created
-  }, [
-    commitMode,
-    isOpen,
-    draft.draft,
-    timeIssue,
-    typingBlocked,
-    wheelSpinning,
-    confirmDisabled,
-    constraints,
-  ]);
+    [
+      commitMode,
+      isOpen,
+      sheetTyping,
+      draft.draft,
+      draftSystem,
+      timeIssue,
+      typingBlocked,
+      wheelSpinning,
+      confirmDisabled,
+      constraints,
+    ]
+  );
+  // Closing while the sheet's field still has focus ends the typing: an
+  // instant picker saves what was typed before it closes.
+  const saveInstantRef = useRef(saveInstant);
+  saveInstantRef.current = saveInstant;
+  const close = useCallback(() => {
+    saveInstantRef.current(true);
+    closePicker();
+  }, [closePicker]);
 
   // A typed date with no time yet gets one the way a tapped day does: the fixed
   // newDayTime, else a time already typed in the time row, else now.
@@ -664,8 +939,16 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
         }
       : null);
 
+  // Typed segments are Gregorian, so typing keeps the calendar a selection was
+  // picked in; into an empty draft, it takes the calendar on screen.
+  const adoptShownIfEmpty = () => {
+    if (valuesOf(d).every((v) => v === null)) setDraftSystem(shownSystem);
+  };
+
   const onSheetTyped = (parsed: ParsedSegments) => {
     edited.current = true;
+    typedLast.current = true;
+    adoptShownIfEmpty();
     const typed = withFilledTime(parsed, 'single');
     setTypingBlock('single', !parsed.isEmpty && !typed);
     if (typed) draft.setValue(typed, 'single');
@@ -674,6 +957,8 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
 
   const onRangeTyped = (end: RangeEnd, parsed: ParsedSegments) => {
     edited.current = true;
+    typedLast.current = true;
+    adoptShownIfEmpty();
     const typed = withFilledTime(parsed, end);
     setTypingBlock(end, !parsed.isEmpty && !typed);
     if (typed || parsed.isEmpty) draft.setValue(typed, end);
@@ -692,35 +977,111 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     return { hour: Math.floor(capped / 60), minute: capped % 60 };
   }, [now, zone, minuteStep]);
 
+  // A range end picked on the start's day starts an hour after the start (at
+  // most the day's latest allowed time, or its last step), so the range isn't
+  // out of order before the user has touched the time.
+  // A time typed for the end before its day is kept as typed.
+  const endTimeFor = (
+    from: DateTimeValue | null,
+    day: CalendarDate,
+    typed: Time | null | undefined
+  ): Time => {
+    if (!fixedTime && typed) return typed;
+    const time = fixedTime ?? nowTime();
+    if (!from?.time || !isSameDay(from.date, day)) return time;
+    const start = from.time.hour * 60 + from.time.minute;
+    if (time.hour * 60 + time.minute > start) return time;
+    // Within the day's allowed hours when it has them.
+    const max = constraints.timeBounds(day)?.max;
+    const last = max
+      ? max.hour * 60 + max.minute
+      : 24 * 60 - Math.max(1, minuteStep);
+    const end = Math.min(start + 60, last);
+    return { hour: Math.floor(end / 60), minute: end % 60 };
+  };
+
   const onSelectDay = useCallback(
     (day: CalendarDate) => {
       edited.current = true;
-      if (d.mode === 'range') {
+      typedLast.current = false;
+      // A pick in the other calendar starts over: the selection is one calendar's.
+      const fresh =
+        draftSystem !== shownSystem && valuesOf(d).some((v) => v !== null);
+      setDraftSystem(shownSystem);
+      const cur = fresh ? emptied(d) : d;
+      const end0: RangeEnd = fresh ? 'from' : activeEnd;
+      const dayInEdit = fresh ? null : activeDay;
+      const times: PendingTimes = fresh ? {} : pending;
+      if (fresh) {
+        draft.clear();
+        resetSelectionUi();
+      }
+      if (cur.mode === 'range') {
         if (rangeLayout === 'fromTo') {
+          setEndPicked(false);
+          // A full range: the tap starts a new one (or moves the nearest end).
+          if (!endPicked && cur.from.value && cur.to.value) {
+            const moveNearest = range?.reselect === 'moveNearestEnd';
+            const nearest: RangeEnd =
+              Math.abs(daysBetween(cur.from.value.date, day)) <
+              Math.abs(daysBetween(cur.to.value.date, day))
+                ? 'from'
+                : 'to';
+            const end = moveNearest ? nearest : 'from';
+            setTypingBlock('from', false);
+            setTypingBlock('to', false);
+            draft.selectDay(day, fixedTime ?? times[end] ?? nowTime());
+            setActiveEnd(moveNearest ? nearest : 'to');
+            return;
+          }
+          // Choosing the end after a start tap: a day before the start moves the start.
+          const end1: RangeEnd =
+            end0 === 'to' &&
+            !endPicked &&
+            cur.from.value &&
+            compareCalendarDates(day, cur.from.value.date) < 0
+              ? 'from'
+              : end0;
           // The tapped day replaces whatever was typed in this end only.
-          setTypingBlock(activeEnd, false);
+          setTypingBlock(end1, false);
           draft.setRangeEnd(
             day,
-            activeEnd,
-            fixedTime ?? pending[activeEnd] ?? nowTime()
+            end1,
+            end1 === 'to'
+              ? endTimeFor(cur.from.value, day, times.to)
+              : (fixedTime ?? times.from ?? nowTime())
           );
-          if (activeEnd === 'from') setActiveEnd('to');
+          // The start tapped again where a range can't be one day deselects
+          // it, so the next tap picks the start again.
+          const deselects =
+            end1 === 'to' &&
+            !sameDayRangeOk(draftOptions) &&
+            isSameDay(cur.from.value?.date, day);
+          if (end0 === 'from') setActiveEnd('to');
+          else if (deselects) setActiveEnd('from');
           return;
         }
         // The single field: the first tap is the start, the next one the end.
         const startsOver =
-          !d.from.value ||
-          (!!d.to.value && range?.reselect !== 'moveNearestEnd');
+          !cur.from.value ||
+          (!!cur.to.value && range?.reselect !== 'moveNearestEnd');
         const end: RangeEnd = startsOver ? 'from' : 'to';
         setTypingBlock('single', false);
-        draft.selectDay(day, fixedTime ?? pending[end] ?? nowTime());
+        draft.selectDay(
+          day,
+          end === 'to' && !cur.to.value
+            ? endTimeFor(cur.from.value, day, times.to)
+            : (fixedTime ?? times[end] ?? nowTime())
+        );
         return;
       }
-      if (d.mode === 'multiple') {
+      if (cur.mode === 'multiple') {
         const perDate = type === 'datetime' && multipleTimeMode === 'perDate';
-        const picked = d.slots.some((slot) => isSameDay(slot.value?.date, day));
+        const picked = cur.slots.some((slot) =>
+          isSameDay(slot.value?.date, day)
+        );
         // perDate: a tap on a picked day first makes it the one the time row edits.
-        if (perDate && picked && !isSameDay(activeDay, day)) {
+        if (perDate && picked && !isSameDay(dayInEdit, day)) {
           setActiveDay(day);
           return;
         }
@@ -729,8 +1090,9 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
         return;
       }
       setTypingBlock('single', false);
-      draft.selectDay(day, fixedTime ?? pending.single ?? nowTime());
+      draft.selectDay(day, fixedTime ?? times.single ?? nowTime());
     },
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- valuesOf reads only `d` and props listed here
     [
       d,
       draft,
@@ -744,21 +1106,39 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       type,
       multipleTimeMode,
       setTypingBlock,
+      draftSystem,
+      shownSystem,
+      resetSelectionUi,
+      endPicked,
+      draftOptions,
+      minuteStep,
+      constraints,
     ]
   );
 
+  // The calendar gets a tap handler that never changes, so its memoized day
+  // cells don't all redraw on every tap; it calls the current one.
+  const selectDayRef = useRef(onSelectDay);
+  selectDayRef.current = onSelectDay;
+  const onSelectDayStable = useCallback(
+    (day: CalendarDate) => selectDayRef.current(day),
+    []
+  );
+
   // Greying that depends on what's picked: range length, From/To order, the multiple cap.
   const calendarConstraints = useMemo(() => {
     if (d.mode === 'range') {
+      // A full From/To range greys nothing: the next tap starts a new one.
       const choosingEnd =
         rangeLayout === 'fromTo'
-          ? activeEnd === 'to'
+          ? activeEnd === 'to' && (endPicked || !d.to.value)
           : !!d.from.value && !d.to.value;
       return withSelectionRules(constraints, {
         rangeStart: choosingEnd ? d.from.value?.date : null,
         minDays: range?.minDays,
         maxDays: range?.maxDays,
-        blockBeforeStart: rangeLayout === 'fromTo',
+        // Only an end chosen from the To field can't go before the start.
+        blockBeforeStart: rangeLayout === 'fromTo' && endPicked,
       });
     }
     if (d.mode === 'multiple') {
@@ -775,6 +1155,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     d,
     rangeLayout,
     activeEnd,
+    endPicked,
     range?.minDays,
     range?.maxDays,
     multiple?.maxSelections,
@@ -812,15 +1193,16 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
 
   const handleVisibleMonth = useCallback(
     (year: number, month: number) => {
-      loadHolidaysFor(year);
+      loadHolidaysAround(year, month);
       onVisibleMonthChange?.(year, month);
     },
-    [loadHolidaysFor, onVisibleMonthChange]
+    [loadHolidaysAround, onVisibleMonthChange]
   );
   useEffect(() => {
     if (!isOpen) return;
-    const anchor = selection.kind === 'single' ? selection.day : null;
-    loadHolidaysFor((anchor ?? today).year);
+    const anchor =
+      (selection.kind === 'single' ? selection.day : null) ?? today;
+    loadHolidaysAround(anchor.year, anchor.month);
     // eslint-disable-next-line react-hooks/exhaustive-deps -- once per open
   }, [isOpen]);
 
@@ -874,17 +1256,28 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       return;
     }
     setTriggerError('');
-    onChange(wire);
+    // Typing keeps the calendar the saved value was picked in.
+    emitChange(wire, savedSystem);
     onBlur?.();
   };
 
+  /** A value's date in the calendar it was picked in: Hijri text, or none for the dateFormat. */
+  const dateTextFor = (
+    picked: 'gregory' | 'hijri'
+  ): DateTextFormatter | undefined =>
+    picked === 'hijri'
+      ? (v) =>
+          hijriDateText(v.date, hijriLocale) ?? formatDateText(v, dateFormat)
+      : undefined;
+  const savedDateText = dateTextFor(savedSystem);
+  const draftDateText = dateTextFor(draftSystem);
+  const savedStrings = stringsFor(savedSystem);
+  const draftStrings = stringsFor(draftSystem);
+  // Error messages inside the picker follow the tab on screen; the on-screen
+  // field's keep `strings`.
+  const shownStrings = stringsFor(shownSystem);
+
   // What the on-screen field shows: the saved value, never the draft.
-  const savedKey = valueKey;
-  const saved = useMemo(
-    () => createDraft(mode, value, draftOptions),
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- the value is compared by content (`savedKey`)
-    [savedKey, mode, draftOptions]
-  );
   const savedSingle = saved.mode === 'single' ? saved.slot.value : null;
   const savedText =
     saved.mode === 'range'
@@ -894,14 +1287,18 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
           type,
           dateFormat,
           timeFormat,
-          strings.rangeSeparator
+          strings.rangeSeparator,
+          savedDateText,
+          savedStrings
         )
       : saved.mode === 'multiple'
         ? formatMultipleText(
             saved.slots.map((slot) => slot.value),
             type,
             dateFormat,
-            timeFormat
+            timeFormat,
+            savedDateText,
+            savedStrings
           )
         : precision !== 'day'
           ? periodText(savedSingle)
@@ -954,8 +1351,17 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     type,
     mode,
     value,
-    displayText:
-      savedText ?? formatValueText(savedSingle, type, dateFormat, timeFormat),
+    displayText: digitsFor(savedSystem)(
+      savedText ??
+        formatValueText(
+          savedSingle,
+          type,
+          dateFormat,
+          timeFormat,
+          savedDateText,
+          savedStrings
+        )
+    ),
     disabled,
     readOnly,
     isOpen,
@@ -981,7 +1387,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     draft.draft.mode === 'single' ? draft.draft.slot.value : null;
   // A time outside the limits is explained under the time row, not here.
   const sheetValueError =
-    sheetValue && dayOff(sheetValue.date) ? strings.errorNotAllowed : '';
+    sheetValue && dayOff(sheetValue.date) ? shownStrings.errorNotAllowed : '';
 
   let rangeError = '';
   if (d.mode === 'range' && d.from.value && d.to.value) {
@@ -990,14 +1396,14 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       constraints.dayStatus(d.from.value.date).disabled ||
       constraints.dayStatus(d.to.value.date).disabled
     )
-      rangeError = strings.errorNotAllowed;
+      rangeError = shownStrings.errorNotAllowed;
     else if (previewIssue === 'RANGE_ORDER')
-      rangeError = strings.errorRangeOrder;
+      rangeError = shownStrings.errorRangeOrder;
     else if (previewIssue === 'RANGE_LENGTH')
       rangeError =
         range?.minDays !== undefined && length < range.minDays
-          ? strings.errorRangeTooShort(range.minDays)
-          : strings.errorRangeTooLong(range?.maxDays ?? length);
+          ? shownStrings.errorRangeTooShort(range.minDays)
+          : shownStrings.errorRangeTooLong(range?.maxDays ?? length);
   }
 
   const fieldCommon = {
@@ -1019,8 +1425,11 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     ) : (
       <ValueField
         {...fieldCommon}
+        strings={savedStrings}
+        errorStrings={strings}
         value={savedSingle}
         displayText={savedText}
+        dateText={savedDateText}
         allowTyping={
           mode === 'single' && precision === 'day' && allowFieldTyping
         }
@@ -1062,8 +1471,11 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     ) : mode === 'single' ? (
       <ValueField
         {...fieldCommon}
+        strings={draftStrings}
+        errorStrings={shownStrings}
         value={sheetValue}
         displayText={precision !== 'day' ? periodText(sheetValue) : undefined}
+        dateText={draftDateText}
         placeholder={sheetOptions?.fieldPlaceholder ?? periodPlaceholder}
         allowTyping={allowTyping && precision === 'day'}
         onTyped={onSheetTyped}
@@ -1078,13 +1490,16 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     ) : d.mode === 'range' ? (
       <RangeFields
         {...fieldCommon}
+        strings={draftStrings}
+        errorStrings={shownStrings}
         layout={rangeLayout}
+        dateText={draftDateText}
         showIcon={sheetOptions?.fieldIcon}
         from={d.from.value}
         to={d.to.value}
         placeholder={sheetOptions?.fieldPlaceholder}
         activeEnd={activeEnd}
-        onActivate={setActiveEnd}
+        onActivate={activateEnd}
         allowTyping={allowTyping}
         onTyped={onRangeTyped}
         onFocusChange={(end, f) => reportFocus(`value-${end}`, f)}
@@ -1097,12 +1512,15 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
     ) : d.mode === 'multiple' ? (
       <ValueField
         {...fieldCommon}
+        strings={draftStrings}
         value={null}
         displayText={formatMultipleText(
           draftValues,
           type,
           dateFormat,
-          timeFormat
+          timeFormat,
+          draftDateText,
+          draftStrings
         )}
         placeholder={sheetOptions?.fieldPlaceholder}
         allowClear={allowClear}
@@ -1114,41 +1532,114 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       />
     ) : null;
 
-  const calendar = folded ? null : (
-    <Calendar
-      constraints={calendarConstraints}
-      today={today}
-      initialVisibleDate={initialVisibleDate}
-      selection={selection}
-      onSelectDay={onSelectDay}
-      firstDayOfWeek={firstDayOfWeek}
-      showOutsideDays={showOutsideDays}
-      showHolidays={showHolidays}
-      yearRange={yearRange}
-      locale={loc}
-      // Month and year picks are Gregorian whatever the calendar system.
-      calendarSystem={
-        precision === 'day' ? resolveCalendarSystem(calendarSystem) : 'gregory'
-      }
-      initialView={initialView}
-      precision={precision}
-      enableMonthSwipe={enableMonthSwipe}
-      showToday={showToday}
-      onVisibleMonthChange={handleVisibleMonth}
-      renderDay={renderDay}
-      renderWeekday={renderWeekday}
-      renderMonthChip={renderMonthChip}
-      renderYearCell={renderYearCell}
-      renderMonthCell={renderMonthCell}
-      renderEmptyState={renderEmptyState}
-      icons={icons}
-      iconProps={iconProps}
+  const systemLabels: Record<CalendarSystem, string> = {
+    gregory: strings.calendarGregorian ?? DEFAULT_STRINGS.calendarGregorian,
+    hijri: strings.calendarHijri ?? DEFAULT_STRINGS.calendarHijri,
+    dual: strings.calendarDual ?? DEFAULT_STRINGS.calendarDual,
+  };
+  const systemA11yLabel =
+    strings.a11yCalendarSystem ?? DEFAULT_STRINGS.a11yCalendarSystem;
+  const chooseSystem = (next: CalendarSystem) => {
+    if (next === system) return;
+    setChosenSystem(next);
+    if (next === 'dual') setDualTab(dualDefaultTab);
+    echo.current = next;
+    onCalendarSystemChange?.(next);
+  };
+  const calendarSwitchNode = !switchSystems ? null : renderCalendarSwitch ? (
+    renderCalendarSwitch({
+      systems: switchSystems,
+      selected: system,
+      onSelect: chooseSystem,
+      tokens,
+      strings,
+    })
+  ) : (
+    <CalendarSwitch
+      variant="switch"
+      options={switchSystems.map((v) => {
+        return { value: v, label: systemLabels[v] };
+      })}
+      selected={system}
+      onSelect={chooseSystem}
+      accessibilityLabel={systemA11yLabel}
       tokens={tokens}
       styles={styles}
-      strings={strings}
-      testID={testID}
+      testID={testID ? `${testID}-calendar-switch` : undefined}
     />
   );
+  const dualTabs =
+    system !== 'dual' ? null : (
+      <CalendarSwitch
+        variant="tabs"
+        options={[
+          { value: 'gregory', label: systemLabels.gregory },
+          { value: 'hijri', label: systemLabels.hijri },
+        ]}
+        selected={dualTab}
+        onSelect={setDualTab}
+        accessibilityLabel={systemA11yLabel}
+        tokens={tokens}
+        styles={styles}
+        testID={testID ? `${testID}-dual-tabs` : undefined}
+      />
+    );
+  // The Hijri tab lays out its calendar and time rows right to left; the
+  // wrapper always renders, so a tab change doesn't remount the time boxes.
+  const hijriShown = shownSystem === 'hijri';
+  const mirrored = (node: React.ReactNode) =>
+    node == null ? null : (
+      <RtlContext.Provider value={hijriShown || null}>
+        <View style={hijriShown ? RTL : undefined}>{node}</View>
+      </RtlContext.Provider>
+    );
+  // Another calendar opens on the days the last one showed, else on the
+  // selection (shown or not), else where the picker would open.
+  const calendarAnchor =
+    shownAnchor.current ??
+    (selectionShown ? null : firstSelectedDay(selection)) ??
+    initialVisibleDate;
+
+  const calendar = (
+    <View style={folded ? FOLDED : undefined}>
+      {calendarSwitchNode}
+      {dualTabs}
+      {mirrored(
+        <Calendar
+          key={shownSystem}
+          constraints={selectionShown ? calendarConstraints : constraints}
+          today={today}
+          initialVisibleDate={calendarAnchor}
+          selection={selectionShown ? selection : emptySelection(selection)}
+          onSelectDay={onSelectDayStable}
+          firstDayOfWeek={firstDayOfWeek}
+          showOutsideDays={showOutsideDays}
+          showHolidays={showHolidays}
+          yearRange={yearRange}
+          locale={shownSystem === 'hijri' ? hijriLocale : loc}
+          calendarSystem={shownSystem}
+          initialView={initialView}
+          precision={precision}
+          enableMonthSwipe={enableMonthSwipe}
+          showToday={showToday}
+          onVisibleMonthChange={handleVisibleMonth}
+          onAnchorChange={rememberAnchor}
+          renderDay={renderDay}
+          renderWeekday={renderWeekday}
+          renderMonthChip={renderMonthChip}
+          renderYearCell={renderYearCell}
+          renderMonthCell={renderMonthCell}
+          renderEmptyState={renderEmptyState}
+          icons={icons}
+          iconProps={iconProps}
+          tokens={tokens}
+          styles={styles}
+          strings={stringsFor(shownSystem)}
+          testID={testID}
+        />
+      )}
+    </View>
+  );
 
   const timeRow =
     type !== 'datetime' ? null : renderTimeRow ? (
@@ -1179,7 +1670,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
         onPendingChange={onRowPending}
         tokens={tokens}
         styles={styles}
-        strings={strings}
+        strings={stringsFor(shownSystem)}
         testID={testID}
       />
     );
@@ -1192,11 +1683,19 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       ? validation.message
       : null;
 
+  // The field writes the date in the digits of the calendar it was picked in;
+  // the calendar and the time rows follow the tab that shows.
   const sheetContent = (
     <>
-      {sheetField}
-      {calendar}
-      {timeRow}
+      <NumeralsContext.Provider value={digitsFor(draftSystem)}>
+        {sheetField}
+      </NumeralsContext.Provider>
+      <NumeralsContext.Provider value={digitsFor(shownSystem)}>
+        {calendar}
+      </NumeralsContext.Provider>
+      <NumeralsContext.Provider value={digitsFor(shownSystem)}>
+        {mirrored(timeRow)}
+      </NumeralsContext.Provider>
       {validationMessage ? (
         <FieldMessages
           error={validationMessage}
@@ -1212,7 +1711,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
   );
 
   return (
-    <>
+    <NumeralsContext.Provider value={digitsFor(savedSystem)}>
       {trigger}
       <PickerContainer
         presentation={presentation}
@@ -1235,7 +1734,7 @@ const DateTimePicker: React.FC<DateTimePickerProps> = (props) => {
       >
         {sheetContent}
       </PickerContainer>
-    </>
+    </NumeralsContext.Provider>
   );
 };