panelui-native 0.28.1 → 0.32.0

package/lib/module/components/calendar/index.js

@@ -17,25 +17,35 @@
  * 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, useMemo, useState } from 'react';
-import { Pressable, View } from 'react-native';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { AppState, Pressable, ScrollView, View } from 'react-native';
 import { tv } from 'tailwind-variants';
-import { ChevronLeftIcon, ChevronRightIcon } from "../../icons/index.js";
+import { useCSSVariable } from 'uniwind';
+import { CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from "../../icons/index.js";
 import { Text } from "../../primitives/text.js";
 import { cn } from "../../utils/cn.js";
-import { addCalendarMonths, addDays, calendarDayNumber, calendarLongDate, calendarMonthLabel, calendarMonthNames, calendarParts, isAfter, isBefore, isSameCalendarMonth, isSameDay, isWithin, resolveCalendar, startOfCalendarMonth, startOfDay, weekdayNames } from "../../utils/date.js";
+import { Popover } from "../popover/index.js";
+import { addCalendarMonths, calendarDayNumber, calendarLongDate, calendarMonthLabel, calendarMonthNames, calendarParts, clampDate, isAfter, isBefore, isSameCalendarMonth, isSameDay, isWithin, localeWeekStart, monthGrid, normalizeWeekStart, resolveCalendar, startOfCalendarMonth, startOfDay, weekdayNames } from "../../utils/date.js";
 
 /** A range under construction: `to` is undefined between the two taps. */
 
@@ -49,15 +59,46 @@ import { addCalendarMonths, addDays, calendarDayNumber, calendarLongDate, calend
  * "no weekends" and "not in the past" are the two most common cases and
  * neither can be written as a list that stays right tomorrow.
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * 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: {
@@ -82,14 +123,15 @@ const dayVariants = tv({
         label: 'text-muted-foreground/30'
       }
     },
-    inRange: {
+    /** A ruled-out day inside a range still sits on it, but faintly. */
+    fadedBand: {
       true: {
-        band: 'bg-accent'
+        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,
@@ -108,10 +150,42 @@ function useCalendar(component) {
   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() {
+  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, disabled, minDate, maxDate) {
-  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));
@@ -131,8 +205,12 @@ function CalendarRoot({
   disabled,
   minDate,
   maxDate,
-  weekStartsOn = 0,
+  startMonth,
+  endMonth,
+  weekStartsOn: weekStartsOnProp = 0,
   showOutsideDays = true,
+  selectOutsideDays = false,
+  bordered = true,
   locale,
   calendar = 'gregory',
   ...props
@@ -140,6 +218,10 @@ function CalendarRoot({
   // 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(defaultSelected);
   const isControlled = selected !== undefined;
   const value = isControlled ? selected : internalSelected;
@@ -156,18 +238,57 @@ function CalendarRoot({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
   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 => {
-    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(next => {
     if (!isControlled) setInternalSelected(next);
     onSelect?.(next);
   }, [isControlled, onSelect]);
   const select = useCallback(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 ?? [];
       const without = current.filter(picked => !isSameDay(picked, day));
@@ -199,7 +320,7 @@ function CalendarRoot({
     // Single. Tapping the selected day again clears it.
     const current = value;
     commit(isSameDay(current, day) ? undefined : day);
-  }, [mode, value, commit]);
+  }, [mode, value, commit, month, system, locale, setMonth]);
   const context = useMemo(() => ({
     month,
     setMonth,
@@ -207,20 +328,28 @@ function CalendarRoot({
     system,
     minDate,
     maxDate,
+    startMonth,
+    endMonth,
     captionLayout
-  }), [month, setMonth, locale, system, minDate, maxDate, captionLayout]);
+  }), [month, setMonth, locale, system, minDate, maxDate, startMonth, endMonth, captionLayout]);
+  const {
+    root
+  } = calendarVariants({
+    bordered
+  });
+  const months = Math.max(1, numberOfMonths);
   return /*#__PURE__*/_jsx(CalendarContext.Provider, {
     value: context,
     children: /*#__PURE__*/_jsx(View, {
       ...props,
-      className: cn('gap-4', className),
+      className: cn(root(), className),
       children: Array.from({
-        length: Math.max(1, numberOfMonths)
+        length: months
       }, (_unused, offset) => /*#__PURE__*/_jsxs(View, {
         className: "gap-2",
-        children: [/*#__PURE__*/_jsx(CalendarCaption, {
+        children: [/*#__PURE__*/_jsx(CalendarHeader, {
           offset: offset,
-          lastOffset: numberOfMonths - 1
+          lastOffset: months - 1
         }), /*#__PURE__*/_jsx(CalendarGrid, {
           month: addCalendarMonths(month, offset, system, locale),
           mode: mode,
@@ -231,6 +360,7 @@ function CalendarRoot({
           maxDate: maxDate,
           weekStartsOn: weekStartsOn,
           showOutsideDays: showOutsideDays,
+          selectOutsideDays: selectOutsideDays,
           locale: locale,
           system: system
         })]
@@ -245,15 +375,20 @@ CalendarRoot.displayName = 'Calendar';
 /* -------------------------------------------------------------------------- */
 
 /**
- * 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
+function CalendarHeader({
+  offset = 0,
+  lastOffset = 0
 }) {
   const {
     month,
@@ -263,38 +398,56 @@ function CalendarCaption({
     minDate,
     maxDate,
     captionLayout
-  } = useCalendar('Calendar.Caption');
+  } = useCalendar('Calendar.Header');
+  const {
+    header,
+    caption
+  } = calendarVariants();
   const shown = addCalendarMonths(month, offset, system, locale);
   const canGoBack = !minDate || isBefore(startOfCalendarMonth(minDate, system, locale), month);
   const canGoForward = !maxDate || isAfter(startOfCalendarMonth(maxDate, system, locale), shown);
   return /*#__PURE__*/_jsxs(View, {
-    className: "h-9 flex-row items-center justify-between",
+    className: header(),
     children: [offset === 0 ? /*#__PURE__*/_jsx(CalendarNav, {
       direction: "previous",
       disabled: !canGoBack,
       onPress: () => setMonth(addCalendarMonths(month, -1, system, locale))
     }) : /*#__PURE__*/_jsx(View, {
-      className: "h-7 w-7"
-    }), captionLayout === 'dropdown' ? /*#__PURE__*/_jsx(CalendarDropdowns, {
-      month: shown,
-      offset: offset
-    }) : /*#__PURE__*/_jsx(Text, {
-      weight: "semibold",
-      children: calendarMonthLabel(shown, system, locale)
+      className: "h-8 w-8"
+    }), /*#__PURE__*/_jsx(View, {
+      className: caption(),
+      children: captionLayout === 'dropdown' ? /*#__PURE__*/_jsx(CalendarDropdowns, {
+        month: shown,
+        offset: offset
+      }) : /*#__PURE__*/_jsx(Text, {
+        weight: "semibold",
+        className: "text-base",
+        children: calendarMonthLabel(shown, system, locale)
+      })
     }), offset === lastOffset ? /*#__PURE__*/_jsx(CalendarNav, {
       direction: "next",
       disabled: !canGoForward,
       onPress: () => setMonth(addCalendarMonths(month, 1, system, locale))
     }) : /*#__PURE__*/_jsx(View, {
-      className: "h-7 w-7"
+      className: "h-8 w-8"
     })]
   });
 }
+/**
+ * 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,
+  disabled = false,
   onPress
 }) {
+  const {
+    nav
+  } = calendarVariants();
   return /*#__PURE__*/_jsx(Pressable, {
     disabled: disabled,
     onPress: onPress,
@@ -304,21 +457,26 @@ function CalendarNav({
     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'),
     children: direction === 'next' ? /*#__PURE__*/_jsx(ChevronRightIcon, {
-      size: 16
+      size: 18
     }) : /*#__PURE__*/_jsx(ChevronLeftIcon, {
-      size: 16
+      size: 18
     })
   });
 }
 
 /**
- * Month and year as two rows of chips rather than as native pickers.
+ * Month and year as chips that open a panel of options.
+ *
+ * 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.
  *
- * 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.
+ * 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,
@@ -329,9 +487,10 @@ function CalendarDropdowns({
     locale,
     system,
     minDate,
-    maxDate
+    maxDate,
+    startMonth,
+    endMonth
   } = useCalendar('Calendar.Caption');
-  const [open, setOpen] = useState(null);
 
   /*
    * Everything here counts in the calendar on screen, not in the platform's.
@@ -341,10 +500,49 @@ function CalendarDropdowns({
    */
   const months = useMemo(() => calendarMonthNames(month, system, locale, 'short'), [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);
@@ -356,58 +554,154 @@ function CalendarDropdowns({
    */
   const choose = months_ => {
     setMonth(addCalendarMonths(month, months_ - offset, system, locale));
-    setOpen(null);
   };
-  return /*#__PURE__*/_jsxs(View, {
-    className: "flex-1 items-center",
-    children: [/*#__PURE__*/_jsxs(View, {
-      className: "flex-row items-center gap-1",
-      children: [/*#__PURE__*/_jsx(CaptionChip, {
-        label: months[current.month - 1] ?? String(current.month),
-        expanded: open === 'month',
-        onPress: () => setOpen(open === 'month' ? null : 'month')
-      }), /*#__PURE__*/_jsx(CaptionChip, {
-        label: String(current.year),
-        expanded: open === 'year',
-        onPress: () => setOpen(open === 'year' ? null : 'year')
-      })]
-    }), open ? /*#__PURE__*/_jsx(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",
-      children: (open === 'month' ? months : years.map(String)).map((option, index) => {
-        const active = open === 'month' ? index === current.month - 1 : years[index] === current.year;
-        return /*#__PURE__*/_jsx(Pressable, {
-          onPress: () => choose(open === 'month' ? index - (current.month - 1) : (years[index] - current.year) * 12),
-          accessibilityRole: "button",
-          accessibilityState: {
-            selected: active
-          },
-          className: cn('rounded-md px-2.5 py-1.5', active ? 'bg-primary' : 'active:bg-accent'),
-          children: /*#__PURE__*/_jsx(Text, {
-            size: "sm",
-            className: active ? 'text-primary-foreground' : undefined,
-            children: option
-          })
-        }, option);
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(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)
+    }), /*#__PURE__*/_jsx(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
+}) {
+  const [open, setOpen] = useState(false);
+  const list = useRef(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]);
+  return /*#__PURE__*/_jsxs(Popover, {
+    open: open,
+    onOpenChange: setOpen,
+    children: [/*#__PURE__*/_jsx(Popover.Trigger, {
+      children: /*#__PURE__*/_jsx(CaptionChip, {
+        label: label,
+        expanded: open,
+        accessibilityLabel: accessibilityLabel
       })
-    }) : null]
+    }), /*#__PURE__*/_jsx(Popover.Content, {
+      align: "center",
+      width: width,
+      className: "p-1.5",
+      children: /*#__PURE__*/_jsx(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,
+        children: options.map((option, index) => {
+          const selected = index === active;
+          return /*#__PURE__*/_jsxs(Pressable, {
+            onPress: () => {
+              onSelect(index);
+              setOpen(false);
+            },
+            accessibilityRole: "button",
+            accessibilityState: {
+              selected
+            },
+            style: {
+              height: OPTION_HEIGHT
+            },
+            className: cn('flex-row items-center justify-between gap-2 rounded-xl px-3', selected ? 'bg-accent' : 'active:bg-accent'),
+            children: [/*#__PURE__*/_jsx(Text, {
+              size: "sm",
+              weight: selected ? 'semibold' : 'normal',
+              children: option
+            }), selected ? /*#__PURE__*/_jsx(CheckIcon, {
+              size: 16,
+              color: tick
+            }) : null]
+          }, option);
+        })
+      })
+    })]
   });
 }
 function CaptionChip({
   label,
   expanded,
+  accessibilityLabel,
   onPress
 }) {
-  return /*#__PURE__*/_jsx(Pressable, {
+  return /*#__PURE__*/_jsxs(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",
-    children: /*#__PURE__*/_jsx(Text, {
+    className: "flex-row items-center gap-1 rounded-lg px-2 py-1.5 active:bg-accent",
+    children: [/*#__PURE__*/_jsx(Text, {
       weight: "semibold",
       children: label
-    })
+    }), /*#__PURE__*/_jsx(ChevronDownIcon, {
+      size: 14
+    })]
   });
 }
 
@@ -425,6 +719,7 @@ function CalendarGrid({
   maxDate,
   weekStartsOn,
   showOutsideDays,
+  selectOutsideDays = false,
   locale,
   system
 }) {
@@ -434,18 +729,9 @@ 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 : undefined;
   const multiple = mode === 'multiple' ? value ?? [] : [];
   const single = mode === 'single' ? value : undefined;
@@ -475,22 +761,41 @@ function CalendarGrid({
               className: "h-10 flex-1"
             }, dayIndex);
           }
-          const selected = mode === 'range' ? isSameDay(date, range?.from) || isSameDay(date, range?.to) : mode === 'multiple' ? multiple.some(picked => isSameDay(picked, date)) : isSameDay(date, single);
+          const isStart = mode === 'range' && isSameDay(date, range?.from);
+          const isEnd = mode === 'range' && isSameDay(date, range?.to);
+          const selected = mode === 'range' ? isStart || isEnd : mode === 'multiple' ? multiple.some(picked => isSameDay(picked, date)) : isSameDay(date, single);
+
+          /*
+           * 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);
 
-          // Between the ends, but not an end itself — the band, not the disc.
-          const inRange = !!range?.to && isWithin(date, range.from, range.to) && !selected;
+          /*
+           * 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 /*#__PURE__*/_jsx(CalendarDay, {
             date: date,
             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)
@@ -505,6 +810,8 @@ function CalendarDay({
   outside,
   selected,
   inRange,
+  rangeStart = false,
+  rangeEnd = false,
   today,
   disabled,
   openStart,
@@ -518,8 +825,25 @@ 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%' : 0,
+    right: rangeEnd ? '50%' : 0,
+    borderTopLeftRadius: openStart ? 0 : DAY_RADIUS,
+    borderBottomLeftRadius: openStart ? 0 : DAY_RADIUS,
+    borderTopRightRadius: openEnd ? 0 : DAY_RADIUS,
+    borderBottomRightRadius: openEnd ? 0 : DAY_RADIUS
+  } : null;
   return /*#__PURE__*/_jsxs(Pressable, {
     disabled: disabled,
     onPress: onPress,
@@ -529,28 +853,22 @@ function CalendarDay({
       selected,
       disabled
     },
-    className: cn(styles.cell(), 'h-10'),
-    children: [inRange ? /*#__PURE__*/_jsx(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
-      }
+    className: styles.cell(),
+    children: [bandStyle ? /*#__PURE__*/_jsx(View, {
+      className: styles.band(),
+      style: bandStyle
     }) : null, /*#__PURE__*/_jsx(View, {
-      className: cn(styles.disc()),
+      className: styles.disc(),
       children: /*#__PURE__*/_jsx(Text, {
-        size: "sm",
-        className: cn(styles.label()),
+        className: styles.label(),
         children: calendarDayNumber(date, system, locale)
       })
     })]
   });
 }
 export const Calendar = Object.assign(CalendarRoot, {
+  Header: CalendarHeader,
+  Nav: CalendarNav,
   Grid: CalendarGrid,
   Day: CalendarDay
 });