panelui-native 0.65.0 → 0.68.0

package/src/components/signature/signature-accessibility.ts

@@ -0,0 +1,67 @@
+export type SignatureChangeKind = 'draw' | 'undo' | 'redo' | 'clear';
+
+export interface SignatureAccessibilityAction {
+  name: string;
+  label: string;
+}
+
+/**
+ * What the pad reads as when it is focused.
+ *
+ * It counts strokes and says nothing about whether the signature is finished,
+ * because the component cannot know that — one mark may be the whole signature
+ * or the first letter of it. Announcing "complete" after the first stroke tells
+ * somebody who cannot see the pad that they are done when they may not be.
+ */
+export function signatureAccessibilityValue(strokeCount: number) {
+  return {
+    text:
+      strokeCount === 0
+        ? 'Empty signature'
+        : `Signed, ${strokeCount} ${strokeCount === 1 ? 'stroke' : 'strokes'}`,
+  };
+}
+
+export function signatureAccessibilityActions(
+  strokeCount: number,
+  undoneCount: number,
+  alternative: boolean,
+  disabled: boolean
+): SignatureAccessibilityAction[] {
+  if (disabled) return [];
+
+  const actions: SignatureAccessibilityAction[] = [];
+  if (strokeCount > 0) {
+    actions.push(
+      { name: 'signature-undo', label: 'Undo last stroke' },
+      { name: 'signature-clear', label: 'Clear signature' }
+    );
+  }
+  if (undoneCount > 0) {
+    actions.push({ name: 'signature-redo', label: 'Redo last stroke' });
+  }
+  if (alternative) {
+    actions.push({ name: 'signature-alternative', label: 'Use another signature method' });
+  }
+  return actions;
+}
+
+/**
+ * Spoken when the pad crosses between empty and not, and nowhere else.
+ *
+ * Every stroke is silent on purpose: a running commentary during drawing is
+ * noise over the one gesture the reader is concentrating on. The two crossings
+ * are the ones that cannot be felt — that the pad now holds something, and that
+ * it no longer does.
+ */
+export function signatureAnnouncement(
+  previousCount: number,
+  strokeCount: number,
+  change: SignatureChangeKind
+): string | null {
+  if (previousCount === strokeCount) return null;
+  if (change === 'clear') return 'Signature cleared. Signature is empty.';
+  if (strokeCount === 0) return 'Signature is empty.';
+  if (previousCount === 0) return 'Signature started.';
+  return null;
+}

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/slider/index.tsx

@@ -186,6 +186,12 @@ function snap(value: number, min: number, max: number, step: number) {
 /** Which thumb a drag has hold of. A one-thumb slider only ever has `high`. */
 type Thumb = 'low' | 'high';
 
+function recordStep(last: Record<Thumb, number>, thumb: Thumb, next: number) {
+  if (next === last[thumb]) return false;
+  last[thumb] = next;
+  return true;
+}
+
 export const Slider = forwardRef<View, SliderProps>(
   (
     {
@@ -278,9 +284,12 @@ export const Slider = forwardRef<View, SliderProps>(
     rangeChangeRef.current = onRangeChange;
     const rangeCommitRef = useRef(onRangeCommit);
     rangeCommitRef.current = onRangeCommit;
-    // The last step a drag ticked on, so haptics fire once per step, not per
-    // pixel of movement within it.
-    const lastTick = useRef(value);
+    // Each thumb owns its last tick. Sharing one scalar lets the stationary
+    // endpoint suppress the thumb under the finger on a range slider.
+    const lastTick = useRef<Record<Thumb, number>>({
+      low,
+      high: isRange ? high : value,
+    });
     /*
      * True from the moment a finger lands until it lifts. A controlled parent
      * echoes every change straight back as a new prop, and springing the thumb
@@ -329,8 +338,7 @@ export const Slider = forwardRef<View, SliderProps>(
       (p: number, commit: boolean) => {
         const raw = min + p * span;
         const snapped = snap(raw, min, max, step);
-        if (haptics && snapped !== lastTick.current) {
-          lastTick.current = snapped;
+        if (haptics && recordStep(lastTick.current, 'high', snapped)) {
           selectionTick();
         }
         emitChange(snapped);
@@ -340,16 +348,13 @@ export const Slider = forwardRef<View, SliderProps>(
     );
 
     const commitRangeFromProgress = useCallback(
-      (pLow: number, pHigh: number, commit: boolean) => {
+      (pLow: number, pHigh: number, commit: boolean, thumb: Thumb) => {
         const next: [number, number] = [
           snap(min + pLow * span, min, max, step),
           snap(min + pHigh * span, min, max, step),
         ];
-        // Either end crossing onto a new step is a step crossed — the tick is
-        // about the thumb under the finger, and only one of them is.
-        const moved = next[0] !== lastTick.current && next[1] !== lastTick.current;
-        if (haptics && moved) {
-          lastTick.current = next[0];
+        const nextStep = thumb === 'low' ? next[0] : next[1];
+        if (haptics && recordStep(lastTick.current, thumb, nextStep)) {
           selectionTick();
         }
         emitRangeChange(next);
@@ -418,12 +423,12 @@ export const Slider = forwardRef<View, SliderProps>(
           const ceiling = Math.max(highProgress.value - gap, 0);
           const next = Math.min(Math.max(dragStartLow.value + delta, 0), ceiling);
           lowProgress.value = next;
-          runOnJS(commitRangeFromProgress)(next, highProgress.value, false);
+          runOnJS(commitRangeFromProgress)(next, highProgress.value, false, 'low');
         } else {
           const floor = Math.min(lowProgress.value + gap, 1);
           const next = Math.min(Math.max(dragStartHigh.value + delta, floor), 1);
           highProgress.value = next;
-          runOnJS(commitRangeFromProgress)(lowProgress.value, next, false);
+          runOnJS(commitRangeFromProgress)(lowProgress.value, next, false, 'high');
         }
       })
       .onFinalize(() => {
@@ -431,7 +436,12 @@ export const Slider = forwardRef<View, SliderProps>(
         pressedLow.value = withSpring(0, KNOB_SPRING);
         runOnJS(setDragging)(false);
         if (isRange) {
-          runOnJS(commitRangeFromProgress)(lowProgress.value, highProgress.value, true);
+          runOnJS(commitRangeFromProgress)(
+            lowProgress.value,
+            highProgress.value,
+            true,
+            activeThumb.value
+          );
         } else {
           runOnJS(commitFromProgress)(highProgress.value, true);
         }
@@ -456,11 +466,11 @@ export const Slider = forwardRef<View, SliderProps>(
         if (pickThumb(event.x) === 'low') {
           const bounded = Math.min(next, Math.max(highProgress.value - gap, 0));
           lowProgress.value = withSpring(bounded, SPRING);
-          runOnJS(commitRangeFromProgress)(bounded, highProgress.value, true);
+          runOnJS(commitRangeFromProgress)(bounded, highProgress.value, true, 'low');
         } else {
           const bounded = Math.max(next, Math.min(lowProgress.value + gap, 1));
           highProgress.value = withSpring(bounded, SPRING);
-          runOnJS(commitRangeFromProgress)(lowProgress.value, bounded, true);
+          runOnJS(commitRangeFromProgress)(lowProgress.value, bounded, true, 'high');
         }
       });
 
@@ -503,7 +513,7 @@ export const Slider = forwardRef<View, SliderProps>(
         const next = snap(value + dir * (step || 1), min, max, step);
         if (next === value) return;
         if (haptics) {
-          lastTick.current = next;
+          recordStep(lastTick.current, 'high', next);
           selectionTick();
         }
         highProgress.value = withSpring(toFraction(next), SPRING);
@@ -521,7 +531,7 @@ export const Slider = forwardRef<View, SliderProps>(
       const next = snap(bounded, min, max, step);
       if (next === current) return;
       if (haptics) {
-        lastTick.current = next;
+        recordStep(lastTick.current, thumb, next);
         selectionTick();
       }
       const pair: [number, number] = thumb === 'low' ? [next, high] : [low, next];

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 })}
     />

package/src/components/time-picker/index.tsx

@@ -36,12 +36,11 @@
  *
  * ## Scroll offset, not gesture maths
  *
- * The wheel, the clock's list and the ruler are all scroll views with
- * `snapToOffsets`, and the selection is `Math.round(offset / itemSize)`. That
- * buys momentum, deceleration, edge bounce and platform-correct fling physics
- * for nothing, and none of it would be worth rebuilding on a pan gesture. The
- * per-item fade and the ruler's readout follow the offset on the UI thread, so
- * scrolling never round-trips through React — only the settled value does.
+ * The wheel, the clock's list and the ruler are snapping scroll views, and the
+ * selection is `Math.round(offset / itemSize)`. That buys momentum,
+ * deceleration, edge bounce and platform-correct fling physics for nothing,
+ * and none of it would be worth rebuilding on a pan gesture. The ruler keeps
+ * that full scroll range but mounts only an overscanned window of its ticks.
  */
 import {
   useCallback,
@@ -79,6 +78,7 @@ import {
   accessibilityValueForIndex,
   indexForAccessibilityAction,
 } from './accessibility';
+import { rulerWindow } from './ruler-window';
 import {
   clampTime,
   displayHour,
@@ -848,10 +848,20 @@ function RulerFace({
    */
   const [width, setWidth] = useState(0);
   const pad = Math.max(0, width / 2 - TICK_SPACING / 2);
+  const [windowIndex, setWindowIndex] = useState(index);
+  // A controlled/accessibility jump renders its destination before the effect
+  // moves the scroll view there; an in-flight gesture follows the scroll window.
+  const windowAnchor = index === resting.current ? windowIndex : index;
+  const window = rulerWindow(times.length, windowAnchor);
 
-  const snapToOffsets = useMemo(
-    () => times.map((_, i) => i * TICK_SPACING),
-    [times]
+  const showIndex = useCallback(
+    (next: number) => {
+      const nextStart = rulerWindow(times.length, next).start;
+      setWindowIndex((current) =>
+        rulerWindow(times.length, current).start === nextStart ? current : next
+      );
+    },
+    [times.length]
   );
 
   // The scale runs the same rest-and-resync machinery the wheel's columns do,
@@ -872,10 +882,14 @@ function RulerFace({
 
   // Unanimated, for the reason given on the wheel's columns: an animated
   // programmatic scroll reports itself as a gesture and the correction loops.
-  const snapTo = useCallback((to: number) => {
-    resting.current = to;
-    ref.current?.scrollTo({ x: to * TICK_SPACING, animated: false });
-  }, []);
+  const snapTo = useCallback(
+    (to: number) => {
+      resting.current = to;
+      showIndex(to);
+      ref.current?.scrollTo({ x: to * TICK_SPACING, animated: false });
+    },
+    [showIndex]
+  );
 
   useEffect(() => {
     if (index === resting.current) return;
@@ -934,6 +948,13 @@ function RulerFace({
     [atRest, cancelTimer, settleAt]
   );
 
+  const onScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      showIndex(Math.round(event.nativeEvent.contentOffset.x / TICK_SPACING));
+    },
+    [showIndex]
+  );
+
   useEffect(() => cancelTimer, [cancelTimer]);
 
   const stepsPerHour = Math.max(1, Math.round(60 / minuteStep));
@@ -985,9 +1006,11 @@ function RulerFace({
           contentOffset={{ x: index * TICK_SPACING, y: 0 }}
           scrollEnabled={!disabled}
           showsHorizontalScrollIndicator={false}
-          snapToOffsets={snapToOffsets}
+          snapToInterval={TICK_SPACING}
           disableIntervalMomentum
           decelerationRate="fast"
+          onScroll={onScroll}
+          scrollEventThrottle={16}
           onScrollBeginDrag={startMoving}
           onScrollEndDrag={onDragEnd}
           onMomentumScrollBegin={startMoving}
@@ -1009,22 +1032,27 @@ function RulerFace({
             at most — which is a legend, not a scale, and reads as clutter
             beside a number set at 36px.
           */}
-          {times.map((_, i) => (
-            <View
-              key={i}
-              style={{ width: TICK_SPACING }}
-              className="items-center justify-center"
-            >
+          <View style={{ width: window.start * TICK_SPACING }} />
+          {times.slice(window.start, window.end).map((_, offset) => {
+            const i = window.start + offset;
+            return (
               <View
-                className={cn(
-                  'w-0.5 rounded-full',
-                  // Taller and darker on the hour, so the scale reads as hours
-                  // rather than as an undifferentiated comb.
-                  i % stepsPerHour === 0 ? 'h-7 bg-muted-foreground' : 'h-4 bg-border'
-                )}
-              />
-            </View>
-          ))}
+                key={i}
+                style={{ width: TICK_SPACING }}
+                className="items-center justify-center"
+              >
+                <View
+                  className={cn(
+                    'w-0.5 rounded-full',
+                    // Taller and darker on the hour, so the scale reads as hours
+                    // rather than as an undifferentiated comb.
+                    i % stepsPerHour === 0 ? 'h-7 bg-muted-foreground' : 'h-4 bg-border'
+                  )}
+                />
+              </View>
+            );
+          })}
+          <View style={{ width: (times.length - window.end) * TICK_SPACING }} />
         </ScrollView>
 
         {/* Over the scale rather than in it: the indicator marks the centre of

package/src/components/time-picker/ruler-window.ts

@@ -0,0 +1,24 @@
+/** Maximum tick cells mounted by the ruler, regardless of the minute step. */
+export const RULER_WINDOW_SIZE = 121;
+
+const WINDOW_SHIFT = 40;
+
+export interface RulerWindow {
+  start: number;
+  end: number;
+}
+
+/**
+ * A chunked, overscanned slice around the visible tick. It moves only once per
+ * WINDOW_SHIFT ticks, leaving at least forty ticks ahead of a normal scroll.
+ */
+export function rulerWindow(itemCount: number, visibleIndex: number): RulerWindow {
+  const count = Math.max(0, Math.floor(itemCount));
+  if (count <= RULER_WINDOW_SIZE) return { start: 0, end: count };
+
+  const index = Math.min(Math.max(Math.round(visibleIndex), 0), count - 1);
+  const chunk = Math.floor(index / WINDOW_SHIFT) * WINDOW_SHIFT;
+  const before = Math.floor((RULER_WINDOW_SIZE - WINDOW_SHIFT) / 2);
+  const start = Math.min(Math.max(chunk - before, 0), count - RULER_WINDOW_SIZE);
+  return { start, end: start + RULER_WINDOW_SIZE };
+}

package/src/hooks/breakpoint-contract.ts

@@ -0,0 +1,31 @@
+export type BreakpointDefinition = Readonly<Record<string, number>>;
+
+/** Validate declaration order once, when an app creates its responsive contract. */
+export function breakpointEntries<const T extends BreakpointDefinition>(definition: T) {
+  const entries = Object.entries(definition) as [keyof T & string, number][];
+  if (!entries.length) throw new Error('Breakpoints must declare at least one threshold.');
+  let previous = -1;
+  for (const [name, threshold] of entries) {
+    if (!name || !Number.isFinite(threshold) || threshold < 0) {
+      throw new Error(`Breakpoint "${name}" must have a finite, non-negative threshold.`);
+    }
+    if (threshold <= previous) {
+      throw new Error('Breakpoint thresholds must be strictly ascending in declaration order.');
+    }
+    previous = threshold;
+  }
+  return entries;
+}
+
+/** Largest satisfied name, with `base` as the deterministic below-range fallback. */
+export function breakpointAt<Name extends string>(
+  entries: readonly (readonly [Name, number])[],
+  width: number
+): Name | 'base' {
+  let current: Name | 'base' = 'base';
+  for (const [name, threshold] of entries) {
+    if (width < threshold) break;
+    current = name;
+  }
+  return current;
+}

package/src/hooks/index.ts

@@ -10,8 +10,12 @@ export {
 } from './use-disclosure';
 export {
   useBreakpoint,
+  createBreakpoints,
   BREAKPOINTS,
   type Breakpoint,
+  type BreakpointContract,
+  type BreakpointProviderProps,
+  type BreakpointResult,
   type UseBreakpointResult,
 } from './use-breakpoint';
 export { useKeyboard, type UseKeyboardResult } from './use-keyboard';