panelui-native 0.63.0 → 0.66.1

package/src/components/message-scroller/index.tsx

@@ -57,9 +57,12 @@ import { ChevronDownIcon } from '../../icons';
 import { AnimatedPressable } from '../../primitives/animated-pressable';
 import { cn } from '../../utils/cn';
 import { textChildren } from '../../primitives/text';
+import {
+  distanceFromMessageScrollerTarget,
+  isMessageScrollerTargetVisible,
+  MESSAGE_SCROLLER_EDGE_THRESHOLD,
+} from './message-scroller-math';
 
-/** Within this many pixels of the bottom still counts as being at the bottom. */
-const END_THRESHOLD = 24;
 /**
  * How much of the previous turn is left showing above an anchored one. Scrolling
  * a turn flush to the top reads as content having been cut off; a sliver of the
@@ -71,8 +74,11 @@ export type MessageScrollerPosition = 'start' | 'end' | 'last-anchor';
 
 interface MessageScrollerContextValue {
   scrollRef: ReturnType<typeof useAnimatedRef<Animated.ScrollView>>;
-  /** 1 while the reader is at the live edge, 0 otherwise. Drives the button. */
+  /** 1 while the reader is at the live edge, 0 otherwise. Drives follow state. */
   atEnd: ReturnType<typeof useSharedValue<number>>;
+  /** Live distance from each edge, used by target-specific jump controls. */
+  distanceFromStart: ReturnType<typeof useSharedValue<number>>;
+  distanceFromEnd: ReturnType<typeof useSharedValue<number>>;
   atEndJS: boolean;
   setAtEndJS: (atEnd: boolean) => void;
   autoScroll: boolean;
@@ -150,6 +156,11 @@ function MessageScrollerRoot({
 }: MessageScrollerProps) {
   const scrollRef = useAnimatedRef<Animated.ScrollView>();
   const atEnd = useSharedValue(1);
+  const awayFromEdge = MESSAGE_SCROLLER_EDGE_THRESHOLD + 1;
+  const distanceFromStart = useSharedValue(
+    defaultScrollPosition === 'start' ? 0 : awayFromEdge
+  );
+  const distanceFromEnd = useSharedValue(defaultScrollPosition === 'end' ? 0 : awayFromEdge);
   const [atEndJS, setAtEndJS] = useState(true);
   const [currentAnchorId, setCurrentAnchorId] = useState<string | null>(null);
 
@@ -199,6 +210,8 @@ function MessageScrollerRoot({
     () => ({
       scrollRef,
       atEnd,
+      distanceFromStart,
+      distanceFromEnd,
       atEndJS,
       setAtEndJS,
       autoScroll,
@@ -218,6 +231,8 @@ function MessageScrollerRoot({
     [
       scrollRef,
       atEnd,
+      distanceFromStart,
+      distanceFromEnd,
       atEndJS,
       autoScroll,
       preserveScrollOnPrepend,
@@ -268,6 +283,8 @@ function MessageScrollerViewport({
   const {
     scrollRef,
     atEnd,
+    distanceFromStart,
+    distanceFromEnd,
     setAtEndJS,
     autoScroll,
     preserveScrollOnPrepend,
@@ -310,8 +327,19 @@ function MessageScrollerViewport({
       const { contentOffset, contentSize, layoutMeasurement } = event;
       offsetY.value = contentOffset.y;
 
-      const distance = contentSize.height - layoutMeasurement.height - contentOffset.y;
-      const next = distance <= END_THRESHOLD ? 1 : 0;
+      distanceFromStart.value = distanceFromMessageScrollerTarget(
+        'start',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      distanceFromEnd.value = distanceFromMessageScrollerTarget(
+        'end',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      const next = isMessageScrollerTargetVisible(distanceFromEnd.value) ? 0 : 1;
       if (next !== atEnd.value) {
         atEnd.value = next;
         runOnJS(publishAtEnd)(next === 1);
@@ -515,12 +543,16 @@ function MessageScrollerButton({
   children,
   ...props
 }: MessageScrollerButtonProps) {
-  const { atEnd, scrollToEnd, scrollToStart } = useScroller('MessageScroller.Button');
+  const { distanceFromStart, distanceFromEnd, scrollToEnd, scrollToStart } =
+    useScroller('MessageScroller.Button');
   const tint = useCSSVariable('--color-foreground');
 
+  const targetDistance = target === 'end' ? distanceFromEnd : distanceFromStart;
   // Shown when away from the edge the button points at.
   const shown = useDerivedValue(() =>
-    withTiming(target === 'end' ? 1 - atEnd.value : atEnd.value, { duration: 160 })
+    withTiming(isMessageScrollerTargetVisible(targetDistance.value) ? 1 : 0, {
+      duration: 160,
+    })
   );
 
   const style = useAnimatedStyle(() => ({

package/src/components/message-scroller/message-scroller-math.ts

@@ -0,0 +1,24 @@
+type MessageScrollerTarget = 'start' | 'end';
+
+export const MESSAGE_SCROLLER_EDGE_THRESHOLD = 24;
+
+/** Distance from the viewport to the edge a jump button targets. */
+export function distanceFromMessageScrollerTarget(
+  target: MessageScrollerTarget,
+  contentOffsetY: number,
+  contentHeight: number,
+  viewportHeight: number
+): number {
+  'worklet';
+
+  const maximumOffset = Math.max(0, contentHeight - viewportHeight);
+  const boundedOffset = Math.min(maximumOffset, Math.max(0, contentOffsetY));
+  return target === 'start' ? boundedOffset : maximumOffset - boundedOffset;
+}
+
+/** Whether the control has enough distance to its target edge to be useful. */
+export function isMessageScrollerTargetVisible(distance: number): boolean {
+  'worklet';
+
+  return distance > MESSAGE_SCROLLER_EDGE_THRESHOLD;
+}

package/src/components/number-input/index.tsx

@@ -34,6 +34,7 @@ import { AnimatedPressable } from '../../primitives/animated-pressable';
 import { Text } from '../../primitives/text';
 import { selectionTick } from '../../utils/haptics';
 import { Label } from '../label';
+import { normalize, precisionOf } from './number-input-math';
 
 /** Wait before a held button starts repeating — a tap must not trip it. */
 const REPEAT_DELAY = 400;
@@ -156,32 +157,6 @@ export interface NumberInputProps
   haptics?: boolean;
 }
 
-/** Decimals implied by `step`, so display and math round to the same place. */
-function precisionOf(step: number): number {
-  if (!isFinite(step)) return 0;
-  const s = String(step);
-  const dot = s.indexOf('.');
-  return dot === -1 ? 0 : s.length - dot - 1;
-}
-
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(Math.max(value, min), max);
-}
-
-/**
- * Snaps to the nearest step from a finite base (or 0 when `min` is open), then
- * rounds to the step's precision so 0.1 + 0.2 does not drift to 0.30000004.
- */
-function normalize(value: number, min: number, max: number, step: number): number {
-  const base = isFinite(min) ? min : 0;
-  const snapped = isFinite(step) && step > 0
-    ? Math.round((value - base) / step) * step + base
-    : value;
-  const p = precisionOf(step);
-  const factor = 10 ** p;
-  return clamp(Math.round(snapped * factor) / factor, min, max);
-}
-
 /**
  * A number stepped by buttons or typed by hand, reconciled to one clamped,
  * step-snapped value. See the file header for why it keeps both affordances.

package/src/components/number-input/number-input-math.ts

@@ -0,0 +1,50 @@
+/** JavaScript numbers carry about fifteen reliable decimal digits. */
+const MAX_DECIMAL_PRECISION = 15;
+
+/** Decimals `step` implies, before the reliable-digits ceiling is applied. */
+function requestedPrecision(step: number): number {
+  if (!Number.isFinite(step)) return 0;
+
+  const [coefficient = '', exponentText] = Math.abs(step).toString().toLowerCase().split('e');
+  const decimals = coefficient.split('.')[1]?.length ?? 0;
+  const exponent = exponentText === undefined ? 0 : Number(exponentText);
+
+  return Math.max(0, decimals - exponent);
+}
+
+/** Decimals implied by `step`, including numbers written with an exponent. */
+export function precisionOf(step: number): number {
+  return Math.min(MAX_DECIMAL_PRECISION, requestedPrecision(step));
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Snaps to the nearest step from a finite base, then clears binary drift at
+ * the step's decimal precision.
+ */
+export function normalize(value: number, min: number, max: number, step: number): number {
+  const base = Number.isFinite(min) ? min : 0;
+  const offset = (value - base) / step;
+  const snapped =
+    Number.isFinite(step) && step > 0 && Number.isFinite(offset)
+      ? Math.round(offset) * step + base
+      : value;
+
+  // A step finer than the reliable-digit ceiling cannot be tidied at its own
+  // precision: rounding at the ceiling instead lands on zero and takes the
+  // value with it. The snap already placed it on the step, so leave it there.
+  if (requestedPrecision(step) > MAX_DECIMAL_PRECISION) return clamp(snapped, min, max);
+
+  const precision = precisionOf(step);
+  const factor = 10 ** precision;
+  const scaled = snapped * factor;
+  // Keep the established rounding path while it is safe. toFixed avoids
+  // turning a finite large value into Infinity when scaling would overflow.
+  const rounded = Number.isFinite(scaled)
+    ? Math.round(scaled) / factor
+    : Number(snapped.toFixed(precision));
+  return clamp(rounded, min, max);
+}

package/src/components/plot/index.tsx

@@ -68,6 +68,7 @@ import {
   isValidElement,
   useContext,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -328,7 +329,7 @@ const PlotRoot = forwardRef<PlotHandle, PlotProps>(function PlotRoot(
   const [size, setSize] = useState({ width: 0, height: 0 });
   const [series, setSeries] = useState<[string, string][]>([]);
   const [activeIndexJS, setActiveIndexJS] = useState(-1);
-  const clipId = useRef(`panelui-plot-${Math.random().toString(36).slice(2, 9)}`).current;
+  const clipId = `panelui-plot-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
 
   const reveal = useSharedValue(0);
   const domainMin = useSharedValue(0);

package/src/components/popover/index.tsx

@@ -321,6 +321,9 @@ export interface PopoverContentProps extends ViewProps {
    * Frost the background behind the panel instead of dimming it. Uses
    * `expo-blur` when installed and falls back to the dimmed scrim when it is
    * not, so it is safe to pass either way.
+   *
+   * Someone who has Reduce Transparency switched on gets an opaque
+   * backdrop instead, which is the whole point of the setting.
    */
   blur?: boolean;
   /**

package/src/components/radio-group/index.tsx

@@ -45,7 +45,7 @@ const itemVariants = tv({
     // `self-start` matters: the group is a column, so without it Yoga stretches
     // the row to the full width and the dead space to the right of the label
     // becomes part of the target. Tapping nothing would select the option.
-    row: 'flex-row items-center gap-2.5 self-start',
+    row: 'min-h-12 min-w-12 flex-row items-center gap-2.5 self-start',
     indicator:
       'h-5 w-5 items-center justify-center rounded-full border border-input bg-background',
     label: 'text-sm text-foreground',
@@ -248,7 +248,6 @@ const RadioGroupItem = forwardRef<View, RadioGroupItemProps>(
         accessibilityLabel={label}
         disabled={disabled}
         onPress={() => context.onValueChange(value)}
-        hitSlop={variant === 'card' ? undefined : 8}
         className={slots.row({ className })}
       >
         {body}

package/src/components/selection-mode/index.tsx

@@ -88,6 +88,15 @@ import { Text, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import { selectionTick } from '../../utils/haptics';
 import { BottomSheet } from '../bottom-sheet';
+import {
+  canEnterSelection,
+  handleSelectionItemPress,
+  selectAllValues,
+  selectionOwnsPress,
+  selectionTarget,
+  selectValue,
+  toggleValue,
+} from './selection-mode-contracts';
 
 /** How long the circle takes to come and go, in milliseconds. */
 const REVEAL_DURATION = 180;
@@ -293,11 +302,12 @@ function SelectionModeRoot({
       // Entering with the row that was pressed already picked. Entering with
       // nothing picked leaves the reader in a list that has changed under them
       // with nothing to show for it.
-      if (value !== undefined && !selectedRef.current.includes(value)) {
-        setSelected([...selectedRef.current, value]);
+      if (value !== undefined) {
+        const next = selectValue(selectedRef.current, value, max);
+        if (next !== selectedRef.current) setSelected(next);
       }
     },
-    [haptics, setActive, setSelected]
+    [haptics, max, setActive, setSelected]
   );
 
   /*
@@ -321,13 +331,10 @@ function SelectionModeRoot({
   const toggle = useCallback(
     (value: string) => {
       const current = selectedRef.current;
-      if (current.includes(value)) {
-        setSelected(current.filter((entry) => entry !== value));
-      } else {
-        if (max !== undefined && current.length >= max) return;
-        if (haptics) selectionTick();
-        setSelected([...current, value]);
-      }
+      const next = toggleValue(current, value, max);
+      if (next === current) return;
+      if (!current.includes(value) && haptics) selectionTick();
+      setSelected(next);
     },
     [max, haptics, setSelected]
   );
@@ -336,15 +343,15 @@ function SelectionModeRoot({
     if (!values) return;
     // At the limit rather than refusing: somebody who asked for all of them and
     // can only have twenty wants the twenty, not an error.
-    setSelected(max === undefined ? [...values] : values.slice(0, max));
+    setSelected(selectAllValues(values, max));
   }, [values, max, setSelected]);
 
   const clear = useCallback(() => setSelected([]), [setSelected]);
 
   const total = values?.length ?? 0;
   const count = selected.length;
-  const allSelected =
-    total > 0 && count >= (max === undefined ? total : Math.min(total, max));
+  const target = selectionTarget(total, max);
+  const allSelected = target > 0 && count >= target;
 
   // An open mode owns the back button: back should leave the mode, not the
   // screen the list is on.
@@ -459,10 +466,11 @@ export interface SelectionModeItemProps extends Omit<ViewProps, 'children'> {
   className?: string;
   /** This row's id. What ends up in `selected`. */
   value: string;
-  /** What the row does when it is pressed and the mode is off. */
+  /** What the row does whenever selection does not own its press. */
   onPress?: () => void;
   /**
-   * Stop this row entering selection mode, and being picked once in it. For a
+   * Stop this row entering selection mode, and being picked once in it. Its
+   * ordinary `onPress` still runs, including while selection is active. For a
    * header row, an advert, a "load more" — anything in the list that is not one
    * of the things being chosen between.
    */
@@ -487,8 +495,9 @@ export interface SelectionModeItemProps extends Omit<ViewProps, 'children'> {
  *
  * The press behaviour is the whole component: off mode, a press is the row's
  * own and a long press turns the mode on with this row picked; in it, a press
- * picks and unpicks and the row's own press is unreachable. Two meanings for
- * one gesture is exactly why the mode has to be visible from the header.
+ * picks and unpicks. A row excluded from selection keeps its ordinary press in
+ * both states. Two meanings for one gesture is exactly why the mode has to be
+ * visible from the header.
  */
 function SelectionModeItem({
   className,
@@ -503,6 +512,7 @@ function SelectionModeItem({
   const { active, enter, toggle, isSelected, sheet } = useSelectionMode();
   const selected = isSelected(value);
   const showing = alwaysShowIndicator || active;
+  const selecting = selectionOwnsPress(active, disabled);
   const reducedMotion = useReducedMotion();
 
   const context = useMemo(() => ({ value }), [value]);
@@ -537,23 +547,20 @@ function SelectionModeItem({
   return (
     <SelectionModeItemContext.Provider value={context}>
       <Pressable
-        accessibilityRole={showing ? 'checkbox' : 'button'}
-        accessibilityState={showing ? { checked: selected, disabled } : { disabled }}
-        // The row is unreachable in selection mode, so a screen reader is told
-        // what pressing it does now rather than what it used to do.
+        accessibilityRole={selecting ? 'checkbox' : 'button'}
+        accessibilityState={selecting ? { checked: selected } : undefined}
+        // Eligible rows become checkboxes only while selection owns their
+        // press. Excluded rows remain ordinary buttons because their action is
+        // still available.
         accessibilityHint={
-          showing ? undefined : disabled ? undefined : 'Long press to select'
+          active || disabled ? undefined : 'Long press to select'
         }
-        disabled={disabled && showing}
         onPress={() => {
-          if (disabled) return;
-          if (showing) toggle(value);
-          else onPress?.();
-        }}
-        onLongPress={sheet ? undefined : () => {
-          if (disabled || showing) return;
-          enter(value);
+          handleSelectionItemPress(active, disabled, () => toggle(value), onPress);
         }}
+        onLongPress={
+          canEnterSelection(active, disabled, sheet) ? () => enter(value) : undefined
+        }
         className={cn(
           indicator === 'leading' ? 'flex-row items-center gap-3 px-4 py-2.5' : '',
           className

package/src/components/selection-mode/selection-mode-contracts.ts

@@ -0,0 +1,53 @@
+/** The effective selection cap. Invalid and negative caps allow no additions. */
+function selectionLimit(max?: number): number {
+  if (max === undefined || max === Infinity) return Infinity;
+  return Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 0;
+}
+
+/** Add one value without duplicating it or crossing the configured cap. */
+export function selectValue(selected: string[], value: string, max?: number): string[] {
+  if (selected.includes(value) || !(selected.length < selectionLimit(max))) return selected;
+  return [...selected, value];
+}
+
+/** Remove an existing value, or add it under the same contract used by entry. */
+export function toggleValue(selected: string[], value: string, max?: number): string[] {
+  return selected.includes(value)
+    ? selected.filter((entry) => entry !== value)
+    : selectValue(selected, value, max);
+}
+
+/** The values produced by select-all, capped by the same normalized limit. */
+export function selectAllValues(values: string[], max?: number): string[] {
+  const limit = selectionLimit(max);
+  return limit === Infinity ? [...values] : values.slice(0, limit);
+}
+
+/** How many selections constitute all selectable values. */
+export function selectionTarget(total: number, max?: number): number {
+  return Math.min(total, selectionLimit(max));
+}
+
+/**
+ * A selection-ineligible row keeps its ordinary action in every mode. Only an
+ * active, eligible row gives its press to selection.
+ */
+export function selectionOwnsPress(active: boolean, disabled: boolean): boolean {
+  return active && !disabled;
+}
+
+/** Execute the one action owned by a row press under the interaction contract. */
+export function handleSelectionItemPress(
+  active: boolean,
+  disabled: boolean,
+  toggle: () => void,
+  action?: () => void
+): void {
+  if (selectionOwnsPress(active, disabled)) toggle();
+  else action?.();
+}
+
+/** Long press enters only from an inactive screen row that can be selected. */
+export function canEnterSelection(active: boolean, disabled: boolean, sheet: boolean): boolean {
+  return !active && !disabled && !sheet;
+}

package/src/components/signature/index.tsx

@@ -58,7 +58,12 @@ import {
   type ReactNode,
   type Ref,
 } from 'react';
-import { View, type ViewProps } from 'react-native';
+import {
+  AccessibilityInfo,
+  View,
+  type AccessibilityActionEvent,
+  type ViewProps,
+} from 'react-native';
 import { useCSSVariable } from 'uniwind';
 import { Gesture, GestureDetector } from 'react-native-gesture-handler';
 import Animated, {
@@ -81,6 +86,12 @@ import {
 } from '../../primitives/animated-pressable';
 import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
+import {
+  signatureAccessibilityActions,
+  signatureAccessibilityValue,
+  signatureAnnouncement,
+  type SignatureChangeKind,
+} from './signature-accessibility';
 
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 
@@ -175,6 +186,12 @@ export interface SignatureProps
   placeholder?: ReactNode;
   /** Take no input. The strokes already there stay visible. */
   disabled?: boolean;
+  /**
+   * Opens a product-provided non-drawing method, such as typing a legal name,
+   * uploading an image, or asking for assisted signing. Exposed as a screen
+   * reader action; provide the same choice as a visible control too.
+   */
+  onRequestAlternative?: () => void;
   /** A stroke has started. */
   onBegin?: () => void;
   /** A stroke has finished. */
@@ -292,12 +309,17 @@ function SignatureRoot(
     guidelineLabel,
     placeholder,
     disabled = false,
+    onRequestAlternative,
     onBegin,
     onEnd,
     onChange,
     padClassName,
     placeholderClassName,
     guideClassName,
+    accessibilityLabel,
+    accessibilityHint,
+    accessibilityActions,
+    onAccessibilityAction,
     ...props
   }: SignatureProps,
   ref: Ref<SignatureHandle>
@@ -325,19 +347,30 @@ function SignatureRoot(
   beginRef.current = onBegin;
   const endRef = useRef(onEnd);
   endRef.current = onEnd;
+  const alternativeRef = useRef(onRequestAlternative);
+  alternativeRef.current = onRequestAlternative;
 
   // `onChange` fires from an effect rather than from inside a state updater.
   // An updater can be replayed during a render, and calling a parent's setState
   // from there is the "cannot update a component while rendering a different
   // component" warning — earned, not spurious.
   const reported = useRef(0);
+  const changeKind = useRef<SignatureChangeKind>('draw');
   useEffect(() => {
     if (reported.current === strokes.length) return;
+    const previous = reported.current;
     reported.current = strokes.length;
     changeRef.current?.(strokes.length);
+    const announcement = signatureAnnouncement(
+      previous,
+      strokes.length,
+      changeKind.current
+    );
+    if (announcement) AccessibilityInfo.announceForAccessibility(announcement);
   }, [strokes.length]);
 
   const commit = useCallback((d: string) => {
+    changeKind.current = 'draw';
     setStrokes((current) => [...current, d]);
     // Drawing again is a new branch of history, so what was undone is gone.
     setUndone([]);
@@ -419,28 +452,37 @@ function SignatureRoot(
     [layout.height, layout.width]
   );
 
+  const clear = useCallback(() => {
+    changeKind.current = 'clear';
+    setStrokes([]);
+    setUndone([]);
+  }, []);
+
+  const undo = useCallback(() => {
+    const last = strokes[strokes.length - 1];
+    if (last === undefined) return;
+    changeKind.current = 'undo';
+    setUndone((stack) => [...stack, last]);
+    setStrokes(strokes.slice(0, -1));
+  }, [strokes]);
+
+  const redo = useCallback(() => {
+    const restored = undone[undone.length - 1];
+    if (restored === undefined) return;
+    changeKind.current = 'redo';
+    setUndone(undone.slice(0, -1));
+    setStrokes([...strokes, restored]);
+  }, [strokes, undone]);
+
   useImperativeHandle(
     ref,
     (): SignatureHandle => ({
       // These read the current arrays and set flat values rather than nesting
       // one updater inside another — a nested updater runs during the render
       // pass, which is not a safe place to schedule another component's update.
-      clear() {
-        setStrokes([]);
-        setUndone([]);
-      },
-      undo() {
-        const last = strokes[strokes.length - 1];
-        if (last === undefined) return;
-        setUndone((stack) => [...stack, last]);
-        setStrokes(strokes.slice(0, -1));
-      },
-      redo() {
-        const restored = undone[undone.length - 1];
-        if (restored === undefined) return;
-        setUndone(undone.slice(0, -1));
-        setStrokes([...strokes, restored]);
-      },
+      clear,
+      undo,
+      redo,
       isEmpty: () => strokes.length === 0,
       strokeCount: () => strokes.length,
       toSVG: svgDocument,
@@ -524,10 +566,47 @@ function SignatureRoot(
         };
       },
     }),
-    [layout.height, layout.width, rasterise, strokes, undone, svgDocument]
+    [clear, layout.height, layout.width, rasterise, redo, strokes, svgDocument, undo]
   );
 
   const empty = strokes.length === 0;
+  const padActions = useMemo(
+    () =>
+      disabled
+        ? []
+        : [
+            ...(accessibilityActions ?? []),
+            ...signatureAccessibilityActions(
+              strokes.length,
+              undone.length,
+              Boolean(onRequestAlternative),
+              false
+            ),
+          ],
+    [accessibilityActions, disabled, onRequestAlternative, strokes.length, undone.length]
+  );
+  const handleAccessibilityAction = useCallback(
+    (event: AccessibilityActionEvent) => {
+      if (disabled) return;
+      switch (event.nativeEvent.actionName) {
+        case 'signature-undo':
+          undo();
+          return;
+        case 'signature-redo':
+          redo();
+          return;
+        case 'signature-clear':
+          clear();
+          return;
+        case 'signature-alternative':
+          alternativeRef.current?.();
+          return;
+        default:
+          onAccessibilityAction?.(event);
+      }
+    },
+    [clear, disabled, onAccessibilityAction, redo, undo]
+  );
 
   return (
     <View className={slots.root({ className })} {...props}>
@@ -541,9 +620,17 @@ function SignatureRoot(
           onLayout={(event) => setLayout(event.nativeEvent.layout)}
           accessible
           accessibilityRole="image"
-          accessibilityLabel="Signature pad"
-          accessibilityHint="Draw your signature with your finger"
+          accessibilityLabel={accessibilityLabel ?? 'Signature pad'}
+          accessibilityHint={
+            accessibilityHint ??
+            (onRequestAlternative
+              ? 'Direct touch drawing requires tracing a path. Use actions to edit or choose another signature method.'
+              : 'Direct touch drawing requires tracing a path. Use actions to undo, redo, or clear strokes.')
+          }
           accessibilityState={{ disabled }}
+          accessibilityValue={signatureAccessibilityValue(strokes.length)}
+          accessibilityActions={padActions}
+          onAccessibilityAction={handleAccessibilityAction}
         >
           {guideline && layout.height > 0 ? (
             <View