panelui-native 0.68.0 → 0.71.0

package/src/components/meter/index.tsx

@@ -11,16 +11,21 @@ import Animated, {
 import { tv, type VariantProps } from 'tailwind-variants';
 import { Text } from '../../primitives/text';
 import {
-  clamp,
   colorFor,
-  fractionOf,
-  formatValue,
   litSegments,
+  meterSemantics,
+  normalizeScale,
+  normalizeSegments,
   type MeterColor,
   type MeterThreshold,
 } from './meter-scale';
 
-const SPRING = { damping: 20, stiffness: 180, mass: 0.6 } as const;
+const SPRING = {
+  damping: 20,
+  stiffness: 180,
+  mass: 0.6,
+  overshootClamping: true,
+} as const;
 /** Milliseconds for a segment to light or go out. */
 const SEGMENT_DURATION = 180;
 /** How faint an unlit segment sits. Present, but plainly not counted. */
@@ -32,7 +37,7 @@ const meterVariants = tv({
     header: 'flex-row items-center justify-between gap-2',
     track: 'w-full overflow-hidden rounded-full',
     indicator: 'h-full rounded-full',
-    segments: 'w-full flex-row',
+    segments: 'w-full flex-row overflow-hidden',
     segment: 'flex-1 rounded-full',
   },
   variants: {
@@ -70,7 +75,7 @@ export interface MeterProps
   extends Omit<ViewProps, 'children'>,
     MeterVariantProps {
   className?: string;
-  /** The measurement, somewhere between `minValue` and `maxValue`. */
+  /** The measurement. Values outside the scale are clamped to its ends. */
   value: number;
   /**
    * The bottom of the scale — the value at which the bar reads as empty.
@@ -111,7 +116,8 @@ export interface MeterProps
   /**
    * Points on the scale where the colour changes, each `{ from, color }`. The
    * highest one the reading has reached wins, so the order you list them in
-   * does not matter; below all of them the `color` prop applies.
+   * does not matter; below all of them the `color` prop applies. Non-finite
+   * `from` values are ignored.
    *
    * This is the difference between a meter and a bar: the colour is a
    * judgement about the reading. Which direction is bad is yours to say —
@@ -125,8 +131,10 @@ export interface MeterProps
    * say "three out of four" where a bar says "about seventy percent", and a
    * password is not seventy percent strong.
    *
-   * Any value above the floor lights at least one block, so a reading that
-   * is not empty never looks it.
+   * Fractional counts round down and counts above 100 clamp to 100. Invalid,
+   * non-positive, or sub-one counts use the continuous bar. Any value above
+   * the floor lights at least one block, so a reading that is not empty never
+   * looks it.
    */
   segments?: number;
   /** Extra classes for the fill, or for a lit segment. */
@@ -207,8 +215,9 @@ export const Meter = forwardRef<View, MeterProps>(
     },
     ref
   ) => {
-    const held = clamp(value, minValue, maxValue);
-    const fraction = fractionOf(value, minValue, maxValue);
+    const scale = normalizeScale(value, minValue, maxValue);
+    const { value: held, fraction } = scale;
+    const segmentCount = normalizeSegments(segments);
     const resolvedColor = colorFor(held, color ?? 'primary', thresholds);
     const slots = meterVariants({ color: resolvedColor, size });
     const reducedMotion = useReducedMotion();
@@ -218,7 +227,7 @@ export const Meter = forwardRef<View, MeterProps>(
     // Any reading above the floor lights a block, so "a little" never looks
     // like "none". Rounding down would leave the first quarter of a
     // four-block meter dark, which is the reading it is least able to afford.
-    const litCount = segments ? litSegments(fraction, segments) : 0;
+    const litCount = litSegments(fraction, segmentCount);
     const lit = useSharedValue(litCount);
 
     // Reduce motion lands on the value instead of springing to it — the
@@ -232,39 +241,47 @@ export const Meter = forwardRef<View, MeterProps>(
     }, [lit, litCount]);
 
     const onLayout = (event: LayoutChangeEvent) => {
-      trackWidth.value = event.nativeEvent.layout.width;
+      const width = event.nativeEvent.layout.width;
+      trackWidth.value = Number.isFinite(width) && width > 0 ? width : 0;
     };
 
     const fillStyle = useAnimatedStyle(() => ({
       width: trackWidth.value * progress.value,
     }));
 
-    const spoken = formatValue(held, fraction, valueLabel, formatOptions);
+    const semantics = meterSemantics({
+      value: held,
+      fraction,
+      // The normalized ends, not the raw props: an invalid scale is repaired
+      // for the bar, and the spoken reading has to describe the same one.
+      minValue: scale.min,
+      maxValue: scale.max,
+      label,
+      accessibilityLabel,
+      valueLabel,
+      formatOptions,
+    });
+    const spoken = semantics.text;
     const showValue = showValueLabel;
     const hasHeader = label != null || showValue;
 
     const accessibility = {
       accessibilityRole: 'progressbar' as const,
-      accessibilityLabel: accessibilityLabel ?? label,
-      accessibilityValue: {
-        min: minValue,
-        max: maxValue,
-        now: held,
-        // Without this the scale is read as a bare number. `text` is what
-        // carries the unit — the percent sign, the gigabytes, the word.
-        text: spoken,
-      },
+      accessibilityLabel: semantics.label,
+      // `text` carries the unit or word and intentionally overrides the
+      // platform's generic rendering of this numeric range.
+      accessibilityValue: semantics.value,
     };
 
     const bar =
-      segments && segments > 0 ? (
+      segmentCount > 0 ? (
         <View
           ref={ref}
           {...accessibility}
           className={slots.segments({ className })}
           {...props}
         >
-          {Array.from({ length: segments }, (_, index) => (
+          {Array.from({ length: segmentCount }, (_, index) => (
             <Segment
               key={index}
               index={index}
@@ -293,7 +310,13 @@ export const Meter = forwardRef<View, MeterProps>(
 
     return (
       <View className={slots.root()}>
-        <View className={slots.header({ className: headerClassName })}>
+        <View
+          className={slots.header({ className: headerClassName })}
+          // This is the visual rendering of the name and value already owned
+          // by the bar below. Hiding the subtree keeps one concise focus stop.
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        >
           {label != null ? (
             <Text size="sm" weight="medium" numberOfLines={1}>
               {label}

package/src/components/meter/meter-scale.ts

@@ -29,11 +29,55 @@ export interface MeterThreshold {
   color: MeterColor;
 }
 
+/** A bounded block count keeps malformed input from allocating without limit. */
+export const MAX_METER_SEGMENTS = 100;
+
+export interface MeterScale {
+  min: number;
+  max: number;
+  value: number;
+  fraction: number;
+}
+
+/**
+ * Make a public scale safe for layout, animation and native accessibility.
+ * Invalid bounds fall back to their documented defaults; if those still do
+ * not produce a positive span, the scale honestly collapses at its floor.
+ */
+export function normalizeScale(value: number, min: number, max: number): MeterScale {
+  const floor = Number.isFinite(min) ? min : 0;
+  const candidateMax = Number.isFinite(max) ? max : 100;
+  const ceiling = candidateMax > floor ? candidateMax : floor;
+  const held = Number.isNaN(value)
+    ? floor
+    : value === Number.POSITIVE_INFINITY
+      ? ceiling
+      : value === Number.NEGATIVE_INFINITY
+        ? floor
+        : Math.min(Math.max(value, floor), ceiling);
+  const magnitude = Math.max(Math.abs(floor), Math.abs(ceiling), 1);
+  const position =
+    ceiling > floor
+      ? (held / magnitude - floor / magnitude) /
+        (ceiling / magnitude - floor / magnitude)
+      : 0;
+  return {
+    min: floor,
+    max: ceiling,
+    value: held,
+    fraction: Math.min(Math.max(position, 0), 1),
+  };
+}
+
+/** Positive counts are whole and bounded; zero means the continuous meter. */
+export function normalizeSegments(segments: number | undefined) {
+  if (segments == null || !Number.isFinite(segments) || !(segments > 0)) return 0;
+  return Math.min(Math.floor(segments), MAX_METER_SEGMENTS);
+}
+
 /** `value` held inside the scale, so a stray number cannot escape the track. */
 export function clamp(value: number, min: number, max: number) {
-  if (!(value > min)) return min;
-  if (value > max) return max;
-  return value;
+  return normalizeScale(value, min, max).value;
 }
 
 /**
@@ -41,9 +85,7 @@ export function clamp(value: number, min: number, max: number) {
  * meaningful position in it, so it reads as empty rather than dividing by zero.
  */
 export function fractionOf(value: number, min: number, max: number) {
-  const span = max - min;
-  if (!(span > 0)) return 0;
-  return clamp((value - min) / span, 0, 1);
+  return normalizeScale(value, min, max).fraction;
 }
 
 /**
@@ -62,6 +104,7 @@ export function colorFor(
   if (!thresholds?.length) return base;
   let winner: MeterThreshold | undefined;
   for (const threshold of thresholds) {
+    if (!Number.isFinite(threshold.from)) continue;
     if (value < threshold.from) continue;
     if (!winner || threshold.from > winner.from) winner = threshold;
   }
@@ -77,8 +120,10 @@ export function colorFor(
  * wrong.
  */
 export function litSegments(fraction: number, segments: number) {
-  if (!(segments > 0)) return 0;
-  return Math.min(Math.ceil(fraction * segments), segments);
+  const count = normalizeSegments(segments);
+  if (count === 0 || Number.isNaN(fraction) || fraction <= 0) return 0;
+  if (!Number.isFinite(fraction) || fraction >= 1) return count;
+  return Math.min(Math.ceil(fraction * count), count);
 }
 
 /**
@@ -107,3 +152,34 @@ export function formatValue(
   }
   return `${Math.round(fraction * 100)}%`;
 }
+
+/**
+ * The meter's single spoken contract. Visual treatments such as segments,
+ * thresholds and motion do not belong here: they do not change the reading.
+ */
+export function meterSemantics({
+  value,
+  fraction,
+  minValue,
+  maxValue,
+  label,
+  accessibilityLabel,
+  valueLabel,
+  formatOptions,
+}: {
+  value: number;
+  fraction: number;
+  minValue: number;
+  maxValue: number;
+  label?: string;
+  accessibilityLabel?: string;
+  valueLabel?: string;
+  formatOptions?: Intl.NumberFormatOptions;
+}) {
+  const text = formatValue(value, fraction, valueLabel, formatOptions);
+  return {
+    label: accessibilityLabel ?? label,
+    text,
+    value: { min: minValue, max: maxValue, now: value, text },
+  };
+}

package/src/components/planner/index.tsx

@@ -64,6 +64,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type ReactElement,
   type ReactNode,
@@ -71,6 +72,7 @@ import {
 import {
   AccessibilityInfo,
   AppState,
+  Platform,
   Pressable,
   View,
   type ViewProps,
@@ -107,6 +109,12 @@ import {
   visibleEntries,
   type PlannerCountedCategory,
 } from './planner-entries';
+import { usePlannerMonthAnnouncement } from './planner-announcement';
+import { plannerGridTarget } from './planner-grid-navigation';
+import {
+  usePlannerMonthLifecycle,
+  usePlannerSelectionLifecycle,
+} from './planner-lifecycle';
 
 /** How many of a day's entries a cell draws before it stops and counts. */
 const DEFAULT_ENTRY_LIMIT = 2;
@@ -114,6 +122,11 @@ const DEFAULT_ENTRY_LIMIT = 2;
 /** The palette a category takes its dot from when it does not name a colour. */
 const PALETTE_SIZE = 5;
 
+/** Stable wrapper keeps the native method's receiver and the hook dependency steady. */
+const announceMonth = (label: string) => {
+  AccessibilityInfo.announceForAccessibility(label);
+};
+
 const plannerVariants = tv({
   slots: {
     grid: 'gap-1 px-3 pb-3 pt-1',
@@ -203,6 +216,7 @@ interface PlannerContextValue {
   summary: { total: number; categories: PlannerCountedCategory[] };
   entryLimit: number;
   weekStartsOn: number;
+  grid: Date[][];
   locale: DateLocale;
   system: 'gregory' | 'islamic';
   isInMonth: (date: Date) => boolean;
@@ -315,34 +329,51 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
     const system = resolveCalendar(calendar, locale);
     const palette = usePalette();
     const today = useToday();
-
-    const [internalMonth, setInternalMonth] = useState(() =>
-      startOfCalendarMonth(defaultMonth ?? new Date(), system, locale)
+    const settleMonth = useCallback(
+      (date: Date) => startOfCalendarMonth(date, system, locale),
+      [system, locale]
     );
-    const month = monthProp
-      ? startOfCalendarMonth(monthProp, system, locale)
-      : internalMonth;
 
+    const [month, requestMonth] = usePlannerMonthLifecycle({
+      month: monthProp,
+      defaultMonth,
+      settleMonth,
+      onMonthChange,
+    });
+    /*
+     * The announcement is registered against the month a press asks for, and
+     * spoken only once a commit arrives carrying it. That is what keeps a
+     * controlled parent's rejection silent, so it wraps the lifecycle's setter
+     * rather than living inside it — the hook owns which month is current, and
+     * this owns whether the change was the user's to hear about.
+     */
+    const expectMonthAnnouncement = usePlannerMonthAnnouncement({
+      monthKey: month.getTime(),
+      monthLabel: calendarMonthLabel(month, system, locale),
+      announce: announceMonth,
+    });
     const setMonth = useCallback(
       (next: Date) => {
-        const settled = startOfCalendarMonth(next, system, locale);
-        if (!monthProp) setInternalMonth(settled);
-        onMonthChange?.(settled);
-      },
-      [monthProp, onMonthChange, system, locale]
-    );
-
-    const [internalSelected, setInternalSelected] = useState<Date | null>(defaultSelected);
-    const selected = selectedProp !== undefined ? selectedProp : internalSelected;
-    const select = useCallback(
-      (date: Date | null) => {
-        if (selectedProp === undefined) setInternalSelected(date);
-        onSelectedChange?.(date);
+        expectMonthAnnouncement(settleMonth(next));
+        requestMonth(next);
       },
-      [selectedProp, onSelectedChange]
+      [expectMonthAnnouncement, requestMonth, settleMonth]
     );
+    const [selected, select] = usePlannerSelectionLifecycle({
+      selected: selectedProp,
+      defaultSelected,
+      onSelectedChange,
+    });
 
     const days = useMemo(() => bucketByDay(entries), [entries]);
+    const normalizedWeekStart =
+      weekStartsOn === 'auto'
+        ? localeWeekStart(locale)
+        : normalizeWeekStart(weekStartsOn);
+    const grid = useMemo(
+      () => monthGrid(month, normalizedWeekStart, system, locale),
+      [month, normalizedWeekStart, system, locale]
+    );
 
     const isInMonth = useCallback(
       (date: Date) => isSameCalendarMonth(date, month, system, locale),
@@ -354,34 +385,33 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
       [categories]
     );
 
-    const colorOf = useCallback(
-      (id: string | undefined) => {
-        if (!id) return undefined;
-        const index = categories.findIndex((category) => category.id === id);
-        if (index < 0) return undefined;
-        const category = categories[index]!;
-        if (category.color) return category.color;
-        const slot = (category.colorIndex ?? index + 1) - 1;
-        return palette[((slot % PALETTE_SIZE) + PALETTE_SIZE) % PALETTE_SIZE];
+    const categoryColors = useMemo(
+      () => {
+        const colors = new Map<string, string | undefined>();
+        categories.forEach((category, index) => {
+          // `findIndex` used to make the first duplicate id authoritative.
+          if (colors.has(category.id)) return;
+          const slot = (category.colorIndex ?? index + 1) - 1;
+          colors.set(
+            category.id,
+            category.color ??
+              palette[((slot % PALETTE_SIZE) + PALETTE_SIZE) % PALETTE_SIZE]
+          );
+        });
+        return colors;
       },
       [categories, palette]
     );
+    const colorOf = useCallback(
+      (id: string | undefined) => id ? categoryColors.get(id) : undefined,
+      [categoryColors]
+    );
 
     const summary = useMemo(
-      () => summariseMonth(entries, categories, isInMonth),
-      [entries, categories, isInMonth]
+      () => summariseMonth(days, grid, categories, isInMonth),
+      [days, grid, categories, isInMonth]
     );
 
-    /*
-     * The month is announced rather than left to the cells. Paging moves 42
-     * labels at once and a screen reader reads none of them, so without this
-     * the only thing that changes is silent.
-     */
-    const monthLabel = calendarMonthLabel(month, system, locale);
-    useEffect(() => {
-      AccessibilityInfo.announceForAccessibility(monthLabel);
-    }, [monthLabel]);
-
     const context = useMemo<PlannerContextValue>(
       () => ({
         month,
@@ -395,10 +425,8 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
         colorOf,
         summary,
         entryLimit,
-        weekStartsOn:
-          weekStartsOn === 'auto'
-            ? localeWeekStart(locale)
-            : normalizeWeekStart(weekStartsOn),
+        weekStartsOn: normalizedWeekStart,
+        grid,
         locale,
         system,
         isInMonth,
@@ -406,7 +434,8 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
       }),
       [
         month, setMonth, today, selected, select, days, categories, categoryLabels,
-        colorOf, summary, entryLimit, weekStartsOn, locale, system, isInMonth, onDayPress,
+        colorOf, summary, entryLimit, normalizedWeekStart, grid, locale, system,
+        isInMonth, onDayPress,
       ]
     );
 
@@ -600,6 +629,21 @@ export interface PlannerGridProps {
   renderDay?: PlannerDayRenderer;
 }
 
+interface PlannerGridKeyDownEvent {
+  nativeEvent: { key?: string };
+  preventDefault: () => void;
+}
+
+interface PlannerGridNavigationContextValue {
+  activeIndex: number;
+  indexByDay: ReadonlyMap<number, number>;
+  register: (index: number, node: View | null) => void;
+  focus: (index: number, event: PlannerGridKeyDownEvent) => void;
+  makeActive: (index: number) => void;
+}
+
+const PlannerGridNavigationContext = createContext<PlannerGridNavigationContextValue | null>(null);
+
 /**
  * The weekday row and the six weeks below it.
  *
@@ -609,40 +653,77 @@ export interface PlannerGridProps {
  * weekday headings are hidden rather than read out 42 times over.
  */
 function PlannerGrid({ className, renderDay }: PlannerGridProps) {
-  const { month, weekStartsOn, locale, system } = usePlanner('Planner.Grid');
+  const { grid: weeks, weekStartsOn, locale, selected, today, isInMonth } =
+    usePlanner('Planner.Grid');
   const { grid, week: weekRow, heading } = plannerVariants();
-
-  const weeks = useMemo(
-    () => monthGrid(month, weekStartsOn, system, locale),
-    [month, weekStartsOn, system, locale]
-  );
   const headings = useMemo(
     () => weekdayNames(locale, weekStartsOn),
     [locale, weekStartsOn]
   );
+  const dates = useMemo(() => weeks.flat(), [weeks]);
+  const indexByDay = useMemo(
+    () => new Map(dates.map((date, index) => [date.getTime(), index])),
+    [dates]
+  );
+  const initialDay = selected ?? today;
+  const [activeDay, setActiveDay] = useState(initialDay.getTime());
+  const storedIndex = indexByDay.get(activeDay);
+  const preferredIndex =
+    (selected ? indexByDay.get(startOfDay(selected).getTime()) : undefined) ??
+    indexByDay.get(today.getTime()) ??
+    dates.findIndex(isInMonth);
+  const activeIndex = storedIndex ?? Math.max(0, preferredIndex);
+  const refs = useRef(new Map<number, View>());
+  const register = useCallback((index: number, node: View | null) => {
+    if (node) refs.current.set(index, node);
+    else refs.current.delete(index);
+  }, []);
+  const makeActive = useCallback(
+    (index: number) => {
+      const date = dates[index];
+      if (date) setActiveDay(date.getTime());
+    },
+    [dates]
+  );
+  const focus = useCallback(
+    (index: number, event: PlannerGridKeyDownEvent) => {
+      const target = plannerGridTarget(event.nativeEvent.key ?? '', index, dates.length);
+      if (target === null) return;
+      event.preventDefault();
+      makeActive(target);
+      refs.current.get(target)?.focus();
+    },
+    [dates.length, makeActive]
+  );
+  const navigation = useMemo<PlannerGridNavigationContextValue>(
+    () => ({ activeIndex, indexByDay, register, focus, makeActive }),
+    [activeIndex, indexByDay, register, focus, makeActive]
+  );
 
   return (
-    <View className={grid({ className })}>
-      <View
-        className={weekRow()}
-        accessibilityElementsHidden
-        importantForAccessibility="no-hide-descendants"
-      >
-        {headings.map((label) => (
-          <Text key={label} size="xs" muted className={heading()}>
-            {label.toUpperCase()}
-          </Text>
-        ))}
-      </View>
-
-      {weeks.map((week, index) => (
-        <View key={index} className={weekRow()}>
-          {week.map((date) => (
-            <PlannerDay key={date.getTime()} date={date} renderDay={renderDay} />
+    <PlannerGridNavigationContext.Provider value={renderDay ? null : navigation}>
+      <View className={grid({ className })}>
+        <View
+          className={weekRow()}
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        >
+          {headings.map((label) => (
+            <Text key={label} size="xs" muted className={heading()}>
+              {label.toUpperCase()}
+            </Text>
           ))}
         </View>
-      ))}
-    </View>
+
+        {weeks.map((week, index) => (
+          <View key={index} className={weekRow()}>
+            {week.map((date) => (
+              <PlannerDay key={date.getTime()} date={date} renderDay={renderDay} />
+            ))}
+          </View>
+        ))}
+      </View>
+    </PlannerGridNavigationContext.Provider>
   );
 }
 PlannerGrid.displayName = 'Planner.Grid';
@@ -658,6 +739,10 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
     days, today, selected, select, colorOf, categoryLabels,
     entryLimit, locale, system, isInMonth, onDayPress,
   } = usePlanner('Planner.Day');
+  const navigation = useContext(PlannerGridNavigationContext);
+  const registerGridCell = navigation?.register;
+  const focusGridCell = navigation?.focus;
+  const makeGridCellActive = navigation?.makeActive;
 
   const entries = entriesOn(days, date);
   const inMonth = isInMonth(date);
@@ -677,6 +762,31 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
     onDayPress?.(date, entries);
     select(date);
   };
+  const gridIndex = navigation?.indexByDay.get(date.getTime());
+  const setRef = useCallback(
+    (node: View | null) => {
+      if (gridIndex !== undefined) registerGridCell?.(gridIndex, node);
+    },
+    [gridIndex, registerGridCell]
+  );
+  const onFocus = useCallback(() => {
+    if (gridIndex !== undefined) makeGridCellActive?.(gridIndex);
+  }, [gridIndex, makeGridCellActive]);
+  const onKeyDown = useCallback(
+    (event: PlannerGridKeyDownEvent) => {
+      if (gridIndex !== undefined) focusGridCell?.(gridIndex, event);
+    },
+    [gridIndex, focusGridCell]
+  );
+  const webGridProps =
+    Platform.OS === 'web' && gridIndex !== undefined && navigation
+      ? {
+          ref: setRef,
+          tabIndex: navigation.activeIndex === gridIndex ? (0 as const) : (-1 as const),
+          onFocus,
+          onKeyDown,
+        }
+      : {};
 
   if (renderDay) {
     return (
@@ -688,6 +798,7 @@ function PlannerDay({ date, renderDay }: PlannerDayProps) {
 
   return (
     <Pressable
+      {...(webGridProps as ViewProps)}
       onPress={press}
       accessibilityRole="button"
       accessibilityLabel={label}

package/src/components/planner/planner-announcement.ts

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+interface PlannerMonthAnnouncementOptions {
+  /** The settled month currently visible in the grid. */
+  monthKey: number;
+  monthLabel: string;
+  announce: (label: string) => void;
+}
+
+/**
+ * Announces a month only when the next committed render accepts a user request.
+ *
+ * Prop-driven months stay silent. In a controlled planner, a render that keeps
+ * the previous month rejects the pending request and clears it without speaking.
+ */
+export function usePlannerMonthAnnouncement({
+  monthKey,
+  monthLabel,
+  announce,
+}: PlannerMonthAnnouncementOptions): (month: Date) => void {
+  const pendingMonth = useRef<number | null>(null);
+
+  const expectMonth = useCallback((month: Date) => {
+    pendingMonth.current = month.getTime();
+  }, []);
+
+  // Deliberately runs after every commit: an unchanged controlled render is
+  // how a parent rejects a request, while a changed matching render accepts it.
+  useEffect(() => {
+    const expected = pendingMonth.current;
+    if (expected === null) return;
+    pendingMonth.current = null;
+    if (expected === monthKey) announce(monthLabel);
+  });
+
+  return expectMonth;
+}