refactor(PaperProvider): add reduceMotion prop and useReduceMotion hook

[adrcotfas]

Motivation

The library's existing reduce-motion support set animation.scale = 0 -- a v2-era flag that components had to explicitly check, with no connection to the MD3 theme.motion spring and duration tokens.

This PR wires OS accessibility into the theme properly. useAccessibleTheme replaces the inline PaperProvider logic, subscribes to reduceMotionChanged, and when active collapses theme.motion to instant springs and zero durations via the new reducedMotion preset. A clean theme.motion.prefersReducedMotion: boolean flag gives components a single readable signal instead of the magic scale === 0 check.

animation.scale is kept and still set to 0 for backward compatibility with components that haven't migrated yet. It is now formally deprecated in favour of theme.motion.prefersReducedMotion.

Two further deprecations are added while here: theme.mode ('adaptive' | 'exact'), which is an MD2 elevation-overlay concept superseded by tonal surface colors in theme.colors.elevation.*; and animation.defaultAnimationDuration, which was never read at runtime.
No component behavior changes. The reduce-motion path is functionally equivalent to before for all existing components. theme.motion.prefersReducedMotion and the reducedMotion preset are foundation plumbing -- they will be consumed when components migrate to theme.motion tokens in the per-component PRs that follow.

Related issue

See https://www.notion.so/callstack/React-Native-Paper-Foundation-for-MD3-Expressive-34c5d027c0f880edba3df107cd35946f?source=copy_link

Merge order:

• refactor: remove MD3 prefix and use deprecated aliases #4910
• refactor: move styles/ into src/theme/ tree #4915
• refactor: add color role table and buildScheme #4916
• feat: add theme.state opacity tokens and split theme types #4917
• feat: add theme.shapes and cornersToStyle #4919
• feat: add emphasized typescale and fix letter-spacing spec bugs #4920
• feat: add motion tokens (spring, easing, duration) #4922
• feat: add elevation tokens and fix Android dp spec bug #4923
• refactor(PaperProvider): add reduceMotion prop and useReduceMotion hook #4924
• refactor(theme): consolidate DynamicTheme role map and drop DefaultTheme export #4925
• refactor: replace string with ColorValue for ThemeColors #4945
• feat(v6): remove deprecated public API #4926
• docs: update documentation #4927

Test plan

• yarn typescript -- no new type errors
• yarn test -- all tests pass

[callstack-bot]

Hey @adrcotfas, thank you for your pull request 🤗. The documentation from this branch can be viewed here.

[github-actions]

The mobile version of example app from this branch is ready! You can see it here.

[satya164]

I don't think this should be wrapping theme in useTheme. This causes every component using this hook to subscribe to reduce motion.

If this is handled, then it should be done in PaperProvider in a single place so there's a single subscription.

But also, if prefersReducedMotion is in the theme, it conflicts with such an API if it's also handled internally. When the user passes a theme, which will already have prefersReducedMotion, is it also handled internally and overridden?

It probably makes sense to expose a separate prop reduceMotion="auto" or something like that on PaperProvider, then internally it can subscribe and expose the actual value in context. Then, on the component level, components can adapt their animations to reduce motion when necessary.

There is also the problem of the value not being known on initial render, as it's async, so if some component has animation on render, it won't properly respect this.

[adrcotfas]

I refactored that part. Previously we had a bug because the reduce motion handling was listener only. The state stayed false forever until the user toggled reduce motion in the OS during the running session.
Now one frame is still wrong. Do we accept that for now or do you see a solution? Native modules might be an overkill for this edge case.

[satya164]

@adrcotfas i guess it's acceptable for now as it's rare to have motion animation fr initial render. there's also option to create native module but keep it optional, and fallback to react native's API if it's unavailable. i don't see another option.

[satya164]

Avoid as as it's not typesafe. A return type annotation on the function should handle it.

[adrcotfas]

My bad for that - the cast was wrong but there was a pre-existing issue here so I reverted it.
A return annotation doesn't actually fix it though: props.theme is a deep-partial, so the shallow spread overwrites colors/fonts/motion/elevation with partials, and (): Theme => rejects the body for that reason.
Will fix properly (deep-merge per top-level key) in a follow-up.