Enable exactOptionalPropertyTypes support (#4012)

## Description

This PR enables TypeScript's
[`exactOptionalPropertyTypes`](https://www.typescriptlang.org/tsconfig/#exactOptionalPropertyTypes)
flag in `react-native-gesture-handler` and fixes all 60 resulting type
errors across 22 files.

`exactOptionalPropertyTypes` is a strict TypeScript flag (not included
in `strict: true`) that distinguishes between "property is missing" and
"property is explicitly `undefined`". When enabled, `prop?: T` means the
property can be omitted but cannot be set to `undefined` — the fix is
`prop?: T | undefined`.

This matters for downstream projects that enable this flag — without
this change, they get type errors when using gesture-handler components.
This is currently blocking [react-navigation from enabling the
flag](react-navigation/react-navigation#12995).

### What changed

Three categories of fixes across v2 (class-based), v3 (hooks-based), and
web handler code:

1. **Type declarations** — Added `| undefined` to optional properties in
interfaces and types (`HitSlop`, `CommonGestureConfig`,
`BaseGestureHandlerProps`, `ButtonProps`, `ExternalRelations`,
`VirtualChild`, `IGestureHandler`, etc.)

2. **Class property types** — Updated class property declarations in
`GestureHandler.ts` to include `| undefined` for optional config
properties (`_testID`, `hitSlop`, `mouseButton`, `_activeCursor`, etc.)

3. **`WithSharedValueRecursive` mapped type** — Fixed the boolean
special case in `ReanimatedTypes.ts` to preserve `undefined` from
optional properties using `| Extract<T[K], undefined>`

All changes are type annotations only — zero runtime changes.

### Codegen compatibility

The `src/specs/` files are consumed by `@react-native/codegen`. One spec
file was modified (`RNGestureHandlerDetectorNativeComponent.ts` — 7
`DirectEventHandler` event props). Adding `| undefined` to these is safe
— the codegen parser
([`parseTopLevelType.js`](https://github.com/facebook/react-native/blob/main/packages/react-native-codegen/src/parsers/typescript/parseTopLevelType.js))
explicitly strips `undefined` from union types and treats the result
identically to `prop?: T`.

I verified that the codegen schema output is **byte-identical** between
`main` and this branch:
```bash
node node_modules/@react-native/codegen/lib/cli/combine/combine-js-to-schema-cli.js \
  /tmp/schema.json --libraryName rngesturehandler_codegen \
  packages/react-native-gesture-handler/src/specs/RNGestureHandlerDetectorNativeComponent.ts \
  packages/react-native-gesture-handler/src/specs/RNGestureHandlerButtonNativeComponent.ts
```

## Test plan

All quality gates pass:

- `yarn workspace react-native-gesture-handler ts-check` — 0 errors
- `yarn workspace react-native-gesture-handler lint-js` — 0 errors
- `yarn workspace react-native-gesture-handler test` — 5 suites, 41
tests pass
- `yarn workspace react-native-gesture-handler
circular-dependency-check` — pass

Author: YevheniiKotyrlo

packages/react-native-gesture-handler/src/components/GestureButtonsProps.ts

@@ -18,42 +18,42 @@ export interface LegacyRawButtonProps
    * Defines if more than one button could be pressed simultaneously. By default
    * set true.
    */
-  exclusive?: boolean;
+  exclusive?: boolean | undefined;
   // TODO: we should transform props in `createNativeWrapper`
   /**
    * Android only.
    *
    * Defines color of native ripple animation used since API level 21.
    */
-  rippleColor?: number | ColorValue | null;
+  rippleColor?: number | ColorValue | null | undefined;
 
   /**
    * Android only.
    *
    * Defines radius of native ripple animation used since API level 21.
    */
-  rippleRadius?: number | null;
+  rippleRadius?: number | null | undefined;
 
   /**
    * Android only.
    *
    * Set this to true if you want the ripple animation to render outside the view bounds.
    */
-  borderless?: boolean;
+  borderless?: boolean | undefined;
 
   /**
    * Android only.
    *
    * Defines whether the ripple animation should be drawn on the foreground of the view.
    */
-  foreground?: boolean;
+  foreground?: boolean | undefined;
 
   /**
    * Android only.
    *
    * Set this to true if you don't want the system to play sound when the button is pressed.
    */
-  touchSoundDisabled?: boolean;
+  touchSoundDisabled?: boolean | undefined;
 
   /**
    * Style object, use it to set additional styles.
@@ -70,31 +70,31 @@ export interface LegacyRawButtonProps
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPress?: Function | null;
+  testOnly_onPress?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPressIn?: Function | null;
+  testOnly_onPressIn?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPressOut?: Function | null;
+  testOnly_onPressOut?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onLongPress?: Function | null;
+  testOnly_onLongPress?: Function | null | undefined;
 }
 interface ButtonWithRefProps {
-  innerRef?: React.ForwardedRef<React.ComponentType<any>>;
+  innerRef?: React.ForwardedRef<React.ComponentType<any>> | undefined;
 }
 
 /**
@@ -105,28 +105,28 @@ export interface LegacyBaseButtonProps extends LegacyRawButtonProps {
    * Called when the button gets pressed (analogous to `onPress` in
    * `TouchableHighlight` from RN core).
    */
-  onPress?: (pointerInside: boolean) => void;
+  onPress?: ((pointerInside: boolean) => void) | undefined;
 
   /**
    * Called when the button gets pressed and is held for `delayLongPress`
    * milliseconds.
    */
-  onLongPress?: () => void;
+  onLongPress?: (() => void) | undefined;
 
   /**
    * Called when button changes from inactive to active and vice versa. It
    * passes active state as a boolean variable as a first parameter for that
    * method.
    */
-  onActiveStateChange?: (active: boolean) => void;
+  onActiveStateChange?: ((active: boolean) => void) | undefined;
   style?: StyleProp<ViewStyle>;
-  testID?: string;
+  testID?: string | undefined;
 
   /**
    * Delay, in milliseconds, after which the `onLongPress` callback gets called.
    * Defaults to 600.
    */
-  delayLongPress?: number;
+  delayLongPress?: number | undefined;
 }
 export interface BaseButtonWithRefProps
   extends LegacyBaseButtonProps,
@@ -139,14 +139,14 @@ export interface LegacyRectButtonProps extends LegacyBaseButtonProps {
   /**
    * Background color that will be dimmed when button is in active state.
    */
-  underlayColor?: string;
+  underlayColor?: string | undefined;
 
   /**
    * iOS only.
    *
    * Opacity applied to the underlay when button is in active state.
    */
-  activeOpacity?: number;
+  activeOpacity?: number | undefined;
 }
 export interface RectButtonWithRefProps
   extends LegacyRectButtonProps,
@@ -162,7 +162,7 @@ export interface LegacyBorderlessButtonProps extends LegacyBaseButtonProps {
    *
    * Opacity applied to the button when it is in an active state.
    */
-  activeOpacity?: number;
+  activeOpacity?: number | undefined;
 }
 export interface BorderlessButtonWithRefProps
   extends LegacyBorderlessButtonProps,

packages/react-native-gesture-handler/src/components/GestureHandlerButton.tsx

@@ -19,48 +19,48 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
   /**
    * Defines if buttons should respond to touches. By default set to true.
    */
-  enabled?: boolean;
+  enabled?: boolean | undefined;
 
   /**
    * Defines if more than one button could be pressed simultaneously. By default
    * set true.
    */
-  exclusive?: boolean;
+  exclusive?: boolean | undefined;
 
   /**
    * Android only.
    *
    * Defines color of native ripple animation used since API level 21.
    */
-  rippleColor?: number | ColorValue | null;
+  rippleColor?: number | ColorValue | null | undefined;
 
   /**
    * Android only.
    *
    * Defines radius of native ripple animation used since API level 21.
    */
-  rippleRadius?: number | null;
+  rippleRadius?: number | null | undefined;
 
   /**
    * Android only.
    *
    * Set this to true if you want the ripple animation to render outside the view bounds.
    */
-  borderless?: boolean;
+  borderless?: boolean | undefined;
 
   /**
    * Android only.
    *
    * Defines whether the ripple animation should be drawn on the foreground of the view.
    */
-  foreground?: boolean;
+  foreground?: boolean | undefined;
 
   /**
    * Android only.
    *
    * Set this to true if you don't want the system to play sound when the button is pressed.
    */
-  touchSoundDisabled?: boolean;
+  touchSoundDisabled?: boolean | undefined;
 
   /**
    * Style object, use it to set additional styles.
@@ -77,28 +77,28 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPress?: Function | null;
+  testOnly_onPress?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPressIn?: Function | null;
+  testOnly_onPressIn?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onPressOut?: Function | null;
+  testOnly_onPressOut?: Function | null | undefined;
 
   /**
    * Used for testing-library compatibility, not passed to the native component.
    * @deprecated test-only props are deprecated and will be removed in the future.
    */
   // eslint-disable-next-line @typescript-eslint/ban-types
-  testOnly_onLongPress?: Function | null;
+  testOnly_onLongPress?: Function | null | undefined;
 }
 
 const ButtonComponent =

packages/react-native-gesture-handler/src/components/Pressable/PressableProps.tsx

@@ -26,7 +26,7 @@ export type InnerPressableEvent = {
   target: number;
   timestamp: number;
   touches: InnerPressableEvent[];
-  force?: number;
+  force?: number | undefined;
 };
 
 export type PressableEvent = { nativeEvent: InnerPressableEvent };

packages/react-native-gesture-handler/src/components/touchables/ExtraButtonProps.ts

@@ -1,7 +1,7 @@
 export type ExtraButtonProps = {
-  borderless?: boolean;
-  rippleColor?: number | string | null;
-  rippleRadius?: number | null;
-  foreground?: boolean;
-  exclusive?: boolean;
+  borderless?: boolean | undefined;
+  rippleColor?: number | string | null | undefined;
+  rippleRadius?: number | null | undefined;
+  foreground?: boolean | undefined;
+  exclusive?: boolean | undefined;
 };

packages/react-native-gesture-handler/src/components/touchables/TouchableHighlight.tsx

@@ -12,10 +12,10 @@ import {
 
 interface State {
   extraChildStyle: null | {
-    opacity?: number;
+    opacity?: number | undefined;
   };
   extraUnderlayStyle: null | {
-    backgroundColor?: ColorValue;
+    backgroundColor?: ColorValue | undefined;
   };
 }
 

packages/react-native-gesture-handler/src/handlers/GestureHandlerEventPayload.ts

@@ -129,7 +129,7 @@ export type PanGestureHandlerEventPayload = {
   /**
    * Object containing additional stylus data.
    */
-  stylusData?: StylusData;
+  stylusData?: StylusData | undefined;
 };
 
 export type PinchGestureHandlerEventPayload = {
@@ -225,5 +225,5 @@ export type HoverGestureHandlerEventPayload = {
   /**
    * Object containing additional stylus data.
    */
-  stylusData?: StylusData;
+  stylusData?: StylusData | undefined;
 };

packages/react-native-gesture-handler/src/handlers/NativeViewGestureHandler.ts

@@ -17,13 +17,13 @@ export interface NativeViewGestureConfig {
    * Determines whether the handler should check for an existing touch event on
    * instantiation.
    */
-  shouldActivateOnStart?: boolean;
+  shouldActivateOnStart?: boolean | undefined;
 
   /**
    * When `true`, cancels all other gesture handlers when this
    * `NativeViewGestureHandler` receives an `ACTIVE` state event.
    */
-  disallowInterruption?: boolean;
+  disallowInterruption?: boolean | undefined;
 }
 
 /**

packages/react-native-gesture-handler/src/handlers/gestureHandlerCommon.ts

@@ -63,7 +63,7 @@ export type HitSlop =
   | Partial<
       Record<
         'left' | 'right' | 'top' | 'bottom' | 'vertical' | 'horizontal',
-        number
+        number | undefined
       >
     >
   | Record<'width' | 'left', number>
@@ -181,39 +181,41 @@ export type GestureStateChangeEvent<
 > = HandlerStateChangeEventPayload & GestureStateChangeEventPayloadT;
 
 export type CommonGestureConfig = {
-  enabled?: boolean;
-  shouldCancelWhenOutside?: boolean;
-  hitSlop?: HitSlop;
-  userSelect?: UserSelect;
-  activeCursor?: ActiveCursor;
-  mouseButton?: MouseButton;
-  enableContextMenu?: boolean;
-  touchAction?: TouchAction;
+  enabled?: boolean | undefined;
+  shouldCancelWhenOutside?: boolean | undefined;
+  hitSlop?: HitSlop | undefined;
+  userSelect?: UserSelect | undefined;
+  activeCursor?: ActiveCursor | undefined;
+  mouseButton?: MouseButton | undefined;
+  enableContextMenu?: boolean | undefined;
+  touchAction?: TouchAction | undefined;
 };
 
 // Events payloads are types instead of interfaces due to TS limitation.
 // See https://github.com/microsoft/TypeScript/issues/15300 for more info.
 export type BaseGestureHandlerProps<
   ExtraEventPayloadT extends Record<string, unknown> = Record<string, unknown>,
 > = CommonGestureConfig & {
-  id?: string;
-  waitFor?: React.Ref<unknown> | React.Ref<unknown>[];
-  simultaneousHandlers?: React.Ref<unknown> | React.Ref<unknown>[];
-  blocksHandlers?: React.Ref<unknown> | React.Ref<unknown>[];
-  testID?: string;
-  cancelsTouchesInView?: boolean;
+  id?: string | undefined;
+  waitFor?: React.Ref<unknown> | React.Ref<unknown>[] | undefined;
+  simultaneousHandlers?: React.Ref<unknown> | React.Ref<unknown>[] | undefined;
+  blocksHandlers?: React.Ref<unknown> | React.Ref<unknown>[] | undefined;
+  testID?: string | undefined;
+  cancelsTouchesInView?: boolean | undefined;
   // TODO(TS) - fix event types
-  onBegan?: (event: HandlerStateChangeEvent) => void;
-  onFailed?: (event: HandlerStateChangeEvent) => void;
-  onCancelled?: (event: HandlerStateChangeEvent) => void;
-  onActivated?: (event: HandlerStateChangeEvent) => void;
-  onEnded?: (event: HandlerStateChangeEvent) => void;
+  onBegan?: ((event: HandlerStateChangeEvent) => void) | undefined;
+  onFailed?: ((event: HandlerStateChangeEvent) => void) | undefined;
+  onCancelled?: ((event: HandlerStateChangeEvent) => void) | undefined;
+  onActivated?: ((event: HandlerStateChangeEvent) => void) | undefined;
+  onEnded?: ((event: HandlerStateChangeEvent) => void) | undefined;
 
   // TODO(TS) consider using NativeSyntheticEvent
-  onGestureEvent?: (event: GestureEvent<ExtraEventPayloadT>) => void;
-  onHandlerStateChange?: (
-    event: HandlerStateChangeEvent<ExtraEventPayloadT>
-  ) => void;
+  onGestureEvent?:
+    | ((event: GestureEvent<ExtraEventPayloadT>) => void)
+    | undefined;
+  onHandlerStateChange?:
+    | ((event: HandlerStateChangeEvent<ExtraEventPayloadT>) => void)
+    | undefined;
   // Implicit `children` prop has been removed in @types/react^18.0.0
   children?: React.ReactNode;
 };