useReducedMotion hook

1'use client';
2 
3import { useCallback, useSyncExternalStore } from 'react';
4 
5// @interlace/use-reduced-motion v1.1.0 — Interlace design system.
6// Docs, props and live preview: https://ds.interlace.tools/c/use-reduced-motion
7// What changed since: https://ds.interlace.tools/c/use-reduced-motion#history
8// Generated banner — keep it, the upgrade diff reads this version.
9 
10const QUERY = '(prefers-reduced-motion: reduce)';
11 
12/**
13 * Returns `true` when the user has `prefers-reduced-motion: reduce` set.
14 *
15 * Use to gate motion-heavy components: animation should be disabled or
16 * dramatically reduced when this returns `true`.
17 *
18 * ## Why `useSyncExternalStore` and not `useState` + `useEffect`
19 *
20 * The canonical hook — the one MUI, Vercel, Linear and Stripe all ship — is
21 * `useState(false)` plus an effect that calls `matchMedia` on mount. It is
22 * SSR-safe, and it is **one frame late**: the first render always returns
23 * `false`, so a component that gates on it paints its animated first frame and
24 * only then snaps to the still state.
25 *
26 * For most gates that is invisible. For the ones this package ships it is not —
27 * the frame that gets painted is `AnimatedList`'s `scale: 0`, `FlipWords`' 8px
28 * blur, `Spotlight`'s `opacity: 0`. A user who set the preference precisely
29 * because motion makes them ill gets one frame of exactly the motion they
30 * turned off, on every mount. WCAG 2.3.3 is not satisfied by "briefly".
31 *
32 * `useSyncExternalStore` reads the store DURING the first render, so on a
33 * client-rendered mount — which is where every decorative component in this
34 * package actually lives — the first painted frame is already correct.
35 *
36 * **The honest statement is that this closes the gap on CSR and cannot close it
37 * on hydration.** The server genuinely cannot know the preference, so
38 * `getServerSnapshot` must return `false` and the hydration frame is
39 * unavoidable for any JavaScript hook. The only thing that closes THAT is CSS,
40 * which is why `preflight.css` clamps `animation-duration` and
41 * `transition-duration` under `reduce` for `*`: that reset is live before the
42 * first paint and needs no JavaScript at all.
43 *
44 * So this hook is for the motion CSS cannot reach — `motion/react`,
45 * `requestAnimationFrame`, timer-driven steps. The registry publishes that
46 * split per component as `a11y.motion.driver`.
47 *
48 * @example
49 * ```tsx
50 * const reduceMotion = useReducedMotion();
51// … truncated