feat: add accessibility adaptation layer

Author: adrcotfas

src/core/PaperProvider.tsx

@@ -1,34 +1,36 @@
 import * as React from 'react';
-import {
-  AccessibilityInfo,
-  Appearance,
-  ColorSchemeName,
-  NativeEventSubscription,
-} from 'react-native';
+import { Appearance, ColorSchemeName } from 'react-native';
 
 import SafeAreaProviderCompat from './SafeAreaProviderCompat';
 import { Provider as SettingsProvider, Settings } from './settings';
 import { defaultThemes, ThemeProvider } from './theming';
 import MaterialCommunityIcon from '../components/MaterialCommunityIcon';
 import PortalHost from '../components/Portal/PortalHost';
-import type { ThemeProp } from '../types';
-import { addEventListener } from '../utils/addEventListener';
+import { ReduceMotionContext } from '../theme/accessibility/ReduceMotionContext';
+import {
+  useResolvedReduceMotion,
+  type ReduceMotionPreference,
+} from '../theme/accessibility/useResolvedReduceMotion';
+import type { Theme, ThemeProp } from '../types';
 
 export type Props = {
   children: React.ReactNode;
   theme?: ThemeProp;
   settings?: Settings;
+  reduceMotion?: ReduceMotionPreference;
 };
 
 const PaperProvider = (props: Props) => {
+  const { reduceMotion = 'auto' } = props;
+
   const colorSchemeName =
     (!props.theme && Appearance?.getColorScheme()) || 'light';
 
-  const [reduceMotionEnabled, setReduceMotionEnabled] =
-    React.useState<boolean>(false);
   const [colorScheme, setColorScheme] =
     React.useState<ColorSchemeName>(colorSchemeName);
 
+  const resolvedReduceMotion = useResolvedReduceMotion(reduceMotion);
+
   const handleAppearanceChange = (
     preferences: Appearance.AppearancePreferences
   ) => {
@@ -37,28 +39,13 @@ const PaperProvider = (props: Props) => {
   };
 
   React.useEffect(() => {
-    let subscription: NativeEventSubscription | undefined;
-
-    if (!props.theme) {
-      subscription = addEventListener(
-        AccessibilityInfo,
-        'reduceMotionChanged',
-        setReduceMotionEnabled
-      );
-    }
-    return () => {
-      if (!props.theme) {
-        subscription?.remove();
-      }
-    };
-  }, [props.theme]);
-
-  React.useEffect(() => {
-    let appearanceSubscription: NativeEventSubscription | undefined;
+    let appearanceSubscription:
+      | ReturnType<typeof Appearance.addChangeListener>
+      | undefined;
     if (!props.theme) {
       appearanceSubscription = Appearance?.addChangeListener(
         handleAppearanceChange
-      ) as NativeEventSubscription | undefined;
+      ) as typeof appearanceSubscription;
     }
     return () => {
       if (!props.theme) {
@@ -72,19 +59,18 @@ const PaperProvider = (props: Props) => {
     };
   }, [props.theme]);
 
-  const theme = React.useMemo(() => {
+  const theme = React.useMemo<Theme>(() => {
     const scheme = colorScheme === 'dark' ? 'dark' : 'light';
-    const defaultThemeBase = defaultThemes[scheme];
-
+    const base = defaultThemes[scheme];
     return {
-      ...defaultThemeBase,
+      ...base,
       ...props.theme,
       animation: {
         ...props.theme?.animation,
-        scale: reduceMotionEnabled ? 0 : 1,
+        scale: resolvedReduceMotion ? 0 : props.theme?.animation?.scale ?? 1,
       },
-    };
-  }, [colorScheme, props.theme, reduceMotionEnabled]);
+    } as Theme;
+  }, [colorScheme, props.theme, resolvedReduceMotion]);
 
   const { children, settings } = props;
 
@@ -101,7 +87,9 @@ const PaperProvider = (props: Props) => {
     <SafeAreaProviderCompat>
       <PortalHost>
         <SettingsProvider value={settingsValue}>
-          <ThemeProvider theme={theme}>{children}</ThemeProvider>
+          <ReduceMotionContext.Provider value={resolvedReduceMotion}>
+            <ThemeProvider theme={theme}>{children}</ThemeProvider>
+          </ReduceMotionContext.Provider>
         </SettingsProvider>
       </PortalHost>
     </SafeAreaProviderCompat>

src/core/__tests__/PaperProvider.test.tsx

@@ -82,6 +82,7 @@ const mockAccessibilityInfo = () => {
           removeEventListener: jest.fn((cb) => {
             listeners.push(cb);
           }),
+          isReduceMotionEnabled: jest.fn(() => Promise.resolve(false)),
           __internalListeners: listeners,
         },
       };
@@ -122,11 +123,11 @@ describe('PaperProvider', () => {
     );
   });
 
-  it('should set AccessibilityInfo listeners, if there is no theme', async () => {
+  it('subscribes to AccessibilityInfo and adapts theme.animation.scale when OS reduce-motion is enabled (auto mode)', async () => {
     mockAppearance();
     mockAccessibilityInfo();
 
-    const { rerender, getByTestId } = render(createProvider());
+    const { getByTestId } = render(createProvider());
 
     expect(AccessibilityInfo.addEventListener).toHaveBeenCalled();
     act(() =>
@@ -138,20 +139,36 @@ describe('PaperProvider', () => {
     expect(
       getByTestId('provider-child-view').props.theme.animation.scale
     ).toStrictEqual(0);
-
-    rerender(createProvider(ExtendedLightTheme));
-    expect(AccessibilityInfo.removeEventListener).toHaveBeenCalled();
   });
 
-  it('should not set AccessibilityInfo listeners, if there is a theme', async () => {
+  it('does not subscribe to AccessibilityInfo when reduceMotion is "off"', async () => {
     mockAppearance();
-    const { getByTestId } = render(createProvider(ExtendedDarkTheme));
+    mockAccessibilityInfo();
+    const { getByTestId } = render(
+      <PaperProvider theme={ExtendedDarkTheme} reduceMotion="off">
+        <FakeChild />
+      </PaperProvider>
+    );
 
     expect(AccessibilityInfo.addEventListener).not.toHaveBeenCalled();
-    expect(AccessibilityInfo.removeEventListener).not.toHaveBeenCalled();
-    expect(getByTestId('provider-child-view').props.theme).toStrictEqual(
-      ExtendedDarkTheme
+    expect(
+      getByTestId('provider-child-view').props.theme.animation.scale
+    ).toStrictEqual(1);
+  });
+
+  it('forces animation.scale to 0 when reduceMotion is "on" without subscribing', async () => {
+    mockAppearance();
+    mockAccessibilityInfo();
+    const { getByTestId } = render(
+      <PaperProvider reduceMotion="on">
+        <FakeChild />
+      </PaperProvider>
     );
+
+    expect(AccessibilityInfo.addEventListener).not.toHaveBeenCalled();
+    expect(
+      getByTestId('provider-child-view').props.theme.animation.scale
+    ).toStrictEqual(0);
   });
 
   it('should set Appearance listeners, if there is no theme', async () => {

src/theme/accessibility/ReduceMotionContext.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+export const ReduceMotionContext = React.createContext<boolean>(false);
+
+/**
+ * Returns `true` when the user has requested reduced motion, either via the
+ * `reduceMotion` prop on `PaperProvider` (`"on"` | `"off"`) or, in `"auto"`
+ * mode (the default), via the OS-level setting reported by `AccessibilityInfo`.
+ *
+ * Use this in component code to gate motion-specific animations (translation,
+ * scale, transforms) while keeping non-motion animations (opacity, color) intact.
+ */
+export function useReduceMotion(): boolean {
+  return React.useContext(ReduceMotionContext);
+}

src/theme/accessibility/useResolvedReduceMotion.ts

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+import { addEventListener } from '../../utils/addEventListener';
+
+export type ReduceMotionPreference = 'auto' | 'on' | 'off';
+
+/**
+ * Resolves a reduce-motion preference into a boolean.
+ *
+ * - `'on'` / `'off'` are explicit overrides.
+ * - `'auto'` subscribes to `AccessibilityInfo.reduceMotionChanged` and follows
+ *   the OS-level setting.
+ *
+ * `AccessibilityInfo.isReduceMotionEnabled()` is async, so the first render
+ * returns `false` for one frame regardless of OS state.
+ */
+export function useResolvedReduceMotion(
+  preference: ReduceMotionPreference
+): boolean {
+  const [osReduceMotion, setOsReduceMotion] = React.useState(false);
+
+  React.useEffect(() => {
+    if (preference !== 'auto') return;
+    let cancelled = false;
+
+    const init = async () => {
+      const v = await AccessibilityInfo.isReduceMotionEnabled?.();
+      if (!cancelled && v != null) setOsReduceMotion(v);
+    };
+    void init();
+
+    const sub = addEventListener(
+      AccessibilityInfo,
+      'reduceMotionChanged',
+      setOsReduceMotion
+    );
+    return () => {
+      cancelled = true;
+      sub.remove();
+    };
+  }, [preference]);
+
+  if (preference === 'on') return true;
+  if (preference === 'off') return false;
+  return osReduceMotion;
+}

src/theme/types/theme.ts

@@ -10,6 +10,7 @@ type Mode = 'adaptive' | 'exact';
 
 export type ThemeBase = {
   dark: boolean;
+  /** @deprecated Will be removed in a future version. MD3 uses tonal surface colors via `theme.colors.elevation.*`. */
   mode?: Mode;
   animation: {
     scale: number;