panelui-native 0.68.0 → 0.73.0

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',
@@ -136,7 +149,13 @@ const dayVariants = tv({
      * Square-ish because a day here holds a number, a marker and sometimes an
      * icon, and a circle wastes the corners it needs for them.
      */
-    cell: 'mx-0.5 h-14 flex-1 rounded-xl px-1.5 pt-1.5',
+    /*
+     * The transparent border is load-bearing: today and the open day both draw
+     * one, and a cell that only grows a border when it is picked shifts its
+     * contents by a point at the moment you look at it. Every cell reserves the
+     * point; the variants below only colour it.
+     */
+    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',
@@ -148,13 +167,22 @@ const dayVariants = tv({
       false: { cell: 'bg-muted/15', number: 'text-muted-foreground/40' },
     },
     /*
-     * Today is the number, not the tile. A ring on today and a ring on the
-     * open day are two rings that mean different things and look the same.
+     * Today rings the tile; the open day fills it. Two rings would be the
+     * problem — two channels are not, and the ring is the one that has to
+     * survive being read at a glance across forty-two tiles.
      */
-    today: { true: { number: 'text-primary font-semibold' } },
-    selected: { true: { cell: 'border border-primary/60 bg-primary/10' } },
+    today: { true: { cell: 'border-foreground', number: 'font-semibold' } },
+    selected: { true: { cell: 'border-primary/60 bg-primary/10' } },
     disabled: { true: { cell: 'opacity-40' } },
   },
+  compoundVariants: [
+    /*
+     * Today, and open. Declaration order would otherwise hand the border to
+     * `selected` and lose the one mark that says which day it actually is —
+     * so the ring is restated over the fill.
+     */
+    { today: true, selected: true, class: { cell: 'border-foreground bg-primary/10' } },
+  ],
   defaultVariants: { inMonth: true },
 });
 
@@ -203,6 +231,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 +344,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);
+        expectMonthAnnouncement(settleMonth(next));
+        requestMonth(next);
       },
-      [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);
-      },
-      [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 +400,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 +440,8 @@ const PlannerRoot = forwardRef<View, PlannerProps>(
         colorOf,
         summary,
         entryLimit,
-        weekStartsOn:
-          weekStartsOn === 'auto'
-            ? localeWeekStart(locale)
-            : normalizeWeekStart(weekStartsOn),
+        weekStartsOn: normalizedWeekStart,
+        grid,
         locale,
         system,
         isInMonth,
@@ -406,7 +449,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 +644,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 +668,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 +754,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 +777,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 +813,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;
+}

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

@@ -99,9 +99,13 @@ export function dayAccessibilityLabel<T extends PlannerDatedEntry>(
   if (entries.length === 0) return `${dateLabel}, nothing planned`;
 
   const named: string[] = [];
+  const seen = new Set<string>();
   for (const entry of entries) {
     const label = entry.category ? categoryLabels.get(entry.category) : undefined;
-    if (label && !named.includes(label)) named.push(label);
+    if (label && !seen.has(label)) {
+      seen.add(label);
+      named.push(label);
+    }
   }
 
   const count = `${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`;
@@ -120,18 +124,23 @@ export function dayAccessibilityLabel<T extends PlannerDatedEntry>(
  * with the week the month happens to start on.
  */
 export function summariseMonth<T extends PlannerDatedEntry>(
-  entries: readonly T[],
+  days: Map<number, T[]>,
+  grid: readonly (readonly Date[])[],
   categories: readonly { id: string; label: string }[],
   isInMonth: (date: Date) => boolean
 ): { total: number; categories: PlannerCountedCategory[] } {
   const counts = new Map<string, number>();
   let total = 0;
 
-  for (const entry of entries) {
-    if (!isInMonth(entry.date)) continue;
-    total += 1;
-    if (entry.category) {
-      counts.set(entry.category, (counts.get(entry.category) ?? 0) + 1);
+  for (const week of grid) {
+    for (const date of week) {
+      if (!isInMonth(date)) continue;
+      for (const entry of entriesOn(days, date)) {
+        total += 1;
+        if (entry.category) {
+          counts.set(entry.category, (counts.get(entry.category) ?? 0) + 1);
+        }
+      }
     }
   }
 

package/src/components/planner/planner-grid-navigation.ts

@@ -0,0 +1,45 @@
+export type PlannerGridNavigationKey =
+  | 'ArrowLeft'
+  | 'ArrowRight'
+  | 'ArrowUp'
+  | 'ArrowDown'
+  | 'Home'
+  | 'End';
+
+/** Returns the next visible cell for a bounded, row-major month grid. */
+export function plannerGridTarget(
+  key: string,
+  index: number,
+  count: number,
+  columns = 7
+): number | null {
+  if (!Number.isInteger(index) || index < 0 || index >= count || columns < 1) {
+    return null;
+  }
+
+  let target: number;
+  switch (key as PlannerGridNavigationKey) {
+    case 'ArrowLeft':
+      target = index - 1;
+      break;
+    case 'ArrowRight':
+      target = index + 1;
+      break;
+    case 'ArrowUp':
+      target = index - columns;
+      break;
+    case 'ArrowDown':
+      target = index + columns;
+      break;
+    case 'Home':
+      target = index - (index % columns);
+      break;
+    case 'End':
+      target = index + (columns - 1 - (index % columns));
+      break;
+    default:
+      return null;
+  }
+
+  return target >= 0 && target < count ? target : index;
+}

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

@@ -0,0 +1,76 @@
+import { useCallback, useMemo, useState } from 'react';
+
+interface PlannerMonthLifecycleOptions {
+  month: Date | undefined;
+  defaultMonth: Date | undefined;
+  settleMonth: (month: Date) => Date;
+  onMonthChange: ((month: Date) => void) | undefined;
+}
+
+/** Keeps controlled requests separate from the month a parent has accepted. */
+export function usePlannerMonthLifecycle({
+  month: monthProp,
+  defaultMonth,
+  settleMonth,
+  onMonthChange,
+}: PlannerMonthLifecycleOptions): readonly [Date, (month: Date) => void] {
+  const [internalMonth, setInternalMonth] = useState(() =>
+    settleMonth(defaultMonth ?? new Date())
+  );
+  const isControlled = monthProp !== undefined;
+
+  /*
+   * Parents commonly create an equivalent Date on every render. Keying this
+   * derivation by its instant keeps the month object stable, so an unrelated
+   * parent render does not rebuild the grid and its month summary.
+   */
+  const controlledMonth = useMemo(
+    () =>
+      monthProp === undefined
+        ? undefined
+        : settleMonth(monthProp),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [monthProp?.getTime(), settleMonth]
+  );
+  const month = controlledMonth ?? internalMonth;
+
+  const setMonth = useCallback(
+    (next: Date) => {
+      const settled = settleMonth(next);
+      if (!isControlled) setInternalMonth(settled);
+      onMonthChange?.(settled);
+    },
+    [isControlled, onMonthChange, settleMonth]
+  );
+
+  return [month, setMonth] as const;
+}
+
+interface PlannerSelectionLifecycleOptions {
+  selected: Date | null | undefined;
+  defaultSelected: Date | null;
+  onSelectedChange: ((date: Date | null) => void) | undefined;
+}
+
+/** Commits locally only when selection is uncontrolled, but always reports a request. */
+export function usePlannerSelectionLifecycle({
+  selected: selectedProp,
+  defaultSelected,
+  onSelectedChange,
+}: PlannerSelectionLifecycleOptions): readonly [
+  Date | null,
+  (date: Date | null) => void,
+] {
+  const [internalSelected, setInternalSelected] = useState<Date | null>(defaultSelected);
+  const isControlled = selectedProp !== undefined;
+  const selected = isControlled ? selectedProp : internalSelected;
+  const select = useCallback(
+    (date: Date | null) => {
+      if (!isControlled) setInternalSelected(date);
+      onSelectedChange?.(date);
+    },
+    [isControlled, onSelectedChange]
+  );
+
+  return [selected, select] as const;
+}