panelui-native 0.80.0 → 0.82.0

package/src/components/planner/index.tsx

@@ -72,9 +72,11 @@ import {
 import {
   AccessibilityInfo,
   AppState,
+  FlatList,
   Platform,
   Pressable,
   View,
+  type ViewToken,
   type ViewProps,
 } from 'react-native';
 import { tv } from 'tailwind-variants';
@@ -111,18 +113,53 @@ import {
 } from './planner-entries';
 import { usePlannerMonthAnnouncement } from './planner-announcement';
 import { plannerGridTarget } from './planner-grid-navigation';
+import { weekAnchor, weekDays, weekIndex, weekRange } from './planner-weeks';
 import {
   usePlannerMonthLifecycle,
   usePlannerSelectionLifecycle,
 } from './planner-lifecycle';
 import { millisecondsUntilNextLocalDay } from './planner-today';
 
-/** How many of a day's entries a cell draws before it stops and counts. */
-const DEFAULT_ENTRY_LIMIT = 2;
+/**
+ * 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.
+ */
+const DEFAULT_ENTRY_LIMIT: Record<PlannerVariant, number> = {
+  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: string) => {
   AccessibilityInfo.announceForAccessibility(label);
@@ -136,6 +173,14 @@ const plannerVariants = tv({
     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({
@@ -160,8 +205,27 @@ const dayVariants = tv({
     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',
+    /** 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: { cell: 'bg-muted/40', number: 'text-foreground' },
@@ -175,6 +239,38 @@ const dayVariants = tv({
     today: { true: { cell: 'border-foreground', number: 'font-semibold' } },
     selected: { true: { cell: 'border-primary/60 bg-primary/10' } },
     disabled: { 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: [
     /*
@@ -184,13 +280,23 @@ const dayVariants = tv({
      */
     { today: true, selected: true, class: { cell: 'border-foreground bg-primary/10' } },
   ],
-  defaultVariants: { inMonth: true },
+  defaultVariants: { inMonth: true, variant: 'default' },
 });
 
 /* ------------------------------------------------------------------ *
  * 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.
+ */
+export type PlannerVariant = 'default' | 'tiles' | 'calendar';
+
 /** One thing that falls on a day. */
 export interface PlannerEntry {
   /** Stable across renders; it keys the cell's contents. */
@@ -203,6 +309,12 @@ export interface PlannerEntry {
   category?: string;
   /** Drawn in the cell — a brand mark, an avatar, a glyph. */
   icon?: ReactNode;
+  /**
+   * This entry's own colour, for a mark that belongs to the entry rather than
+   * to a group of them — a brand. It wins over the category's colour, and
+   * under `tiles` it is what tints the day.
+   */
+  color?: string;
 }
 
 /** A group of entries: the key to a colour, and a line in the legend. */
@@ -222,6 +334,8 @@ export interface PlannerCategory {
 interface PlannerContextValue {
   month: Date;
   setMonth: (month: Date) => void;
+  /** Moves the month without announcing it. For scrolling, which is continuous. */
+  syncMonth: (month: Date) => void;
   today: Date;
   selected: Date | null;
   select: (date: Date | null) => void;
@@ -231,6 +345,8 @@ interface PlannerContextValue {
   colorOf: (category: string | undefined) => string | undefined;
   summary: { total: number; categories: PlannerCountedCategory[] };
   entryLimit: number;
+  variant: PlannerVariant;
+  fill: boolean;
   weekStartsOn: number;
   grid: Date[][];
   locale: DateLocale;
@@ -325,7 +441,22 @@ export interface PlannerProps extends Omit<ViewProps, 'children'> {
   onSelectedChange?: (date: Date | null) => void;
   /** Runs before the selection moves, whether or not `Details` is present. */
   onDayPress?: (date: Date, entries: PlannerEntry[]) => void;
-  /** How many entries a cell draws before it counts the rest. Default `2`. */
+  /**
+   * What each day draws. `tiles` is one large icon per day, tinted by its
+   * category; `calendar` names every entry and needs the height to do it.
+   */
+  variant?: PlannerVariant;
+  /**
+   * Stretch the grid to its container instead of standing at its own height.
+   * For a planner that owns a screen — the six weeks share out whatever is
+   * left after the header, the legend and anything below them.
+   */
+  fill?: boolean;
+  /**
+   * How many entries a cell draws before it counts the rest. Default `2`, or
+   * `3` under `calendar`, which has the room; `tiles` draws one whatever you
+   * pass.
+   */
   entryLimit?: number;
   /** First day of the week, 0 is Sunday. Defaults to the locale's. */
   weekStartsOn?: number | 'auto';
@@ -349,7 +480,9 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
       defaultSelected = null,
       onSelectedChange,
       onDayPress,
-      entryLimit = DEFAULT_ENTRY_LIMIT,
+      variant = 'default',
+      fill = false,
+      entryLimit,
       weekStartsOn = 'auto',
       locale,
       calendar = 'gregory',
@@ -359,6 +492,7 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
     },
     ref
   ) => {
+    const resolvedEntryLimit = entryLimit ?? DEFAULT_ENTRY_LIMIT[variant];
     const system = resolveCalendar(calendar, locale);
     const palette = usePalette();
     const today = useToday();
@@ -385,6 +519,18 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
       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: Date) => {
+        requestMonth(next);
+      },
+      [requestMonth]
+    );
     const setMonth = useCallback(
       (next: Date) => {
         expectMonthAnnouncement(settleMonth(next));
@@ -449,6 +595,7 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
       () => ({
         month,
         setMonth,
+        syncMonth,
         today,
         selected,
         select,
@@ -457,7 +604,9 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
         categoryLabels,
         colorOf,
         summary,
-        entryLimit,
+        entryLimit: resolvedEntryLimit,
+        variant,
+        fill,
         weekStartsOn: normalizedWeekStart,
         grid,
         locale,
@@ -466,9 +615,9 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
         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,
       ]
     );
 
@@ -488,13 +637,16 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
         {frame ? (
           // 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.
-          <Frame ref={ref} className={cn('w-full', className)} {...props}>
+          // a two-digit number. Under `fill` the panel has to flex too, or the
+          // grid inside it stretches against a container that does not.
+          <Frame ref={ref} className={cn('w-full', fill && 'flex-1', className)} {...props}>
             {header}
-            <Frame.Panel dividers={false}>{body}</Frame.Panel>
+            <Frame.Panel dividers={false} className={fill ? 'flex-1' : undefined}>
+              {body}
+            </Frame.Panel>
           </Frame>
         ) : (
-          <View ref={ref} className={cn('w-full', className)} {...props}>
+          <View ref={ref} className={cn('w-full', fill && 'flex-1', className)} {...props}>
             {header}
             {body}
           </View>
@@ -532,9 +684,15 @@ function PlannerHeader({ children }: PlannerHeaderProps) {
 
   return (
     <Frame.Header>
-      <View className="min-w-0 flex-1 flex-row items-center gap-2">{lead}</View>
+      <View className="min-w-0 shrink flex-row items-center gap-2">{lead}</View>
+      {/*
+        `ml-auto` rather than a flexible lead. The nav belongs against the right
+        edge whatever is to its left — one short title, a title and a pill, or
+        nothing at all — and pushing it there with a margin says that directly
+        instead of leaving it to whether the thing beside it happened to grow.
+      */}
       {trailing.length > 0 ? (
-        <View className="shrink-0 flex-row items-center gap-1.5">{trailing}</View>
+        <View className="ml-auto shrink-0 flex-row items-center gap-1.5">{trailing}</View>
       ) : null}
     </Frame.Header>
   );
@@ -686,18 +844,40 @@ const PlannerGridNavigationContext = createContext<PlannerGridNavigationContextV
  * weekday headings are hidden rather than read out 42 times over.
  */
 function PlannerGrid({ className, renderDay }: PlannerGridProps) {
-  const { grid: weeks, weekStartsOn, locale, selected, today, isInMonth } =
+  const { grid: weeks, weekStartsOn, locale, selected, today, isInMonth, variant, fill } =
     usePlanner('Planner.Grid');
-  const { grid, week: weekRow, heading } = plannerVariants();
+  const { grid, week: weekRow, heading } = 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),
-    [locale, weekStartsOn]
+    () => 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(() => weeks.flat(), [weeks]);
+  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: number) => isInMonth(dates[index] ?? today) : undefined,
+    [variant, dates, isInMonth, today]
+  );
   const initialDay = selected ?? today;
   const [activeDay, setActiveDay] = useState(initialDay.getTime());
   const storedIndex = indexByDay.get(activeDay);
@@ -720,13 +900,19 @@ function PlannerGrid({ className, renderDay }: PlannerGridProps) {
   );
   const focus = useCallback(
     (index: number, event: PlannerGridKeyDownEvent) => {
-      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<PlannerGridNavigationContextValue>(
     () => ({ activeIndex, indexByDay, register, focus, makeActive }),
@@ -735,21 +921,29 @@ function PlannerGrid({ className, renderDay }: PlannerGridProps) {
 
   return (
     <PlannerGridNavigationContext.Provider value={renderDay ? null : navigation}>
-      <View className={grid({ className })}>
+      <View
+        className={grid({ className })}
+        style={variant === 'tiles' && !fill ? { height: TILE_GRID_HEIGHT } : undefined}
+      >
         <View
           className={weekRow()}
           accessibilityElementsHidden
           importantForAccessibility="no-hide-descendants"
         >
-          {headings.map((label) => (
-            <Text key={label} size="xs" muted className={heading()}>
+          {/*
+            Keyed by position rather than by the word: narrow names repeat in
+            plenty of locales — English has T twice and S twice — and a column
+            is identified by where it is, not by the letter over it.
+          */}
+          {headings.map((label, position) => (
+            <Text key={position} size="xs" muted className={heading()}>
               {label.toUpperCase()}
             </Text>
           ))}
         </View>
 
-        {weeks.map((week, index) => (
-          <View key={index} className={weekRow()}>
+        {shownWeeks.map((week, index) => (
+          <View key={index} className={cn(weekRow(), variant === 'tiles' && 'flex-1')}>
             {week.map((date) => (
               <PlannerDay key={date.getTime()} date={date} renderDay={renderDay} />
             ))}
@@ -770,7 +964,7 @@ export interface PlannerDayProps {
 function PlannerDay({ date, renderDay }: PlannerDayProps) {
   const {
     days, today, selected, select, colorOf, categoryLabels,
-    entryLimit, locale, system, isInMonth, onDayPress,
+    entryLimit, variant, fill, locale, system, isInMonth, onDayPress,
   } = usePlanner('Planner.Day');
   const navigation = useContext(PlannerGridNavigationContext);
   const registerGridCell = navigation?.register;
@@ -783,7 +977,14 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
   const isSelected = selected ? isSameDay(date, selected) : false;
   const { shown, overflow } = visibleEntries(entries, entryLimit);
   const drawable = shown.filter((entry) => entry.icon);
-  const styles = dayVariants({ inMonth, today: isToday, selected: isSelected });
+  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),
@@ -791,9 +992,15 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
     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(
@@ -829,6 +1036,23 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
     );
   }
 
+  /*
+   * `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 (
+      <View
+        className={cn('mx-0.5 flex-1', fill ? 'min-h-0' : 'h-16')}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      />
+    );
+  }
+
   return (
     <Pressable
       {...(webGridProps as ViewProps)}
@@ -839,10 +1063,75 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
       accessibilityState={{ selected: isSelected }}
       className={styles.cell()}
     >
-      <Text className={styles.number()}>{calendarDayNumber(date, system, locale)}</Text>
+      {/*
+        The tint sits under the content rather than on the cell itself: the
+        colour arrives as a runtime string from the theme, so it cannot go
+        through a class with an opacity on it, and painting the cell at full
+        strength would take the number down with it.
+      */}
+      {variant === 'tiles' && tint ? (
+        <View
+          pointerEvents="none"
+          className={styles.tint()}
+          style={{ backgroundColor: tint, opacity: TILE_TINT_OPACITY }}
+        />
+      ) : null}
+
+      {variant === 'tiles' ? (
+        <View className={styles.corner()} pointerEvents="none">
+          <Text size="xs" className={styles.number()}>
+            {calendarDayNumber(date, system, locale)}
+          </Text>
+        </View>
+      ) : variant === 'calendar' ? (
+        /*
+         * 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.
+         */
+        <View
+          className={cn(
+            'h-6 w-6 items-center justify-center self-center rounded-full',
+            isToday && 'bg-primary'
+          )}
+        >
+          <Text
+            size="xs"
+            className={cn(styles.number(), isToday && 'text-primary-foreground')}
+          >
+            {calendarDayNumber(date, system, locale)}
+          </Text>
+        </View>
+      ) : (
+        <Text className={styles.number()}>{calendarDayNumber(date, system, locale)}</Text>
+      )}
+
+      {variant === 'default' && entries.length > 0 ? (
+        <View className={styles.marker()} style={{ backgroundColor: tint }} />
+      ) : null}
 
-      {entries.length > 0 ? (
-        <View className={styles.marker()} style={{ backgroundColor: markerColor(entries, colorOf) }} />
+      {variant === 'calendar' ? (
+        <View className={styles.body()}>
+          {shown.map((entry) => (
+            <PlannerChip
+              key={entry.id}
+              entry={entry}
+              color={entry.color ?? colorOf(entry.category)}
+            />
+          ))}
+          {/*
+            Three dots, not a count. The cell has already run out of room for
+            the entries themselves, and "+2 more" spends a whole row of that
+            room on a number nobody acts on — the dots say there is more and
+            leave the row for an entry.
+          */}
+          {overflow > 0 ? (
+            <Text size="xs" muted className={styles.overflow()} numberOfLines={1}>
+              •••
+            </Text>
+          ) : null}
+        </View>
       ) : null}
 
       {/*
@@ -851,13 +1140,21 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
         "something is here" with its marker; adding a bare "+3" under an empty
         row says it twice, in a way that looks like a stray number.
       */}
-      {drawable.length > 0 ? (
+      {variant === 'tiles' && overflow > 0 ? (
+        <View className={styles.counter()} pointerEvents="none">
+          <Text size="xs" muted className={styles.overflow()}>
+            +{overflow}
+          </Text>
+        </View>
+      ) : null}
+
+      {variant !== 'calendar' && drawable.length > 0 ? (
         <View className={styles.body()}>
           {drawable.map((entry) => (
             <View key={entry.id}>{entry.icon}</View>
           ))}
-          {overflow > 0 ? (
-            <Text size="xs" muted className="leading-none">
+          {variant !== 'tiles' && overflow > 0 ? (
+            <Text size="xs" muted className={styles.overflow()}>
               +{overflow}
             </Text>
           ) : null}
@@ -866,7 +1163,31 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
     </Pressable>
   );
 }
-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 }: { entry: PlannerEntry; color?: string }) {
+  const { chip } = dayVariants();
+  return (
+    <View className={chip()} style={color ? { backgroundColor: color } : undefined}>
+      <Text
+        size="xs"
+        numberOfLines={1}
+        className={cn('leading-none', !color && 'text-foreground')}
+        style={color ? { color: '#ffffff' } : undefined}
+      >
+        {entry.label}
+      </Text>
+    </View>
+  );
+}
 
 /**
  * The dot's colour: the first entry that names a category the planner knows.
@@ -880,7 +1201,9 @@ function markerColor(
   colorOf: (category: string | undefined) => string | undefined
 ): string | undefined {
   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;
@@ -1013,6 +1336,160 @@ function PlannerDetails({ className, title, description, children }: PlannerDeta
 }
 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;
+
+export interface PlannerScrollerProps {
+  className?: string;
+  /**
+   * How many weeks either side of the opening month can be reached. Default
+   * `53`, about a year each way.
+   */
+  weeks?: number;
+  /** The height of one week row. Default `96`. */
+  rowHeight?: number;
+  /** Draws a cell yourself. It is handed the day and what falls on it. */
+  renderDay?: PlannerDayRenderer;
+}
+
+/**
+ * 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,
+}: PlannerScrollerProps) {
+  const { month, syncMonth, weekStartsOn, locale, variant, system } =
+    usePlanner('Planner.Scroller');
+  const { week: weekRow, heading } = plannerVariants();
+  const list = useRef<FlatList<Date>>(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 }: { viewableItems: ViewToken[] }) => {
+    const first = viewableItems[0]?.item as Date | undefined;
+    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 (
+    <View className={cn('flex-1', className)}>
+      <View
+        className={cn(weekRow(), 'px-1 pb-1')}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      >
+        {headings.map((label, position) => (
+          <Text key={position} size="xs" muted className={heading()}>
+            {label.toUpperCase()}
+          </Text>
+        ))}
+      </View>
+
+      <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 }) => (
+          <View
+            className={cn(
+              weekRow(),
+              'border-t border-border px-1',
+              variant === 'calendar' && 'items-stretch'
+            )}
+            style={{ height: rowHeight }}
+          >
+            {weekDays(item).map((date) => (
+              <PlannerDay key={date.getTime()} date={date} renderDay={renderDay} />
+            ))}
+          </View>
+        )}
+      />
+    </View>
+  );
+}
+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,
@@ -1020,6 +1497,7 @@ export const Planner = Object.assign(PlannerRoot, {
   Nav: PlannerNav,
   Action: PlannerAction,
   Grid: PlannerGrid,
+  Scroller: PlannerScroller,
   Day: PlannerDay,
   Legend: PlannerLegend,
   Summary: PlannerSummary,