panelui-native 0.66.1 → 0.71.0

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

@@ -0,0 +1,155 @@
+/**
+ * The parts of a planner that are arithmetic rather than rendering: which
+ * entries fall on which day, which category an entry belongs to, what a day
+ * says to a screen reader, and what the month adds up to.
+ *
+ * Kept out of the component so they can be tested without a renderer, and so
+ * the day cell stays a function of its inputs rather than of when it ran.
+ *
+ * Nothing here imports anything. The tests run this file through `node --test`
+ * with type stripping rather than a bundler, so an extensionless import of a
+ * sibling module — which is how the rest of the library is written — does not
+ * resolve. That is why the one line of date arithmetic below is here instead
+ * of coming from `utils/date`.
+ */
+
+/** The minimum an entry has to be for the grid to place it. */
+export interface PlannerDatedEntry {
+  date: Date;
+  /** Matches a `PlannerCategory` id. An entry without one is uncategorised. */
+  category?: string;
+}
+
+export interface PlannerCountedCategory {
+  id: string;
+  label: string;
+  count: number;
+}
+
+/** A day's key: local midnight, so two times on the same day agree. */
+export function dayKey(date: Date): number {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+}
+
+/**
+ * Entries grouped by the day they fall on, each day in the order it was given.
+ *
+ * A map rather than a lookup per cell: a month draws 42 cells, and asking each
+ * of them to filter the whole list is 42 passes over it every render.
+ */
+export function bucketByDay<T extends PlannerDatedEntry>(
+  entries: readonly T[]
+): Map<number, T[]> {
+  const days = new Map<number, T[]>();
+  for (const entry of entries) {
+    const key = dayKey(entry.date);
+    const bucket = days.get(key);
+    if (bucket) bucket.push(entry);
+    else days.set(key, [entry]);
+  }
+  return days;
+}
+
+/** What falls on one day. Always an array, so a cell has nothing to guard. */
+export function entriesOn<T extends PlannerDatedEntry>(
+  days: Map<number, T[]>,
+  date: Date
+): T[] {
+  return days.get(dayKey(date)) ?? EMPTY;
+}
+
+/*
+ * One frozen array for every empty day, rather than a new `[]` each call. A
+ * month is mostly empty days, and a fresh array per cell per render defeats
+ * every memo below it for a day where nothing changed.
+ */
+const EMPTY: never[] = Object.freeze([]) as never[];
+
+/**
+ * How many entries a cell draws before it stops and says how many are left.
+ *
+ * `limit` of 0 means draw none of them — the day still carries its marker and
+ * its spoken label, which is the whole content of a compact planner.
+ */
+export function visibleEntries<T>(entries: readonly T[], limit: number): {
+  shown: T[];
+  overflow: number;
+} {
+  const cap = Math.max(0, Math.floor(limit));
+  if (entries.length <= cap) return { shown: [...entries], overflow: 0 };
+  return { shown: entries.slice(0, cap), overflow: entries.length - cap };
+}
+
+/**
+ * What a day says when it is read out.
+ *
+ * The date on its own is what a date picker says, and it is not enough here: a
+ * day in a planner differs from the one beside it by what is on it, and a
+ * marker that carries that difference in colour alone carries it to nobody who
+ * cannot see the colour. So the count and the categories are spoken.
+ *
+ * `dateLabel` is passed in rather than formatted here, so the grid and the
+ * label agree about the calendar system and the locale.
+ */
+export function dayAccessibilityLabel<T extends PlannerDatedEntry>(
+  dateLabel: string,
+  entries: readonly T[],
+  categoryLabels: ReadonlyMap<string, string>
+): string {
+  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 && !seen.has(label)) {
+      seen.add(label);
+      named.push(label);
+    }
+  }
+
+  const count = `${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`;
+  return named.length > 0
+    ? `${dateLabel}, ${count}: ${named.join(', ')}`
+    : `${dateLabel}, ${count}`;
+}
+
+/**
+ * What the month adds up to, per category, in the order the categories were
+ * declared — so the legend and the totals beside it never disagree about which
+ * one comes first.
+ *
+ * Entries outside `month` are left out. The grid draws the days either side of
+ * the month it is showing, and counting those would make a total that changes
+ * with the week the month happens to start on.
+ */
+export function summariseMonth<T extends PlannerDatedEntry>(
+  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 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);
+        }
+      }
+    }
+  }
+
+  return {
+    total,
+    categories: categories.map(({ id, label }) => ({
+      id,
+      label,
+      count: counts.get(id) ?? 0,
+    })),
+  };
+}

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;
+}

package/src/components/popover/index.tsx

@@ -59,7 +59,7 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { Portal } from '../../primitives/portal';
+import { FocusRestorePortal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
 import { useBackHandler } from '../../hooks/use-back-handler';
 import { BottomSheet } from '../bottom-sheet';
@@ -535,7 +535,7 @@ function PopoverContent({
   if (!open || !trigger) return null;
 
   return (
-    <Portal>
+    <FocusRestorePortal>
       {/* Portal content mounts under PortalHost, outside this provider's
           subtree — re-provide the context so Popover.Close and Popover.Arrow
           keep working. */}
@@ -609,7 +609,7 @@ function PopoverContent({
           </Animated.View>
         </View>
       </PopoverContext.Provider>
-    </Portal>
+    </FocusRestorePortal>
   );
 }
 

package/src/components/radar-chart/index.tsx

@@ -59,6 +59,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import { cn } from '../../utils/cn';
 import {
   polarPoint,
@@ -212,6 +213,9 @@ export interface RadarChartProps extends Omit<ViewProps, 'children'> {
   /** Drop the room reserved for axis labels, for a radar with none. */
   compact?: boolean;
   children?: ReactNode;
+  /** Accessible data labels and optional activation for each axis row. */
+  accessibilityLabelForDatum?: ChartAccessibilityProps<RadarChartDatum>['accessibilityLabelForDatum'];
+  onAccessibilityDatumPress?: ChartAccessibilityProps<RadarChartDatum>['onAccessibilityDatumPress'];
 }
 
 /** Imperative handle: re-run the reveal on demand, for a "replay" control. */
@@ -231,6 +235,11 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
       domain,
       animationDuration = REVEAL_DURATION,
       compact = false,
+      accessible,
+      accessibilityLabel,
+      accessibilityHint,
+      accessibilityLabelForDatum,
+      onAccessibilityDatumPress,
       children,
       ...props
     },
@@ -393,6 +402,19 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
       <RadarChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
           {header}
+          <ChartAccessibilityData
+            chart="Radar chart"
+            data={data}
+            disabled={accessible === false || status === 'loading'}
+            accessibilityLabel={accessibilityLabel}
+            accessibilityHint={accessibilityHint}
+            accessibilityLabelForDatum={accessibilityLabelForDatum}
+            onAccessibilityDatumPress={onAccessibilityDatumPress}
+            valueOf={(datum) => [
+              [axisKey, datum[axisKey]],
+              ...series.map(([key]) => [key, datum[key]] as [string, unknown]),
+            ]}
+          />
           <View
             onLayout={onLayout}
             style={
@@ -407,6 +429,8 @@ const RadarChartRoot = forwardRef<RadarChartHandle, RadarChartProps>(
                 : { aspectRatio }
             }
             className={fixedSize ? 'self-center' : 'w-full'}
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
           >
             {radius > 0 ? (
               <>

package/src/components/scatter-chart/index.tsx

@@ -67,6 +67,7 @@ import Animated, {
 import Svg, { Circle, G, Line as SvgLine } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { Text } from '../../primitives/text';
+import { ChartAccessibilityData, type ChartAccessibilityProps } from '../../primitives/chart-accessibility';
 import { compactNumber, useSeriesColor, xAt, yOf, type Plot } from '../../utils/chart';
 import { cn } from '../../utils/cn';
 
@@ -191,7 +192,7 @@ export function useScatterChart() {
   return { activePoint, xDataKey };
 }
 
-export interface ScatterChartProps extends ViewProps {
+export interface ScatterChartProps extends ViewProps, ChartAccessibilityProps<ScatterChartDatum> {
   className?: string;
   /** The rows. Each one is a point, placed by two of its values. */
   data: ScatterChartDatum[];
@@ -244,6 +245,11 @@ const ScatterChartRoot = forwardRef<ScatterChartHandle, ScatterChartProps>(
       xDomain,
       yDomain,
       onActivePointChange,
+      accessible,
+      accessibilityLabel,
+      accessibilityHint,
+      accessibilityLabelForDatum,
+      onAccessibilityDatumPress,
       compact = false,
       children,
       ...props
@@ -476,7 +482,26 @@ const ScatterChartRoot = forwardRef<ScatterChartHandle, ScatterChartProps>(
       <ScatterChartContext.Provider value={context}>
         <View {...props} style={props.style} className={cn('w-full', className)}>
           {header}
-          <View onLayout={onLayout} style={{ aspectRatio }} className="w-full">
+          <ChartAccessibilityData
+            chart="Scatter chart"
+            data={data}
+            disabled={accessible === false || status === 'loading'}
+            accessibilityLabel={accessibilityLabel}
+            accessibilityHint={accessibilityHint}
+            accessibilityLabelForDatum={accessibilityLabelForDatum}
+            onAccessibilityDatumPress={onAccessibilityDatumPress}
+            valueOf={(datum) => [
+              [xDataKey, datum[xDataKey]],
+              ...series.map(([key]) => [key, datum[key]] as [string, unknown]),
+            ]}
+          />
+          <View
+            onLayout={onLayout}
+            style={{ aspectRatio }}
+            className="w-full"
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+          >
             {plot.width > 0 ? (
               <>
                 <Svg width="100%" height="100%" style={StyleSheet.absoluteFill}>

package/src/components/skeleton/index.tsx

@@ -2,31 +2,85 @@ import { memo, useEffect } from 'react';
 import Animated, {
   cancelAnimation,
   useAnimatedStyle,
+  useReducedMotion,
   useSharedValue,
   withRepeat,
   withTiming,
 } from 'react-native-reanimated';
 import { cn } from '../../utils/cn';
 
+/** Milliseconds for one half of the pulse. */
+const PULSE_DURATION = 700;
+/** How far down the pulse goes. */
+const PULSE_FLOOR = 0.45;
+/**
+ * Where the pulse rests when it is not running. Between the two ends of it, so
+ * a still skeleton looks like the same placeholder rather than a solid block.
+ */
+const RESTING_OPACITY = 0.7;
+
 export interface SkeletonProps {
   className?: string;
+  /**
+   * What is loading, for a screen reader. Setting it makes this skeleton
+   * announce as a busy status; leaving it unset keeps the placeholder out of
+   * the accessibility tree entirely.
+   *
+   * A screen full of placeholders needs **one** of them labelled, not all of
+   * them — put it on the skeleton standing for the region and leave the rest
+   * silent.
+   */
+  label?: string;
 }
 
-/** Pulsing placeholder. Opacity animation runs on the UI thread. */
-export const Skeleton = memo(function Skeleton({ className }: SkeletonProps) {
-  const opacity = useSharedValue(1);
+/**
+ * Pulsing placeholder for content that has not arrived. The opacity animation
+ * runs on the UI thread.
+ *
+ * A placeholder is a picture of absent content, so it is hidden from assistive
+ * technology by default — an unlabelled grey box announces nothing worth
+ * hearing, and a screen of them announces it many times over. Pass `label` on
+ * the one skeleton that stands for the region to have the wait announced once.
+ *
+ * Under the platform's reduce-motion setting the pulse stops and the
+ * placeholder holds at a middle opacity. Unlike a spinner, a skeleton that
+ * stops moving does not read as hung: it is a shape where content will be, and
+ * the shape says that on its own.
+ */
+export const Skeleton = memo(function Skeleton({
+  className,
+  label,
+}: SkeletonProps) {
+  const reducedMotion = useReducedMotion();
+  const opacity = useSharedValue(reducedMotion ? RESTING_OPACITY : 1);
 
   useEffect(() => {
-    opacity.value = withRepeat(withTiming(0.45, { duration: 700 }), -1, true);
+    if (reducedMotion) {
+      opacity.value = RESTING_OPACITY;
+      return undefined;
+    }
+    opacity.value = 1;
+    opacity.value = withRepeat(
+      withTiming(PULSE_FLOOR, { duration: PULSE_DURATION }),
+      -1,
+      true
+    );
     return () => cancelAnimation(opacity);
-  }, [opacity]);
+  }, [opacity, reducedMotion]);
 
   const animatedStyle = useAnimatedStyle(() => ({
     opacity: opacity.value,
   }));
 
+  const announced = label != null;
+
   return (
     <Animated.View
+      accessibilityRole={announced ? 'progressbar' : undefined}
+      accessibilityLabel={label}
+      accessibilityState={announced ? { busy: true } : undefined}
+      accessibilityElementsHidden={!announced}
+      importantForAccessibility={announced ? 'auto' : 'no-hide-descendants'}
       style={animatedStyle}
       className={cn('rounded-md bg-skeleton', className)}
     />

package/src/components/spinner/index.tsx

@@ -1,14 +1,23 @@
 import { memo, useEffect } from 'react';
 import Animated, {
   Easing,
+  cancelAnimation,
+  interpolate,
   useAnimatedStyle,
+  useReducedMotion,
   useSharedValue,
   withRepeat,
   withTiming,
-  cancelAnimation,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
 
+/** Milliseconds for one full turn. */
+const SPIN_DURATION = 800;
+/** Milliseconds for one half of the fade that stands in for the turn. */
+const PULSE_DURATION = 900;
+/** How far down the fade goes. Faint enough to read as a pulse, not a flicker. */
+const PULSE_FLOOR = 0.35;
+
 const spinnerVariants = tv({
   base: 'rounded-full border-2 border-muted border-t-primary',
   variants: {
@@ -25,27 +34,85 @@ const spinnerVariants = tv({
 
 export interface SpinnerProps extends VariantProps<typeof spinnerVariants> {
   className?: string;
+  /**
+   * What is loading, for a screen reader. Setting it makes the spinner
+   * announce as a busy status; leaving it unset keeps it out of the
+   * accessibility tree.
+   *
+   * Leave it unset wherever something around the spinner already says the
+   * wait is on — a loading button, a row with its own caption. Set it where
+   * the spinner is the only sign, or the wait passes in silence.
+   */
+  label?: string;
 }
 
-/** Rotating ring spinner. Animation runs entirely on the UI thread. */
-export const Spinner = memo(function Spinner({ className, size }: SpinnerProps) {
-  const rotation = useSharedValue(0);
+/**
+ * Rotating ring for work of unknown length. The animation runs entirely on the
+ * UI thread.
+ *
+ * A bare ring carries no words, so it is hidden from assistive technology
+ * unless `label` is given — an unnamed progress indicator announces its role
+ * and nothing else, which is noise standing in for information.
+ *
+ * Under the platform's reduce-motion setting the ring stops turning and fades
+ * in place instead. Stopping it dead is the other option and it is the wrong
+ * one: a spinner that holds still reads as one that has hung, which is the
+ * single thing a spinner exists to rule out. Reduce motion asks for less
+ * travel, not for less news.
+ */
+export const Spinner = memo(function Spinner({
+  className,
+  size,
+  label,
+}: SpinnerProps) {
+  const reducedMotion = useReducedMotion();
+  const progress = useSharedValue(0);
 
   useEffect(() => {
-    rotation.value = withRepeat(
-      withTiming(360, { duration: 800, easing: Easing.linear }),
-      -1
+    progress.value = 0;
+    progress.value = withRepeat(
+      withTiming(1, {
+        duration: reducedMotion ? PULSE_DURATION : SPIN_DURATION,
+        easing: reducedMotion ? Easing.inOut(Easing.ease) : Easing.linear,
+      }),
+      -1,
+      // The turn restarts where it began, because a full circle already ends
+      // where it started. The fade turns around, because a pulse that snapped
+      // back to full brightness would be the flicker the setting is there to
+      // avoid.
+      reducedMotion
     );
-    return () => cancelAnimation(rotation);
-  }, [rotation]);
+    return () => cancelAnimation(progress);
+  }, [progress, reducedMotion]);
+
+  /*
+   * One style sets both properties either case needs. The two are swapped on
+   * the same view when the setting changes under a mounted spinner, and an
+   * animated property that one case drops is not reset by the other — it is
+   * left at whatever it was last given, which would strand a half-faded ring
+   * at that opacity for the rest of its life.
+   */
+  const animatedStyle = useAnimatedStyle(() =>
+    reducedMotion
+      ? {
+          opacity: interpolate(progress.value, [0, 1], [1, PULSE_FLOOR]),
+          transform: [{ rotate: '0deg' }],
+        }
+      : {
+          opacity: 1,
+          transform: [{ rotate: `${progress.value * 360}deg` }],
+        }
+  );
 
-  const animatedStyle = useAnimatedStyle(() => ({
-    transform: [{ rotate: `${rotation.value}deg` }],
-  }));
+  const announced = label != null;
 
   return (
     <Animated.View
-      accessibilityRole="progressbar"
+      accessibilityRole={announced ? 'progressbar' : undefined}
+      accessibilityLabel={label}
+      accessibilityState={announced ? { busy: true } : undefined}
+      accessibilityElementsHidden={!announced}
+      importantForAccessibility={announced ? 'auto' : 'no-hide-descendants'}
       style={animatedStyle}
       className={spinnerVariants({ size, className })}
     />