panelui-native 0.28.1 → 0.32.0

package/src/components/calendar/index.tsx

@@ -15,44 +15,63 @@
  * between months. So the grid is six rows always, and the spare cells hold the
  * neighbouring months' days.
  *
- * ## Why a range is drawn in three pieces
+ * ## How a range is drawn
  *
  * On the web the band under a selected range is one background with the ends
  * rounded by `:first-child` and `:last-child`. There are no pseudo-classes
- * here, so each day works out for itself whether it is a start, a middle or an
- * end — and, separately, whether it is at the edge of its own row, because a
- * range that runs over a weekend has to close off on Saturday and open again
- * on Sunday rather than trailing into the gap.
+ * here, so each cell draws its own piece of the band as a view *behind* the
+ * number, and works out for itself where that piece has to stop.
  *
- * Every cell therefore draws its band as a view *behind* the number, sized and
- * rounded from those flags, rather than as a background on the cell itself.
+ * Two questions, and they are not the same one:
+ *
+ * - **How wide.** A day between the two ends fills its cell, so the pieces meet
+ *   and the band reads as continuous. An end fills half its cell, from the
+ *   centre outwards towards the middle of the range — the half that is not
+ *   covered by the disc, so the disc appears to sit *on* the band rather than
+ *   beside it. That is the join the old three-piece version never made, which
+ *   is why a range used to read as two discs with a gap and a stripe.
+ * - **Where it is rounded.** Only where it genuinely stops: at an end of the
+ *   range, or at the edge of a row, because a range running over a weekend has
+ *   to close off on Saturday and open again on Sunday rather than trailing into
+ *   the gap between the two.
  */
 import {
   createContext,
   useCallback,
   useContext,
+  useEffect,
   useMemo,
+  useRef,
   useState,
-  type ReactNode,
 } from 'react';
-import { Pressable, View, type ViewProps } from 'react-native';
+import { AppState, Pressable, ScrollView, View, type ViewProps } from 'react-native';
 import { tv } from 'tailwind-variants';
-import { ChevronLeftIcon, ChevronRightIcon } from '../../icons';
+import { useCSSVariable } from 'uniwind';
+import {
+  CheckIcon,
+  ChevronDownIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+} from '../../icons';
 import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
+import { Popover } from '../popover';
 import {
   addCalendarMonths,
-  addDays,
   calendarDayNumber,
   calendarLongDate,
   calendarMonthLabel,
   calendarMonthNames,
   calendarParts,
+  clampDate,
   isAfter,
   isBefore,
   isSameCalendarMonth,
   isSameDay,
   isWithin,
+  localeWeekStart,
+  monthGrid,
+  normalizeWeekStart,
   resolveCalendar,
   startOfCalendarMonth,
   startOfDay,
@@ -90,24 +109,56 @@ export type CalendarDisabled =
   | { from: Date; to: Date }
   | ((date: Date) => boolean);
 
+/**
+ * The corner radius of a day, and so of the band that runs between days.
+ *
+ * A number rather than a class because the band's four corners are set
+ * independently from the flags below, which no single `rounded-*` can express.
+ */
+const DAY_RADIUS = 8;
+
+const calendarVariants = tv({
+  slots: {
+    root: 'gap-3',
+    header: 'h-10 flex-row items-center justify-between gap-2',
+    nav: 'h-8 w-8 items-center justify-center rounded-full',
+    caption: 'flex-1 flex-row items-center justify-center gap-1',
+  },
+  variants: {
+    /** Draw the calendar's own panel, for one standing on the page. */
+    bordered: {
+      true: { root: 'rounded-3xl border border-border bg-card p-3' },
+    },
+  },
+  defaultVariants: {
+    bordered: true,
+  },
+});
+
 const dayVariants = tv({
   slots: {
-    cell: 'flex-1 items-center justify-center',
+    cell: 'h-10 flex-1 items-center justify-center',
     /** The range band, drawn behind the number so it can run cell to cell. */
-    band: 'absolute inset-y-1',
-    /** The circle on a selected day, or the ring on today. */
-    disc: 'h-9 w-9 items-center justify-center rounded-full',
-    label: '',
+    band: 'absolute inset-y-0.5 bg-accent',
+    /**
+     * The fill on a selected day, or the ring on today. Square-ish rather than
+     * round: a circle has one point of contact with the band beside it, so a
+     * range reads as beads on a string. A rounded rectangle meets the band
+     * along its whole edge and the two become one shape.
+     */
+    disc: 'h-9 w-9 items-center justify-center rounded-lg',
+    label: 'text-sm',
   },
   variants: {
     selected: { true: { disc: 'bg-primary', label: 'text-primary-foreground' } },
     today: { true: { disc: 'border border-primary', label: 'text-primary' } },
     outside: { true: { label: 'text-muted-foreground/40' } },
     disabled: { true: { label: 'text-muted-foreground/30' } },
-    inRange: { true: { band: 'bg-accent' } },
+    /** A ruled-out day inside a range still sits on it, but faintly. */
+    fadedBand: { true: { band: 'opacity-40' } },
   },
   compoundVariants: [
-    // A selected day inside a range keeps the solid disc; the band passes
+    // A selected day inside a range keeps the solid fill; the band passes
     // under it rather than the disc losing to it.
     { selected: true, today: true, class: { label: 'text-primary-foreground' } },
   ],
@@ -121,6 +172,9 @@ interface CalendarContextValue {
   system: 'gregory' | 'islamic';
   minDate?: Date;
   maxDate?: Date;
+  /** Bounds for the caption's pickers, which are not the selectable bounds. */
+  startMonth?: Date;
+  endMonth?: Date;
   captionLayout: CalendarCaptionLayout;
 }
 
@@ -134,6 +188,35 @@ function useCalendar(component: string): CalendarContextValue {
   return context;
 }
 
+/**
+ * Today, kept current.
+ *
+ * "Today" is not a constant, and a calendar is exactly the kind of thing left
+ * on screen across the boundary that changes it — a picker open in a sheet, an
+ * app resumed the next morning. Recomputed when the app comes back to the
+ * foreground, which is when a stale answer would otherwise become visible, and
+ * held as state so the marker actually moves when it does.
+ */
+function useToday(): Date {
+  const [today, setToday] = useState(() => startOfDay(new Date()));
+
+  useEffect(() => {
+    const refresh = () => {
+      const now = startOfDay(new Date());
+      // A new object every resume would invalidate every memo below it for a
+      // date that has not changed.
+      setToday((current) => (current.getTime() === now.getTime() ? current : now));
+    };
+
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') refresh();
+    });
+    return () => subscription.remove();
+  }, []);
+
+  return today;
+}
+
 /** Whether a rule, a list or a span rules this day out. */
 function isDisabled(
   date: Date,
@@ -141,8 +224,14 @@ function isDisabled(
   minDate: Date | undefined,
   maxDate: Date | undefined
 ): boolean {
-  if (minDate && isBefore(date, minDate)) return true;
-  if (maxDate && isAfter(date, maxDate)) return true;
+  /*
+   * Both bounds are compared at local midnight, because they are about days
+   * and the caller almost always hands over a moment. `minDate={new Date()}`
+   * means "from today", and against a raw timestamp that would rule out every
+   * hour of today that has already passed — which is to say, today.
+   */
+  if (minDate && isBefore(date, startOfDay(minDate))) return true;
+  if (maxDate && isAfter(date, startOfDay(maxDate))) return true;
   if (!disabled) return false;
   if (typeof disabled === 'function') return disabled(date);
   if (Array.isArray(disabled)) return disabled.some((day) => isSameDay(day, date));
@@ -177,10 +266,44 @@ export interface CalendarProps<Mode extends CalendarMode = 'single'>
   minDate?: Date;
   /** Latest selectable day. */
   maxDate?: Date;
-  /** `0` is Sunday. */
-  weekStartsOn?: number;
+  /**
+   * Earliest month the caption's pickers offer. Defaults to `minDate`, and to
+   * a hundred years back when there is none.
+   *
+   * Separate from `minDate` because they answer different questions: `minDate`
+   * is about which days can be picked, this is about how far the month and year
+   * lists reach. A birthday picker wants a century of years on offer and no
+   * bound at all on the days inside them.
+   */
+  startMonth?: Date;
+  /** Latest month the caption's pickers offer. Defaults to `maxDate`, else ten years on. */
+  endMonth?: Date;
+  /**
+   * Which day the week's first column is. `0` is Sunday.
+   *
+   * `auto` asks the locale, which is what most of the world wants — `en-GB` and
+   * `fr-FR` start on Monday, and a calendar that says otherwise is wrong in a
+   * way its reader notices immediately. It is not the default only because
+   * changing an existing calendar's columns out from under it is not something
+   * a version bump should do. Out-of-range numbers wrap rather than producing
+   * a blank column.
+   */
+  weekStartsOn?: number | 'auto';
   /** Draw the neighbouring months' days rather than leaving the cells blank. */
   showOutsideDays?: boolean;
+  /**
+   * Let a tap on a neighbouring month's day select it. Off by default: those
+   * cells exist to keep the grid six rows tall, and a tap on one is far more
+   * often a misfire than an attempt to reach into July from June. Paging to the
+   * month is the way to pick a day in it.
+   */
+  selectOutsideDays?: boolean;
+  /**
+   * Draw the calendar's own panel — a rounded, bordered card. On by default,
+   * for a calendar standing on a page. Turn it off when it is already inside
+   * something that draws one, which is what `DatePicker` does.
+   */
+  bordered?: boolean;
   /** BCP 47 tag for the month and weekday names. The device's own by default. */
   locale?: DateLocale;
   /**
@@ -208,8 +331,12 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
   disabled,
   minDate,
   maxDate,
-  weekStartsOn = 0,
+  startMonth,
+  endMonth,
+  weekStartsOn: weekStartsOnProp = 0,
   showOutsideDays = true,
+  selectOutsideDays = false,
+  bordered = true,
   locale,
   calendar = 'gregory',
   ...props
@@ -217,6 +344,16 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
   // Settled once here rather than at each call site, so every part of the
   // grid is certainly reading the same calendar.
   const system = useMemo(() => resolveCalendar(calendar, locale), [calendar, locale]);
+  // Settled once too, and normalised: everything below indexes an array of
+  // seven with it, where a negative or out-of-range value is a blank column
+  // rather than an error anyone would trace back to here.
+  const weekStartsOn = useMemo(
+    () =>
+      weekStartsOnProp === 'auto'
+        ? localeWeekStart(locale)
+        : normalizeWeekStart(weekStartsOnProp),
+    [weekStartsOnProp, locale]
+  );
   const [internalSelected, setInternalSelected] = useState<CalendarSelection[Mode] | undefined>(
     defaultSelected
   );
@@ -243,15 +380,52 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
   }, []);
 
   const [internalMonth, setInternalMonth] = useState(initialMonth);
-  const month = monthProp ? startOfCalendarMonth(monthProp, system, locale) : internalMonth;
+  /*
+   * Memoised on the *instant*, not on the prop. A controlled caller almost
+   * always passes a fresh `new Date(…)`, and deriving a new month object from
+   * it on every render invalidates the grid memo and the context memo below —
+   * so a calendar that has not moved rebuilds forty-two cells per keystroke
+   * somewhere else on the screen.
+   */
+  const controlledMonth = useMemo(
+    () => (monthProp ? startOfCalendarMonth(monthProp, system, locale) : undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [monthProp?.getTime(), system, locale]
+  );
+  const month = controlledMonth ?? internalMonth;
+
+  /*
+   * How far the calendar may be paged, as the first day of the outermost month
+   * either way. `startMonth`/`endMonth` win where they are given, because they
+   * are the props about *navigation*; `minDate`/`maxDate` are about which days
+   * can be picked, and stand in when the navigation bounds are not stated.
+   */
+  const monthBounds = useMemo(() => {
+    const lower = startMonth ?? minDate;
+    const upper = endMonth ?? maxDate;
+    return {
+      from: lower ? startOfCalendarMonth(lower, system, locale) : undefined,
+      to: upper ? startOfCalendarMonth(upper, system, locale) : undefined,
+    };
+  }, [startMonth, minDate, endMonth, maxDate, system, locale]);
 
   const setMonth = useCallback(
     (next: Date) => {
-      const settled = startOfCalendarMonth(next, system, locale);
+      /*
+       * Clamped here rather than only at the arrows. The arrows guard
+       * themselves, but the caption's dropdowns and a controlled caller both
+       * reach this by other routes — and a month list that offers a year is a
+       * poor place to discover that the year was out of bounds.
+       */
+      const settled = clampDate(
+        startOfCalendarMonth(next, system, locale),
+        monthBounds.from,
+        monthBounds.to
+      );
       if (!monthProp) setInternalMonth(settled);
       onMonthChange?.(settled);
     },
-    [monthProp, onMonthChange, system, locale]
+    [monthProp, onMonthChange, system, locale, monthBounds]
   );
 
   const commit = useCallback(
@@ -266,6 +440,14 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
     (date: Date) => {
       const day = startOfDay(date);
 
+      /*
+       * A tap on a neighbouring month's cell — which only happens with
+       * `selectOutsideDays` — commits a date the grid is not showing. Page to
+       * it, or the selection lands in a greyed-out cell of the month you are
+       * still looking at and reads as having missed.
+       */
+      if (!isSameCalendarMonth(day, month, system, locale)) setMonth(day);
+
       if (mode === 'multiple') {
         const current = (value as Date[] | undefined) ?? [];
         const without = current.filter((picked) => !isSameDay(picked, day));
@@ -294,20 +476,33 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
       const current = value as Date | undefined;
       commit((isSameDay(current, day) ? undefined : day) as CalendarSelection[Mode]);
     },
-    [mode, value, commit]
+    [mode, value, commit, month, system, locale, setMonth]
   );
 
   const context = useMemo(
-    () => ({ month, setMonth, locale, system, minDate, maxDate, captionLayout }),
-    [month, setMonth, locale, system, minDate, maxDate, captionLayout]
+    () => ({
+      month,
+      setMonth,
+      locale,
+      system,
+      minDate,
+      maxDate,
+      startMonth,
+      endMonth,
+      captionLayout,
+    }),
+    [month, setMonth, locale, system, minDate, maxDate, startMonth, endMonth, captionLayout]
   );
 
+  const { root } = calendarVariants({ bordered });
+  const months = Math.max(1, numberOfMonths);
+
   return (
     <CalendarContext.Provider value={context}>
-      <View {...props} className={cn('gap-4', className)}>
-        {Array.from({ length: Math.max(1, numberOfMonths) }, (_unused, offset) => (
+      <View {...props} className={cn(root(), className)}>
+        {Array.from({ length: months }, (_unused, offset) => (
           <View key={offset} className="gap-2">
-            <CalendarCaption offset={offset} lastOffset={numberOfMonths - 1} />
+            <CalendarHeader offset={offset} lastOffset={months - 1} />
             <CalendarGrid
               month={addCalendarMonths(month, offset, system, locale)}
               mode={mode}
@@ -318,6 +513,7 @@ function CalendarRoot<Mode extends CalendarMode = 'single'>({
               maxDate={maxDate}
               weekStartsOn={weekStartsOn}
               showOutsideDays={showOutsideDays}
+              selectOutsideDays={selectOutsideDays}
               locale={locale}
               system={system}
             />
@@ -333,16 +529,29 @@ CalendarRoot.displayName = 'Calendar';
 /* Caption                                                                    */
 /* -------------------------------------------------------------------------- */
 
+export interface CalendarHeaderProps {
+  /** Which month of the run this header sits over. `0` is the first. */
+  offset?: number;
+  /** The last offset in the run, so the header knows whether it owns the arrow. */
+  lastOffset?: number;
+}
+
 /**
- * The month name and the arrows, or the month and year pickers.
+ * The row over a month: an arrow at each edge and the month's name between
+ * them.
  *
- * With several months shown the arrows are split across the row — back on the
- * first, forward on the last — because both sets on both captions would page
- * the whole run and give two ways to do one thing.
+ * The arrows are pinned to the edges of the calendar rather than packed around
+ * the label, so the two targets are as far apart as the panel allows and the
+ * name sits centred over its own grid. With several months shown they are split
+ * across the run — back on the first, forward on the last — because both sets
+ * on both headers would page the whole run and give two ways to do one thing.
+ * The month that owns neither still lays out a spacer, or its name would slide
+ * off centre.
  */
-function CalendarCaption({ offset, lastOffset }: { offset: number; lastOffset: number }) {
+function CalendarHeader({ offset = 0, lastOffset = 0 }: CalendarHeaderProps) {
   const { month, setMonth, locale, system, minDate, maxDate, captionLayout } =
-    useCalendar('Calendar.Caption');
+    useCalendar('Calendar.Header');
+  const { header, caption } = calendarVariants();
   const shown = addCalendarMonths(month, offset, system, locale);
 
   const canGoBack =
@@ -351,7 +560,7 @@ function CalendarCaption({ offset, lastOffset }: { offset: number; lastOffset: n
     !maxDate || isAfter(startOfCalendarMonth(maxDate, system, locale), shown);
 
   return (
-    <View className="h-9 flex-row items-center justify-between">
+    <View className={header()}>
       {offset === 0 ? (
         <CalendarNav
           direction="previous"
@@ -359,14 +568,18 @@ function CalendarCaption({ offset, lastOffset }: { offset: number; lastOffset: n
           onPress={() => setMonth(addCalendarMonths(month, -1, system, locale))}
         />
       ) : (
-        <View className="h-7 w-7" />
+        <View className="h-8 w-8" />
       )}
 
-      {captionLayout === 'dropdown' ? (
-        <CalendarDropdowns month={shown} offset={offset} />
-      ) : (
-        <Text weight="semibold">{calendarMonthLabel(shown, system, locale)}</Text>
-      )}
+      <View className={caption()}>
+        {captionLayout === 'dropdown' ? (
+          <CalendarDropdowns month={shown} offset={offset} />
+        ) : (
+          <Text weight="semibold" className="text-base">
+            {calendarMonthLabel(shown, system, locale)}
+          </Text>
+        )}
+      </View>
 
       {offset === lastOffset ? (
         <CalendarNav
@@ -375,21 +588,28 @@ function CalendarCaption({ offset, lastOffset }: { offset: number; lastOffset: n
           onPress={() => setMonth(addCalendarMonths(month, 1, system, locale))}
         />
       ) : (
-        <View className="h-7 w-7" />
+        <View className="h-8 w-8" />
       )}
     </View>
   );
 }
 
-function CalendarNav({
-  direction,
-  disabled,
-  onPress,
-}: {
+export interface CalendarNavProps {
   direction: 'previous' | 'next';
-  disabled: boolean;
-  onPress: () => void;
-}) {
+  disabled?: boolean;
+  onPress?: () => void;
+}
+
+/**
+ * One paging arrow.
+ *
+ * Borderless: two bordered squares at the ends of a bordered panel read as a
+ * row of boxes rather than as controls, and the chevron is legible enough on
+ * its own. The target is still 32px with another 8 of slop around it.
+ */
+function CalendarNav({ direction, disabled = false, onPress }: CalendarNavProps) {
+  const { nav } = calendarVariants();
+
   return (
     <Pressable
       disabled={disabled}
@@ -398,26 +618,28 @@ function CalendarNav({
       accessibilityRole="button"
       accessibilityLabel={direction === 'next' ? 'Next month' : 'Previous month'}
       accessibilityState={{ disabled }}
-      className={cn(
-        'h-7 w-7 items-center justify-center rounded-md border border-border',
-        disabled ? 'opacity-40' : 'active:bg-accent'
-      )}
+      className={cn(nav(), disabled ? 'opacity-30' : 'active:bg-accent')}
     >
-      {direction === 'next' ? <ChevronRightIcon size={16} /> : <ChevronLeftIcon size={16} />}
+      {direction === 'next' ? <ChevronRightIcon size={18} /> : <ChevronLeftIcon size={18} />}
     </Pressable>
   );
 }
 
 /**
- * Month and year as two rows of chips rather than as native pickers.
+ * Month and year as chips that open a panel of options.
  *
- * A picker is a platform overlay, and putting one on top of a calendar that is
- * itself already inside a popover is two floating layers deep for choosing a
- * number. Chips stay on the surface the choice is being made on.
+ * The panel floats rather than opening in place, and the caption is the reason:
+ * it is a fixed-height row, so a list opened inside it has nowhere to go and
+ * spills over the grid below. A popover is laid out against the chip and
+ * clamped to the screen, which is the behaviour this needs and already has.
+ *
+ * Native pickers are still the wrong tool — a platform overlay on top of a
+ * calendar that is itself already in a popover is two floating layers deep for
+ * choosing a number, and it cannot show a Hijri year at all.
  */
 function CalendarDropdowns({ month, offset }: { month: Date; offset: number }) {
-  const { setMonth, locale, system, minDate, maxDate } = useCalendar('Calendar.Caption');
-  const [open, setOpen] = useState<'month' | 'year' | null>(null);
+  const { setMonth, locale, system, minDate, maxDate, startMonth, endMonth } =
+    useCalendar('Calendar.Caption');
 
   /*
    * Everything here counts in the calendar on screen, not in the platform's.
@@ -430,10 +652,46 @@ function CalendarDropdowns({ month, offset }: { month: Date; offset: number }) {
     [month, system, locale]
   );
   const current = calendarParts(month, system, locale);
+  /*
+   * `startMonth`/`endMonth` bound the lists, falling back to the selectable
+   * bounds and then to a century back and a decade on. They are separate props
+   * because the two questions are different: a birthday picker wants a hundred
+   * years on offer and no bound at all on the days inside them.
+   */
+  const first = startMonth ?? minDate;
+  const last = endMonth ?? maxDate;
+  const firstParts = first ? calendarParts(first, system, locale) : null;
+  const lastParts = last ? calendarParts(last, system, locale) : null;
   const bounds = {
-    from: minDate ? calendarParts(minDate, system, locale).year : current.year - 100,
-    to: maxDate ? calendarParts(maxDate, system, locale).year : current.year + 10,
+    from: firstParts ? firstParts.year : current.year - 100,
+    to: lastParts ? lastParts.year : current.year + 10,
   };
+  /*
+   * The month list is bounded too, and only the year list used to be — so a
+   * calendar starting in March 1925 still offered January and February of 1925,
+   * and picking one navigated somewhere the calendar had said it would not go.
+   * Only the outermost year of each bound loses months; every year between them
+   * has all twelve.
+   */
+  const monthOptions = months
+    .map((label, index) => ({ label, month: index + 1 }))
+    .filter(({ month }) => {
+      if (firstParts && current.year === firstParts.year && month < firstParts.month) {
+        return false;
+      }
+      if (lastParts && current.year === lastParts.year && month > lastParts.month) {
+        return false;
+      }
+      return true;
+    });
+  /*
+   * Oldest first, the way a year runs. The list is long — a century by default
+   * — so it is opened scrolled to the year already in the caption rather than
+   * to either end, which is what makes the natural order affordable. Counting
+   * backwards was a way of putting the likely years at the top of a list that
+   * always opened at the top; it is not needed once the list opens in the right
+   * place, and it made every other use of the picker read upside down.
+   */
   const years = Array.from(
     { length: Math.max(1, bounds.to - bounds.from + 1) },
     (_unused, index) => bounds.from + index
@@ -446,77 +704,163 @@ function CalendarDropdowns({ month, offset }: { month: Date; offset: number }) {
    */
   const choose = (months_: number) => {
     setMonth(addCalendarMonths(month, months_ - offset, system, locale));
-    setOpen(null);
   };
 
   return (
-    <View className="flex-1 items-center">
-      <View className="flex-row items-center gap-1">
-        <CaptionChip
-          label={months[current.month - 1] ?? String(current.month)}
-          expanded={open === 'month'}
-          onPress={() => setOpen(open === 'month' ? null : 'month')}
-        />
-        <CaptionChip
-          label={String(current.year)}
-          expanded={open === 'year'}
-          onPress={() => setOpen(open === 'year' ? null : 'year')}
-        />
-      </View>
+    <>
+      <CaptionDropdown
+        label={months[current.month - 1] ?? String(current.month)}
+        accessibilityLabel="Month"
+        options={monthOptions.map((option) => option.label)}
+        active={monthOptions.findIndex((option) => option.month === current.month)}
+        width={MONTH_LIST_WIDTH}
+        onSelect={(index) => choose((monthOptions[index]?.month ?? current.month) - current.month)}
+      />
+      <CaptionDropdown
+        label={String(current.year)}
+        accessibilityLabel="Year"
+        options={years.map(String)}
+        active={years.indexOf(current.year)}
+        width={YEAR_LIST_WIDTH}
+        onSelect={(index) => choose((years[index]! - current.year) * 12)}
+      />
+    </>
+  );
+}
+
+/** Panel widths. A month name needs the room; a four-digit year does not. */
+const MONTH_LIST_WIDTH = 176;
+const YEAR_LIST_WIDTH = 132;
+
+/**
+ * Height of one option row, and the tallest the list is allowed to be.
+ *
+ * The row height is a constant rather than a measurement because it is what
+ * turns "the twenty-ninth option" into a scroll offset, and that has to be
+ * known before the list has laid out — the whole point is that it opens in the
+ * right place rather than scrolling there afterwards.
+ */
+const OPTION_HEIGHT = 40;
+const LIST_MAX_HEIGHT = OPTION_HEIGHT * 6.5;
+
+/**
+ * One chip and the list of options it opens.
+ *
+ * A list, not a grid of chips. Twelve months tile into a panel well enough, but
+ * the same treatment applied to a century of years is a wall of four-digit
+ * numbers with no order the eye can follow — and it opened at whichever end
+ * happened to be first. Rows in a column read as a list, take a checkmark, and
+ * can be scrolled to a particular one.
+ */
+function CaptionDropdown({
+  label,
+  accessibilityLabel,
+  options,
+  active,
+  width,
+  onSelect,
+}: {
+  label: string;
+  accessibilityLabel: string;
+  options: string[];
+  /** Index of the option currently in the caption, or -1 for none. */
+  active: number;
+  width: number;
+  onSelect: (index: number) => void;
+}) {
+  const [open, setOpen] = useState(false);
+  const list = useRef<ScrollView>(null);
+  /*
+   * The check is given a colour rather than left to its own fallback, which is
+   * white — right inside a filled control, invisible on this panel.
+   */
+  const rawTick = useCSSVariable('--color-foreground');
+  const tick = typeof rawTick === 'string' ? rawTick : undefined;
+
+  /*
+   * Opened on the option already in the caption, centred in the panel rather
+   * than pinned to an edge so the years either side of it are in view too. A
+   * hundred-item list that opens at the top is showing the one year nobody came
+   * to pick, and asks for a flick through a century to reach the one they did.
+   */
+  const scrollToActive = useCallback(() => {
+    if (active < 0) return;
+    const centred = active * OPTION_HEIGHT - LIST_MAX_HEIGHT / 2 + OPTION_HEIGHT / 2;
+    list.current?.scrollTo({ y: Math.max(0, centred), animated: false });
+  }, [active]);
 
-      {open ? (
-        <View className="mt-2 max-h-40 w-full flex-row flex-wrap justify-center gap-1 rounded-lg border border-border bg-popover p-2">
-          {(open === 'month' ? months : years.map(String)).map((option, index) => {
-            const active =
-              open === 'month'
-                ? index === current.month - 1
-                : years[index] === current.year;
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <Popover.Trigger>
+        <CaptionChip label={label} expanded={open} accessibilityLabel={accessibilityLabel} />
+      </Popover.Trigger>
+      <Popover.Content align="center" width={width} className="p-1.5">
+        <ScrollView
+          ref={list}
+          bounces={false}
+          showsVerticalScrollIndicator={false}
+          style={{ maxHeight: LIST_MAX_HEIGHT }}
+          // Fires once the rows exist, which is the first moment there is
+          // anything to scroll. Doing it on mount would scroll an empty list.
+          onContentSizeChange={scrollToActive}
+        >
+          {options.map((option, index) => {
+            const selected = index === active;
             return (
               <Pressable
                 key={option}
-                onPress={() =>
-                  choose(
-                    open === 'month'
-                      ? index - (current.month - 1)
-                      : (years[index]! - current.year) * 12
-                  )
-                }
+                onPress={() => {
+                  onSelect(index);
+                  setOpen(false);
+                }}
                 accessibilityRole="button"
-                accessibilityState={{ selected: active }}
+                accessibilityState={{ selected }}
+                style={{ height: OPTION_HEIGHT }}
                 className={cn(
-                  'rounded-md px-2.5 py-1.5',
-                  active ? 'bg-primary' : 'active:bg-accent'
+                  'flex-row items-center justify-between gap-2 rounded-xl px-3',
+                  selected ? 'bg-accent' : 'active:bg-accent'
                 )}
               >
-                <Text size="sm" className={active ? 'text-primary-foreground' : undefined}>
+                <Text size="sm" weight={selected ? 'semibold' : 'normal'}>
                   {option}
                 </Text>
+                {selected ? <CheckIcon size={16} color={tick} /> : null}
               </Pressable>
             );
           })}
-        </View>
-      ) : null}
-    </View>
+        </ScrollView>
+      </Popover.Content>
+    </Popover>
   );
 }
 
 function CaptionChip({
   label,
   expanded,
+  accessibilityLabel,
   onPress,
 }: {
   label: string;
   expanded: boolean;
-  onPress: () => void;
+  accessibilityLabel: string;
+  /** Supplied by `Popover.Trigger`, which clones this to open the panel. */
+  onPress?: (...args: unknown[]) => void;
 }) {
   return (
     <Pressable
       onPress={onPress}
       accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
       accessibilityState={{ expanded }}
-      className="flex-row items-center gap-1 rounded-md px-2 py-1 active:bg-accent"
+      className="flex-row items-center gap-1 rounded-lg px-2 py-1.5 active:bg-accent"
     >
       <Text weight="semibold">{label}</Text>
+      {/*
+        The chevron says the chip opens something. Without it a bold word in the
+        middle of a header is indistinguishable from the plain caption layout,
+        and nobody thinks to press it.
+      */}
+      <ChevronDownIcon size={14} />
     </Pressable>
   );
 }
@@ -535,6 +879,7 @@ interface GridProps {
   maxDate?: Date;
   weekStartsOn: number;
   showOutsideDays: boolean;
+  selectOutsideDays?: boolean;
   locale: DateLocale;
   system: 'gregory' | 'islamic';
 }
@@ -549,6 +894,7 @@ function CalendarGrid({
   maxDate,
   weekStartsOn,
   showOutsideDays,
+  selectOutsideDays = false,
   locale,
   system,
 }: GridProps) {
@@ -558,16 +904,12 @@ function CalendarGrid({
    * boundaries and the day numbers differ — so the walk itself is the same
    * either way and only where it starts moves.
    */
-  const weeks = useMemo(() => {
-    const first = startOfCalendarMonth(month, system, locale);
-    const lead = (first.getDay() - weekStartsOn + 7) % 7;
-    const start = addDays(first, -lead);
-    return Array.from({ length: 6 }, (_unusedWeek, week) =>
-      Array.from({ length: 7 }, (_unusedDay, day) => addDays(start, week * 7 + day))
-    );
-  }, [month, weekStartsOn, system, locale]);
+  const weeks = useMemo(
+    () => monthGrid(month, weekStartsOn, system, locale),
+    [month, weekStartsOn, system, locale]
+  );
   const headings = useMemo(() => weekdayNames(locale, weekStartsOn), [locale, weekStartsOn]);
-  const today = startOfDay(new Date());
+  const today = useToday();
 
   const range = mode === 'range' ? (value as DateRange | undefined) : undefined;
   const multiple = mode === 'multiple' ? ((value as Date[] | undefined) ?? []) : [];
@@ -595,16 +937,38 @@ function CalendarGrid({
               return <View key={dayIndex} className="h-10 flex-1" />;
             }
 
+            const isStart = mode === 'range' && isSameDay(date, range?.from);
+            const isEnd = mode === 'range' && isSameDay(date, range?.to);
+
             const selected =
               mode === 'range'
-                ? isSameDay(date, range?.from) || isSameDay(date, range?.to)
+                ? isStart || isEnd
                 : mode === 'multiple'
                   ? multiple.some((picked) => isSameDay(picked, date))
                   : isSameDay(date, single);
 
-            // Between the ends, but not an end itself — the band, not the disc.
-            const inRange =
-              !!range?.to && isWithin(date, range.from, range.to) && !selected;
+            /*
+             * Inclusive of both ends, unlike the old middles-only rule. An end
+             * has to carry its half of the band or there is a gap between the
+             * disc and the run beside it — which is precisely what made a range
+             * read as two discs with a stripe floating between them.
+             */
+            const inRange = !!range?.to && isWithin(date, range.from, range.to);
+
+            /*
+             * Whether the band carries on past this cell's edge into the one
+             * beside it. It stops at an end of the range, and at the edge of a
+             * row — a range over a weekend closes on Saturday and opens again
+             * on Sunday rather than trailing into the gap between the rows.
+             */
+            const openStart = inRange && !isStart && dayIndex > 0;
+            const openEnd = inRange && !isEnd && dayIndex < 6;
+
+            // A neighbouring month's day is drawn, not offered. Reaching into
+            // July from June is what the arrows are for.
+            const ruledOut =
+              isDisabled(date, disabled, minDate, maxDate) ||
+              (outside && !selectOutsideDays);
 
             return (
               <CalendarDay
@@ -613,12 +977,12 @@ function CalendarGrid({
                 outside={outside}
                 selected={selected}
                 inRange={inRange}
+                rangeStart={isStart}
+                rangeEnd={isEnd}
                 today={isSameDay(date, today)}
-                disabled={isDisabled(date, disabled, minDate, maxDate)}
-                // The band closes off at the edges of a row rather than
-                // trailing into the gap between weeks.
-                openStart={inRange && dayIndex > 0}
-                openEnd={inRange && dayIndex < 6}
+                disabled={ruledOut}
+                openStart={openStart}
+                openEnd={openEnd}
                 locale={locale}
                 system={system}
                 onPress={() => onSelect(date)}
@@ -635,10 +999,15 @@ interface DayProps {
   date: Date;
   outside: boolean;
   selected: boolean;
+  /** Anywhere inside the range, ends included. */
   inRange: boolean;
+  rangeStart?: boolean;
+  rangeEnd?: boolean;
   today: boolean;
   disabled: boolean;
+  /** The band carries on past this cell's leading edge. */
   openStart: boolean;
+  /** The band carries on past this cell's trailing edge. */
   openEnd: boolean;
   locale: DateLocale;
   system: 'gregory' | 'islamic';
@@ -650,6 +1019,8 @@ function CalendarDay({
   outside,
   selected,
   inRange,
+  rangeStart = false,
+  rangeEnd = false,
   today,
   disabled,
   openStart,
@@ -663,9 +1034,28 @@ function CalendarDay({
     today: today && !selected,
     outside,
     disabled,
-    inRange,
+    fadedBand: disabled && inRange,
   });
 
+  /*
+   * An end of the range fills half its cell, from the centre outwards towards
+   * the rest of the range; every other day in it fills the whole cell. Half a
+   * cell is what puts the band underneath the disc rather than beside it — the
+   * disc is centred, so a band starting at the centre emerges from behind it
+   * and the two read as one shape. A range of one day gets both halves and so
+   * no band at all, which is right: there is nothing to span.
+   */
+  const bandStyle = inRange
+    ? {
+        left: rangeStart ? ('50%' as const) : 0,
+        right: rangeEnd ? ('50%' as const) : 0,
+        borderTopLeftRadius: openStart ? 0 : DAY_RADIUS,
+        borderBottomLeftRadius: openStart ? 0 : DAY_RADIUS,
+        borderTopRightRadius: openEnd ? 0 : DAY_RADIUS,
+        borderBottomRightRadius: openEnd ? 0 : DAY_RADIUS,
+      }
+    : null;
+
   return (
     <Pressable
       disabled={disabled}
@@ -673,23 +1063,11 @@ function CalendarDay({
       accessibilityRole="button"
       accessibilityLabel={calendarLongDate(date, system, locale)}
       accessibilityState={{ selected, disabled }}
-      className={cn(styles.cell(), 'h-10')}
+      className={styles.cell()}
     >
-      {inRange ? (
-        <View
-          className={cn(styles.band())}
-          style={{
-            left: openStart ? 0 : '10%',
-            right: openEnd ? 0 : '10%',
-            borderTopLeftRadius: openStart ? 0 : 999,
-            borderBottomLeftRadius: openStart ? 0 : 999,
-            borderTopRightRadius: openEnd ? 0 : 999,
-            borderBottomRightRadius: openEnd ? 0 : 999,
-          }}
-        />
-      ) : null}
-      <View className={cn(styles.disc())}>
-        <Text size="sm" className={cn(styles.label())}>
+      {bandStyle ? <View className={styles.band()} style={bandStyle} /> : null}
+      <View className={styles.disc()}>
+        <Text className={styles.label()}>
           {calendarDayNumber(date, system, locale)}
         </Text>
       </View>
@@ -698,6 +1076,8 @@ function CalendarDay({
 }
 
 export const Calendar = Object.assign(CalendarRoot, {
+  Header: CalendarHeader,
+  Nav: CalendarNav,
   Grid: CalendarGrid,
   Day: CalendarDay,
 });