panelui-native 0.80.0 → 0.82.0

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

@@ -58,7 +58,7 @@
  * are the whole content of the grid for somebody who cannot see it.
  */
 import { Children, createContext, forwardRef, isValidElement, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { AccessibilityInfo, AppState, Platform, Pressable, View } from 'react-native';
+import { AccessibilityInfo, AppState, FlatList, Platform, Pressable, View } from 'react-native';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { ChevronLeftIcon, ChevronRightIcon } from "../../icons/index.js";
@@ -70,16 +70,51 @@ import { Frame } from "../frame/index.js";
 import { bucketByDay, dayAccessibilityLabel, entriesOn, summariseMonth, visibleEntries } from "./planner-entries.js";
 import { usePlannerMonthAnnouncement } from "./planner-announcement.js";
 import { plannerGridTarget } from "./planner-grid-navigation.js";
+import { weekAnchor, weekDays, weekIndex, weekRange } from "./planner-weeks.js";
 import { usePlannerMonthLifecycle, usePlannerSelectionLifecycle } from "./planner-lifecycle.js";
 import { millisecondsUntilNextLocalDay } from "./planner-today.js";
 
-/** How many of a day's entries a cell draws before it stops and counts. */
+/**
+ * How many of a day's entries a cell draws before it stops and counts.
+ *
+ * `calendar` gets one more because a named entry is a row, and a cell tall
+ * enough to name one is tall enough for three; `tiles` draws a single icon at
+ * the size of the tile, so the limit there is the look rather than a number.
+ */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const DEFAULT_ENTRY_LIMIT = 2;
+const DEFAULT_ENTRY_LIMIT = {
+  default: 2,
+  tiles: 1,
+  calendar: 3
+};
 
 /** The palette a category takes its dot from when it does not name a colour. */
 const PALETTE_SIZE = 5;
 
+/**
+ * How strongly a `tiles` day takes its category's colour.
+ *
+ * Low enough that the date in the corner and the icon over it both stay
+ * legible, high enough that a brand colour arrives as that brand rather than as
+ * a grey tile with a suggestion of one.
+ */
+const TILE_TINT_OPACITY = 0.32;
+
+/**
+ * The height a `tiles` grid reserves, and what it is made of.
+ *
+ * Six weeks' worth, always — but only the weeks the month actually spans are
+ * drawn, and they share the reserved height out between them. A five-week
+ * month therefore has slightly taller tiles than a six-week one and no band of
+ * empty space under the last row, while the panel itself never changes size as
+ * you page through the year. Reserving the height and leaving the sixth row
+ * blank, or dropping the row and letting the panel shrink, each fix one of
+ * those at the cost of the other.
+ */
+const TILE_ROW_HEIGHT = 64;
+const TILE_ROW_GAP = 4;
+const TILE_GRID_HEIGHT = TILE_ROW_HEIGHT * 6 + TILE_ROW_GAP * 5;
+
 /** Stable wrapper keeps the native method's receiver and the hook dependency steady. */
 const announceMonth = label => {
   AccessibilityInfo.announceForAccessibility(label);
@@ -91,6 +126,19 @@ const plannerVariants = tv({
     heading: 'flex-1 text-center',
     legend: 'flex-row flex-wrap items-center gap-x-4 gap-y-2 px-4 py-3',
     swatch: 'h-2 w-2 rounded-full'
+  },
+  variants: {
+    /*
+     * The weeks share out the height instead of standing at their own. The
+     * weekday row keeps its natural height — it is a label, and stretching it
+     * only moves the letters away from the column they name.
+     */
+    fill: {
+      true: {
+        grid: 'flex-1',
+        week: 'flex-1'
+      }
+    }
   }
 });
 const dayVariants = tv({
@@ -114,9 +162,32 @@ const dayVariants = tv({
     cell: 'mx-0.5 h-14 flex-1 rounded-xl border border-transparent px-1.5 pt-1.5',
     number: 'text-xs leading-none',
     marker: 'absolute right-1.5 top-1.5 h-1.5 w-1.5 rounded-full',
-    body: 'flex-1 flex-row items-center justify-center gap-0.5 pb-1'
+    body: 'flex-1 flex-row items-center justify-center gap-0.5 pb-1',
+    /** The colour a day's entries give it, drawn under everything else. */
+    tint: 'absolute inset-0 rounded-xl',
+    /*
+     * The corners of a tile. These are Views rather than classes on the Text
+     * itself: a Text takes its typography from a class but not its position,
+     * so a number told to sit in a corner stayed where the layout put it —
+     * dead centre, under the icon.
+     */
+    corner: 'absolute bottom-1 right-1.5',
+    counter: 'absolute left-1.5 top-1',
+    /** One entry, named, in a cell with the height to name it. */
+    chip: 'w-full overflow-hidden rounded-sm bg-muted px-1 py-0.5',
+    overflow: 'leading-none'
   },
   variants: {
+    /*
+     * Cells stretch to their container rather than standing at a fixed height.
+     * The grid is still six weeks, so what changes is how tall a week is, not
+     * how many there are.
+     */
+    fill: {
+      true: {
+        cell: 'h-auto min-h-0 flex-1'
+      }
+    },
     /** Inside the month being shown, as opposed to the days either side. */
     inMonth: {
       true: {
@@ -148,6 +219,38 @@ const dayVariants = tv({
       true: {
         cell: 'opacity-40'
       }
+    },
+    /*
+     * What a cell draws. One axis, because these are three answers to the same
+     * question and a cell can only give one of them.
+     *
+     * Last, so a look can undo what the states above it set. `calendar` has no
+     * tile to ring or fill, so it has to be able to take the background and the
+     * border back off a cell that today or the open day just gave one to.
+     */
+    variant: {
+      default: {},
+      /*
+       * A tile per day, carrying the one thing on it at the size of a mark
+       * rather than a marker. The date moves out of the way into the corner:
+       * it is how you find the day you want, not what the cell is showing.
+       */
+      tiles: {
+        cell: 'h-full items-center justify-center px-0 pt-0',
+        overflow: 'leading-none'
+      },
+      /*
+       * Named entries stacked down an open cell. No tile, because a tile per
+       * day and a block per entry are two boxes saying the same thing and the
+       * entries are the ones carrying words — the weeks are ruled off instead,
+       * which separates them without enclosing anything.
+       */
+      calendar: {
+        cell: 'mx-0 h-full min-h-0 items-stretch gap-px rounded-none border-transparent bg-transparent px-1 pb-1 pt-1.5',
+        number: 'text-center',
+        body: 'flex-col items-stretch justify-start gap-px pb-0',
+        overflow: 'text-center leading-none'
+      }
     }
   },
   compoundVariants: [
@@ -164,7 +267,8 @@ const dayVariants = tv({
     }
   }],
   defaultVariants: {
-    inMonth: true
+    inMonth: true,
+    variant: 'default'
   }
 });
 
@@ -172,6 +276,15 @@ const dayVariants = tv({
  * Data
  * ------------------------------------------------------------------ */
 
+/**
+ * What a day cell draws.
+ *
+ * `default` is a number, a marker and small icons. `tiles` gives the day over
+ * to one large icon tinted with its category's colour, with the date in the
+ * corner. `calendar` names each entry in a block under a centred date, on an
+ * open grid ruled off by week.
+ */
+
 /** One thing that falls on a day. */
 
 /** A group of entries: the key to a colour, and a line in the legend. */
@@ -246,7 +359,9 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
   defaultSelected = null,
   onSelectedChange,
   onDayPress,
-  entryLimit = DEFAULT_ENTRY_LIMIT,
+  variant = 'default',
+  fill = false,
+  entryLimit,
   weekStartsOn = 'auto',
   locale,
   calendar = 'gregory',
@@ -254,6 +369,7 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
   children,
   ...props
 }, ref) => {
+  const resolvedEntryLimit = entryLimit ?? DEFAULT_ENTRY_LIMIT[variant];
   const system = resolveCalendar(calendar, locale);
   const palette = usePalette();
   const today = useToday();
@@ -276,6 +392,15 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
     monthLabel: calendarMonthLabel(month, system, locale),
     announce: announceMonth
   });
+  /*
+   * Scrolling changes the month continuously, and announcing each one as it
+   * goes would talk over somebody reading the weeks. The announcement belongs
+   * to a deliberate move — the arrows, the Today pill — so a scroll reports
+   * the change and stays quiet about it.
+   */
+  const syncMonth = useCallback(next => {
+    requestMonth(next);
+  }, [requestMonth]);
   const setMonth = useCallback(next => {
     expectMonthAnnouncement(settleMonth(next));
     requestMonth(next);
@@ -305,6 +430,7 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
   const context = useMemo(() => ({
     month,
     setMonth,
+    syncMonth,
     today,
     selected,
     select,
@@ -313,14 +439,16 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
     categoryLabels,
     colorOf,
     summary,
-    entryLimit,
+    entryLimit: resolvedEntryLimit,
+    variant,
+    fill,
     weekStartsOn: normalizedWeekStart,
     grid,
     locale,
     system,
     isInMonth,
     onDayPress
-  }), [month, setMonth, today, selected, select, days, categories, categoryLabels, colorOf, summary, entryLimit, normalizedWeekStart, grid, locale, system, isInMonth, onDayPress]);
+  }), [month, setMonth, syncMonth, today, selected, select, days, categories, categoryLabels, colorOf, summary, resolvedEntryLimit, variant, fill, normalizedWeekStart, grid, locale, system, isInMonth, onDayPress]);
 
   /*
    * The header belongs in the Frame's strip and everything else in its
@@ -336,18 +464,20 @@ const PlannerRoot = /*#__PURE__*/forwardRef(({
     /*#__PURE__*/
     // Full width by default: the grid is seven equal columns, and a
     // container that sizes to its content collapses them to the width of
-    // a two-digit number.
+    // a two-digit number. Under `fill` the panel has to flex too, or the
+    // grid inside it stretches against a container that does not.
     _jsxs(Frame, {
       ref: ref,
-      className: cn('w-full', className),
+      className: cn('w-full', fill && 'flex-1', className),
       ...props,
       children: [header, /*#__PURE__*/_jsx(Frame.Panel, {
         dividers: false,
+        className: fill ? 'flex-1' : undefined,
         children: body
       })]
     }) : /*#__PURE__*/_jsxs(View, {
       ref: ref,
-      className: cn('w-full', className),
+      className: cn('w-full', fill && 'flex-1', className),
       ...props,
       children: [header, body]
     })
@@ -377,10 +507,10 @@ function PlannerHeader({
   const lead = parts.filter(child => !trails(child));
   return /*#__PURE__*/_jsxs(Frame.Header, {
     children: [/*#__PURE__*/_jsx(View, {
-      className: "min-w-0 flex-1 flex-row items-center gap-2",
+      className: "min-w-0 shrink flex-row items-center gap-2",
       children: lead
     }), trailing.length > 0 ? /*#__PURE__*/_jsx(View, {
-      className: "shrink-0 flex-row items-center gap-1.5",
+      className: "ml-auto shrink-0 flex-row items-center gap-1.5",
       children: trailing
     }) : null]
   });
@@ -510,16 +640,35 @@ function PlannerGrid({
     locale,
     selected,
     today,
-    isInMonth
+    isInMonth,
+    variant,
+    fill
   } = usePlanner('Planner.Grid');
   const {
     grid,
     week: weekRow,
     heading
-  } = plannerVariants();
-  const headings = useMemo(() => weekdayNames(locale, weekStartsOn), [locale, weekStartsOn]);
-  const dates = useMemo(() => weeks.flat(), [weeks]);
+  } = plannerVariants({
+    fill
+  });
+  /*
+   * `tiles` leaves the days either side of the month blank, so its columns are
+   * told apart by position alone and a single letter is enough to head them.
+   */
+  const headings = useMemo(() => weekdayNames(locale, weekStartsOn, variant === 'tiles' ? 'narrow' : 'short'), [locale, weekStartsOn, variant]);
+  /*
+   * `tiles` draws nothing for the days either side of the month, so a week made
+   * only of those is a band of empty space rather than a week. It is dropped,
+   * and the grid keeps its height by letting the weeks that remain stretch.
+   */
+  const shownWeeks = useMemo(() => variant === 'tiles' ? weeks.filter(week => week.some(isInMonth)) : weeks, [weeks, variant, isInMonth]);
+  const dates = useMemo(() => shownWeeks.flat(), [shownWeeks]);
   const indexByDay = useMemo(() => new Map(dates.map((date, index) => [date.getTime(), index])), [dates]);
+  /*
+   * A blank cell has nothing to focus, so arrow keys step over it rather than
+   * landing on a day that is not drawn and losing focus altogether.
+   */
+  const navigable = useMemo(() => variant === 'tiles' ? index => isInMonth(dates[index] ?? today) : undefined, [variant, dates, isInMonth, today]);
   const initialDay = selected ?? today;
   const [activeDay, setActiveDay] = useState(initialDay.getTime());
   const storedIndex = indexByDay.get(activeDay);
@@ -534,12 +683,12 @@ function PlannerGrid({
     if (date) setActiveDay(date.getTime());
   }, [dates]);
   const focus = useCallback((index, event) => {
-    const target = plannerGridTarget(event.nativeEvent.key ?? '', index, dates.length);
+    const target = plannerGridTarget(event.nativeEvent.key ?? '', index, dates.length, 7, navigable);
     if (target === null) return;
     event.preventDefault();
     makeActive(target);
     refs.current.get(target)?.focus();
-  }, [dates.length, makeActive]);
+  }, [dates.length, makeActive, navigable]);
   const navigation = useMemo(() => ({
     activeIndex,
     indexByDay,
@@ -553,18 +702,21 @@ function PlannerGrid({
       className: grid({
         className
       }),
+      style: variant === 'tiles' && !fill ? {
+        height: TILE_GRID_HEIGHT
+      } : undefined,
       children: [/*#__PURE__*/_jsx(View, {
         className: weekRow(),
         accessibilityElementsHidden: true,
         importantForAccessibility: "no-hide-descendants",
-        children: headings.map(label => /*#__PURE__*/_jsx(Text, {
+        children: headings.map((label, position) => /*#__PURE__*/_jsx(Text, {
           size: "xs",
           muted: true,
           className: heading(),
           children: label.toUpperCase()
-        }, label))
-      }), weeks.map((week, index) => /*#__PURE__*/_jsx(View, {
-        className: weekRow(),
+        }, position))
+      }), shownWeeks.map((week, index) => /*#__PURE__*/_jsx(View, {
+        className: cn(weekRow(), variant === 'tiles' && 'flex-1'),
         children: week.map(date => /*#__PURE__*/_jsx(PlannerDay, {
           date: date,
           renderDay: renderDay
@@ -587,6 +739,8 @@ function PlannerDay({
     colorOf,
     categoryLabels,
     entryLimit,
+    variant,
+    fill,
     locale,
     system,
     isInMonth,
@@ -606,14 +760,30 @@ function PlannerDay({
   } = visibleEntries(entries, entryLimit);
   const drawable = shown.filter(entry => entry.icon);
   const styles = dayVariants({
+    variant,
+    fill,
     inMonth,
     today: isToday,
     selected: isSelected
   });
+  /*
+   * The colour the day's entries give it. The first entry naming a category the
+   * planner knows wins, and an uncategorised day gets nothing — the tint is a
+   * signal about what is on the day, so a day with no answer stays plain rather
+   * than being coloured for the sake of it.
+   */
+  const tint = markerColor(entries, colorOf);
   const label = dayAccessibilityLabel(calendarLongDate(date, system, locale), entries, categoryLabels);
+
+  /*
+   * Pressing the open day again closes it. Without this the mark is a one-way
+   * door: a planner with no `Details` bound has nothing to dismiss, so the day
+   * you pressed stays ringed until you press a different one and there is no
+   * way back to none selected.
+   */
   const press = () => {
     onDayPress?.(date, entries);
-    select(date);
+    select(isSelected ? null : date);
   };
   const gridIndex = navigation?.indexByDay.get(date.getTime());
   const setRef = useCallback(node => {
@@ -643,6 +813,21 @@ function PlannerDay({
       })
     });
   }
+
+  /*
+   * `tiles` leaves the days either side of the month out altogether. The row
+   * still holds their column, so the grid is six weeks whatever month it is
+   * showing, but there is no tile, no number and nothing to press or to read
+   * out: a blank is the answer, and drawing a faded one only invites the press
+   * it is going to ignore.
+   */
+  if (variant === 'tiles' && !inMonth) {
+    return /*#__PURE__*/_jsx(View, {
+      className: cn('mx-0.5 flex-1', fill ? 'min-h-0' : 'h-16'),
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants"
+    });
+  }
   return /*#__PURE__*/_jsxs(Pressable, {
     ...webGridProps,
     onPress: press,
@@ -653,28 +838,111 @@ function PlannerDay({
       selected: isSelected
     },
     className: styles.cell(),
-    children: [/*#__PURE__*/_jsx(Text, {
+    children: [variant === 'tiles' && tint ? /*#__PURE__*/_jsx(View, {
+      pointerEvents: "none",
+      className: styles.tint(),
+      style: {
+        backgroundColor: tint,
+        opacity: TILE_TINT_OPACITY
+      }
+    }) : null, variant === 'tiles' ? /*#__PURE__*/_jsx(View, {
+      className: styles.corner(),
+      pointerEvents: "none",
+      children: /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        className: styles.number(),
+        children: calendarDayNumber(date, system, locale)
+      })
+    }) : variant === 'calendar' ?
+    /*#__PURE__*/
+    /*
+     * A disc around the date rather than a ring around the cell. There is
+     * no tile here to ring, and the date is the only thing in the cell that
+     * is always present — so it is the only place a mark can go and be
+     * found in the same spot on every day of the month.
+     */
+    _jsx(View, {
+      className: cn('h-6 w-6 items-center justify-center self-center rounded-full', isToday && 'bg-primary'),
+      children: /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        className: cn(styles.number(), isToday && 'text-primary-foreground'),
+        children: calendarDayNumber(date, system, locale)
+      })
+    }) : /*#__PURE__*/_jsx(Text, {
       className: styles.number(),
       children: calendarDayNumber(date, system, locale)
-    }), entries.length > 0 ? /*#__PURE__*/_jsx(View, {
+    }), variant === 'default' && entries.length > 0 ? /*#__PURE__*/_jsx(View, {
       className: styles.marker(),
       style: {
-        backgroundColor: markerColor(entries, colorOf)
+        backgroundColor: tint
       }
-    }) : null, drawable.length > 0 ? /*#__PURE__*/_jsxs(View, {
+    }) : null, variant === 'calendar' ? /*#__PURE__*/_jsxs(View, {
+      className: styles.body(),
+      children: [shown.map(entry => /*#__PURE__*/_jsx(PlannerChip, {
+        entry: entry,
+        color: entry.color ?? colorOf(entry.category)
+      }, entry.id)), overflow > 0 ? /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        className: styles.overflow(),
+        numberOfLines: 1,
+        children: "\u2022\u2022\u2022"
+      }) : null]
+    }) : null, variant === 'tiles' && overflow > 0 ? /*#__PURE__*/_jsx(View, {
+      className: styles.counter(),
+      pointerEvents: "none",
+      children: /*#__PURE__*/_jsxs(Text, {
+        size: "xs",
+        muted: true,
+        className: styles.overflow(),
+        children: ["+", overflow]
+      })
+    }) : null, variant !== 'calendar' && drawable.length > 0 ? /*#__PURE__*/_jsxs(View, {
       className: styles.body(),
       children: [drawable.map(entry => /*#__PURE__*/_jsx(View, {
         children: entry.icon
-      }, entry.id)), overflow > 0 ? /*#__PURE__*/_jsxs(Text, {
+      }, entry.id)), variant !== 'tiles' && overflow > 0 ? /*#__PURE__*/_jsxs(Text, {
         size: "xs",
         muted: true,
-        className: "leading-none",
+        className: styles.overflow(),
         children: ["+", overflow]
       }) : null]
     }) : null]
   });
 }
-PlannerDay.displayName = 'Planner.Day';
+
+/**
+ * One named entry inside a `calendar` cell.
+ *
+ * A solid block of the entry's colour with light text on it. That is a real
+ * constraint rather than a free choice: the colour is the caller's, so a pale
+ * one will not carry white well — but a wash with the label in the foreground
+ * colour makes every entry the same weight and loses the one thing the colour
+ * was for, which is telling them apart down a column at a glance.
+ */
+function PlannerChip({
+  entry,
+  color
+}) {
+  const {
+    chip
+  } = dayVariants();
+  return /*#__PURE__*/_jsx(View, {
+    className: chip(),
+    style: color ? {
+      backgroundColor: color
+    } : undefined,
+    children: /*#__PURE__*/_jsx(Text, {
+      size: "xs",
+      numberOfLines: 1,
+      className: cn('leading-none', !color && 'text-foreground'),
+      style: color ? {
+        color: '#ffffff'
+      } : undefined,
+      children: entry.label
+    })
+  });
+}
 
 /**
  * The dot's colour: the first entry that names a category the planner knows.
@@ -685,7 +953,9 @@ PlannerDay.displayName = 'Planner.Day';
  */
 function markerColor(entries, colorOf) {
   for (const entry of entries) {
-    const color = colorOf(entry.category);
+    // The entry's own colour first: a brand belongs to the thing, not to the
+    // group it was filed under.
+    const color = entry.color ?? colorOf(entry.category);
     if (color) return color;
   }
   return undefined;
@@ -807,6 +1077,149 @@ function PlannerDetails({
   });
 }
 PlannerDetails.displayName = 'Planner.Details';
+
+/* ------------------------------------------------------------------ *
+ * Scroller
+ * ------------------------------------------------------------------ */
+
+/** How many weeks either side of the opening month a scroller reaches by default. */
+const DEFAULT_SCROLLER_WEEKS = 53;
+
+/** The height of one week row, and enough of it for a date and three entries. */
+const DEFAULT_WEEK_HEIGHT = 96;
+/**
+ * The weeks of the year, scrolled through rather than paged.
+ *
+ * A month grid answers "what does this month look like"; a scroller answers
+ * "what is coming", which does not stop at the end of a month. The week
+ * straddling the boundary is drawn once, in one piece, instead of appearing cut
+ * in half at the bottom of one page and again at the top of the next.
+ *
+ * The range is bounded rather than endless. A scroller has to know its own
+ * height to place a scrollbar and to jump to a month without rendering its way
+ * there, and neither is possible over a list with no end.
+ *
+ * The month in the header follows the scroll: whichever month holds most of the
+ * first week on screen is the one named, and the days either side of it grey
+ * out. `Planner.Nav` and `Planner.Today` still work — they scroll the list
+ * rather than replacing what is in it.
+ */
+function PlannerScroller({
+  className,
+  weeks: span = DEFAULT_SCROLLER_WEEKS,
+  rowHeight = DEFAULT_WEEK_HEIGHT,
+  renderDay
+}) {
+  const {
+    month,
+    syncMonth,
+    weekStartsOn,
+    locale,
+    variant,
+    system
+  } = usePlanner('Planner.Scroller');
+  const {
+    week: weekRow,
+    heading
+  } = plannerVariants();
+  const list = useRef(null);
+
+  /*
+   * The range is anchored where the planner opened and never rebuilt. Rebuilding
+   * it around the current month would move every row's index under the scroll
+   * position each time the month changed, which is the one thing a list being
+   * scrolled must not do.
+   */
+  const [anchor] = useState(() => month);
+  const range = useMemo(() => weekRange(anchor, weekStartsOn, span, span), [anchor, weekStartsOn, span]);
+  const headings = useMemo(() => weekdayNames(locale, weekStartsOn, 'narrow'), [locale, weekStartsOn]);
+
+  /*
+   * Which month the scroll is showing, reported up but not acted on here. The
+   * ref is what stops a scroll that stays inside one month from setting it over
+   * and over, and what stops the scroll this component performs in answer to a
+   * month change from reporting that same month straight back.
+   */
+  const reported = useRef(month.getTime());
+  const onViewable = useRef(({
+    viewableItems
+  }) => {
+    const first = viewableItems[0]?.item;
+    if (!first) return;
+    const next = startOfCalendarMonth(weekAnchor(first), system, locale);
+    if (next.getTime() === reported.current) return;
+    reported.current = next.getTime();
+    syncMonth(next);
+  });
+
+  /*
+   * A month arriving from outside — the arrows, the Today pill, a controlled
+   * prop — scrolls the list to it. A month the scroll itself just reported is
+   * already there, and scrolling to it again would fight the finger.
+   */
+  useEffect(() => {
+    if (month.getTime() === reported.current) return;
+    reported.current = month.getTime();
+    const index = weekIndex(range, month, weekStartsOn);
+    if (index >= 0) list.current?.scrollToIndex({
+      index,
+      animated: true
+    });
+  }, [month, range, weekStartsOn]);
+  const initialIndex = Math.max(0, weekIndex(range, month, weekStartsOn));
+  return /*#__PURE__*/_jsxs(View, {
+    className: cn('flex-1', className),
+    children: [/*#__PURE__*/_jsx(View, {
+      className: cn(weekRow(), 'px-1 pb-1'),
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants",
+      children: headings.map((label, position) => /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        className: heading(),
+        children: label.toUpperCase()
+      }, position))
+    }), /*#__PURE__*/_jsx(FlatList, {
+      ref: list,
+      data: range,
+      keyExtractor: weekStart => String(weekStart.getTime()),
+      initialScrollIndex: initialIndex
+      // Every row is the same height, so the list can place any of them
+      // without measuring — which is what makes jumping to a month cheap.
+      ,
+      getItemLayout: (_unused, index) => ({
+        length: rowHeight,
+        offset: rowHeight * index,
+        index
+      }),
+      onViewableItemsChanged: onViewable.current,
+      viewabilityConfig: VIEWABILITY,
+      showsVerticalScrollIndicator: false,
+      renderItem: ({
+        item
+      }) => /*#__PURE__*/_jsx(View, {
+        className: cn(weekRow(), 'border-t border-border px-1', variant === 'calendar' && 'items-stretch'),
+        style: {
+          height: rowHeight
+        },
+        children: weekDays(item).map(date => /*#__PURE__*/_jsx(PlannerDay, {
+          date: date,
+          renderDay: renderDay
+        }, date.getTime()))
+      })
+    })]
+  });
+}
+PlannerScroller.displayName = 'Planner.Scroller';
+
+/*
+ * The first row more than half on screen is the one that names the month. A
+ * lower threshold hands the month over while the week is still mostly below the
+ * fold, which reads as the header changing early.
+ */
+const VIEWABILITY = {
+  itemVisiblePercentThreshold: 60
+};
 export const Planner = Object.assign(PlannerRoot, {
   Header: PlannerHeader,
   Title: PlannerTitle,
@@ -814,6 +1227,7 @@ export const Planner = Object.assign(PlannerRoot, {
   Nav: PlannerNav,
   Action: PlannerAction,
   Grid: PlannerGrid,
+  Scroller: PlannerScroller,
   Day: PlannerDay,
   Legend: PlannerLegend,
   Summary: PlannerSummary,