pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/core/motion/MODULE.md

@@ -1,4 +1,4 @@
-# core/motion
+# core/motion — the one global animation gate
 
 The single global control for every animation in the library. **Internal only** — nothing here is
 exported from the package, so a consumer app cannot (and does not need to) configure motion. You
@@ -11,9 +11,9 @@ Edit **`config.ts`**. Nothing else.
 | Knob | Effect |
 |---|---|
 | `MOTION_ENABLED` | `false` kills every animation library-wide. Components render their final state instantly. |
-| `MOTION_SCALE` | Global speed dial. `0.5` = everything twice as fast, `2` = twice as slow. The fastest way to feel a change across all 72 components. |
+| `MOTION_SCALE` | Global speed dial. `0.5` = everything twice as fast, `2` = twice as slow. The fastest way to feel a change across every module at once. |
 | `MOTION_DURATION` | The five named speeds. Components never write a raw number. |
-| `MOTION_EASING` | Four curves — `standard`, `decelerate` (entering), `accelerate` (leaving), `emphasized`. |
+| `MOTION_EASING_CURVE` | Six bezier curves — `standard`, `decelerate` (entering), `accelerate` (leaving), `emphasized`, `emphasizedDecelerate`, `emphasizedAccelerate`. Built lazily by `motionEasing(key)`. |
 | `MOTION_SPRING` | Three spring presets, used only where the device tier allows. |
 | `MOTION_TRANSFORM` | Shared magnitudes — press scale, slide offsets, scrim opacity. Keeps every component's motion the same size. |
 | `MOTION_TIER` | Per-device-tier policy: duration scale, whether springs and decorative motion are allowed. |
@@ -30,7 +30,7 @@ const motion = useMotion();
 motion.timing(opacity, 1, { duration: "fast", easing: "decelerate" }).start();
 
 // Snap instead of tween when the user asked for less motion.
-if (!motion.enabled) opacity.setValue(1);
+if (!motion.enabled) opacity.value = 1;
 
 // Decorative motion (shimmer, parallax, stagger) is high-tier only.
 if (motion.decorative) startShimmer();
@@ -41,19 +41,21 @@ Allocate the value itself with **`useAnimatedValue(initial)`**, never
 hands `useRef` one it immediately discards. `initial` is read on the first render only, exactly like
 `useRef`, so the two are interchangeable.
 
-Three ready-made patterns cover most needs:
+Ready-made patterns cover most needs:
 
+- **`usePressState(disabled?)`** — asymmetric press choreography (tween-in scale, spring-out scale
+  + state-layer overlay), width-aware via `onLayout` + `pressScaleFor`. Preferred for pressable
+  modules.
 - **`usePressMotion(disabled?)`** — scale + opacity dip on press. Spread `onPressIn`/`onPressOut`
-  onto the `Pressable` and `style` onto an `Animated.View`. The returned object is `useMemo`'d on the
-  stable `Animated.Value`s, so `press.style` keeps its identity and a consumer `useMemo` keyed on it
-  can hit. **`disabled` allocates nothing** — it returns one shared `{ opacity: 1, transform: [{
-  scale: 1 }] }`, so `list-item` / `stat-tile` rows that are display-only cost no `Animated.Value`
-  at all (5000 rows used to build 10,000 that never moved). `style.opacity` and `style.transform[0]
-  .scale` are therefore `Animated.Value | number`.
+  onto the `Pressable` and `style` onto a Reanimated view.
 - **`useEnterExit(visible, offsetY?)`** — fade + slide a subtree in, and unmount it once the exit
   settles. Returns `{ mounted, style }`.
 - **`useReveal(visible, offsetY?)`** — the same fade + slide for a subtree whose mounting the caller
   already controls. Returns `{ style }` only.
+- **`useFocusRing(focused, disabled?)`** — the shared focus-ring fade; returns
+  `{ focusRingStyle, animateFocus }`.
+- **`runTiming` / `runLoop` / `motionLoop` / `motionParallel`** (`motionAnimation.ts`) — the
+  imperative escape hatch for a loop or a parallel group that is not one of the hooks above.
 
 **Pick between the last two by who owns the unmount.** `useReveal` holds no state, so it costs no
 extra render — but it also never removes anything from the tree. Ignoring `useEnterExit`'s `mounted`
@@ -63,11 +65,13 @@ null`, or an RN `<Modal>`); use `useEnterExit` only when you actually render its
 
 ## The rules any new motion must follow
 
-1. **Animate only `opacity` and `transform`.** Never height, width, margin, padding or
-   `borderColor` — those cannot run on the native driver and force a layout pass every frame. This
-   constraint is the reason the library can animate freely without costing frames on low-end Android.
-2. **Always `useNativeDriver: true`.** One documented exception exists library-wide: `Drawer`'s
-   keyboard-avoidance `paddingBottom` (see `Drawer.tsx:115,122`, and its eslint override).
+1. **Animate paint-only properties — never layout.** `opacity`, `transform`, and (via Reanimated
+   effects springs) `backgroundColor`, `borderColor`, `color`, `shadowColor` are allowed. Never
+   `width`, `height`, `margin`, `padding`, `top`/`left`, or `flex` — those force a layout pass
+   every frame. Spatial motion uses spatial springs; colour/opacity uses effects springs (critically
+   damped, no bounce).
+2. **UI-thread motion.** One documented exception exists library-wide: `Drawer`'s keyboard-avoidance
+   `paddingBottom` (see `Drawer.tsx`, Reanimated animated style).
 3. **Never gate an unmount on the animation reporting `finished`.** An interrupted animation then
    leaves the subtree mounted forever — collapsed content stays in the tree, screen readers still
    read it, and heavy children never release. Drive the unmount from a timer, as `useEnterExit`
@@ -99,3 +103,8 @@ and no decorative motion. High-end gets the full treatment. Reduce-motion overri
 
 `useMotion` calls `resolveDeviceTier(reducedMotion)`, not `useDeviceTier()` — the hook would read
 the reduce-motion store a second time for the same answer.
+
+## Known gotchas
+
+- **`Reanimated.Text` is undefined on web** — types lie; use `AnimatedText` from this module
+  (`createAnimatedComponent(Text)` at module scope). `Reanimated.View` is fine.

package/lib/module/core/motion/animatedComponents.js

@@ -0,0 +1,8 @@
+"use strict";
+
+import { Text } from "react-native";
+import Reanimated from "react-native-reanimated";
+
+/** Web-safe animated text — `Reanimated.Text` is undefined under react-native-web at runtime. */
+export const AnimatedText = Reanimated.createAnimatedComponent(Text);
+//# sourceMappingURL=animatedComponents.js.map

package/lib/module/core/motion/config.js

@@ -35,7 +35,9 @@ export const MOTION_EASING_CURVE = {
   decelerate: [0, 0, 0, 1],
   /** Leaving the screen — soft start, quick exit. */
   accelerate: [0.3, 0, 1, 1],
-  emphasized: [0.2, 0, 0, 1.2]
+  emphasized: [0.05, 0.7, 0.1, 1],
+  emphasizedDecelerate: [0.05, 0.7, 0.1, 1],
+  emphasizedAccelerate: [0.3, 0, 0.8, 0.15]
 };
 let easingCache = {};
 
@@ -72,6 +74,7 @@ export const MOTION_SPRING = {
 };
 
 /** Shared magnitudes so every component's motion reads as one system. */
+export const pressScaleFor = width => 1 - 4 / Math.max(width, 24);
 export const MOTION_TRANSFORM = {
   /** Press scale for buttons, cards, list rows. */
   pressScale: 0.97,

package/lib/module/core/motion/index.js

@@ -1,7 +1,10 @@
 "use strict";
 
-export { MOTION_DURATION, MOTION_EASING_CURVE, MOTION_ENABLED, MOTION_SCALE, MOTION_SPRING, MOTION_TIER, MOTION_TRANSFORM, motionEasing, resetMotionEasingCache, resolveDuration } from "./config.js";
+export { MOTION_DURATION, MOTION_EASING_CURVE, MOTION_ENABLED, MOTION_SCALE, MOTION_SPRING, MOTION_TIER, MOTION_TRANSFORM, motionEasing, pressScaleFor, resetMotionEasingCache, resolveDuration } from "./config.js";
+export { AnimatedText } from "./animatedComponents.js";
 export { useAnimatedValue } from "./useAnimatedValue.js";
 export { useMotion } from "./useMotion.js";
+export { usePressState, useFocusRing } from "./usePressState.js";
 export { useEnterExit, usePressMotion, useReveal } from "./presets.js";
+export { motionLoop, motionParallel, runLoop, runTiming } from "./motionAnimation.js";
 //# sourceMappingURL=index.js.map

package/lib/module/core/motion/motionAnimation.js

@@ -0,0 +1,87 @@
+"use strict";
+
+import { cancelAnimation, withRepeat, withTiming } from "react-native-reanimated";
+export function motionParallel(...animations) {
+  return {
+    start: callback => {
+      for (const animation of animations) animation.start();
+      callback?.({
+        finished: true
+      });
+    },
+    stop: () => {
+      for (const animation of animations) animation.stop();
+    }
+  };
+}
+export function motionLoop(animation) {
+  return {
+    start: callback => {
+      animation.start();
+      callback?.({
+        finished: true
+      });
+    },
+    stop: () => animation.stop()
+  };
+}
+export function runTiming(value, toValue, durationMs, easing, delayMs, snap) {
+  let cancelled = false;
+  return {
+    start: callback => {
+      cancelled = false;
+      if (snap || durationMs === 0) {
+        value.value = toValue;
+        callback?.({
+          finished: true
+        });
+        return;
+      }
+      const apply = () => {
+        value.value = withTiming(toValue, {
+          duration: durationMs,
+          easing
+        });
+      };
+      if (delayMs > 0) {
+        setTimeout(() => {
+          if (!cancelled) apply();
+          callback?.({
+            finished: true
+          });
+        }, delayMs);
+      } else {
+        apply();
+        callback?.({
+          finished: true
+        });
+      }
+    },
+    stop: () => {
+      cancelled = true;
+      cancelAnimation(value);
+    }
+  };
+}
+export function runLoop(value, toValue, durationMs, easing) {
+  return {
+    start: callback => {
+      if (durationMs === 0) {
+        value.value = toValue;
+        callback?.({
+          finished: true
+        });
+        return;
+      }
+      value.value = withRepeat(withTiming(toValue, {
+        duration: durationMs,
+        easing
+      }), -1, true);
+      callback?.({
+        finished: true
+      });
+    },
+    stop: () => cancelAnimation(value)
+  };
+}
+//# sourceMappingURL=motionAnimation.js.map

package/lib/module/core/motion/presets.js

@@ -1,18 +1,12 @@
 "use strict";
 
-/**
- * Ready-made motion for the two patterns that repeat across the library: press feedback, and
- * mount/unmount reveal. Components use these instead of hand-rolling an `Animated.Value` each,
- * so retuning `config.ts` retunes everything.
- */
-
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Animated } from "react-native";
+import { useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { motionParallel } from "./motionAnimation.js";
+import { reanimatedEasing } from "./reanimatedEasing.js";
 import { useAnimatedValue } from "./useAnimatedValue.js";
 import { useMotion } from "./useMotion.js";
 const NOOP = () => undefined;
-
-/** Shared by every disabled caller — `list-item` and `stat-tile` render thousands of these. */
 const PRESS_AT_REST = {
   style: {
     opacity: 1,
@@ -23,101 +17,106 @@ const PRESS_AT_REST = {
   onPressIn: NOOP,
   onPressOut: NOOP
 };
-
-/** Scale + opacity dip on press. Native driver, so it never blocks the JS thread mid-scroll. */
 export function usePressMotion(disabled = false) {
   const motion = useMotion();
-  const values = useRef(null);
-  const running = useRef(null);
-
-  // Lazily allocated: a 5000-row display-only list would otherwise build 10k values that never move.
-  if (!disabled && values.current === null) {
-    values.current = {
-      scale: new Animated.Value(1),
-      opacity: new Animated.Value(1)
-    };
-  }
-  const pressValues = values.current;
+  const scale = useSharedValue(1);
+  const opacity = useSharedValue(1);
+  const [pressed, setPressed] = useState(false);
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{
+      scale: scale.value
+    }]
+  }));
+  const snap = useCallback((toScale, toOpacity) => {
+    scale.value = toScale;
+    opacity.value = toOpacity;
+  }, [opacity, scale]);
   const animate = useCallback((toScale, toOpacity) => {
-    const current = values.current;
-    if (current === null) return;
-    running.current?.stop();
     if (!motion.enabled) {
-      current.scale.setValue(toScale);
-      current.opacity.setValue(toOpacity);
+      snap(toScale, toOpacity);
       return;
     }
-    running.current = Animated.parallel([motion.timing(current.scale, toScale, {
-      duration: "fast"
-    }), motion.timing(current.opacity, toOpacity, {
-      duration: "fast"
-    })]);
-    running.current.start();
-  }, [motion]);
-  useEffect(() => () => running.current?.stop(), []);
+    const durationMs = motion.duration("fast");
+    const easing = reanimatedEasing("standard");
+    scale.value = withTiming(toScale, {
+      duration: durationMs,
+      easing
+    });
+    opacity.value = withTiming(toOpacity, {
+      duration: durationMs,
+      easing
+    });
+  }, [motion, opacity, scale, snap]);
   const onPressIn = useCallback(() => {
     if (disabled) return;
+    if (!motion.enabled) {
+      setPressed(true);
+      return;
+    }
     animate(motion.transform.pressScale, motion.transform.pressOpacity);
-  }, [disabled, animate, motion]);
+  }, [disabled, animate, motion.enabled, motion.transform.pressOpacity, motion.transform.pressScale]);
   const onPressOut = useCallback(() => {
     if (disabled) return;
+    if (!motion.enabled) {
+      setPressed(false);
+      return;
+    }
     animate(1, 1);
-  }, [disabled, animate]);
-
-  // The Animated.Values are stable, but a fresh wrapper each render defeats every consumer
-  // `useMemo` keyed on `press.style`.
-  return useMemo(() => pressValues === null ? PRESS_AT_REST : {
-    style: {
-      opacity: pressValues.opacity,
-      transform: [{
-        scale: pressValues.scale
-      }]
-    },
+  }, [disabled, animate, motion.enabled]);
+  const enabledMotion = useMemo(() => ({
+    style: animatedStyle,
     onPressIn,
     onPressOut
-  }, [pressValues, onPressIn, onPressOut]);
+  }), [animatedStyle, onPressIn, onPressOut]);
+  if (disabled) return PRESS_AT_REST;
+  if (!motion.enabled) {
+    return {
+      style: {
+        opacity: pressed ? motion.transform.pressOpacity : 1,
+        transform: [{
+          scale: pressed ? motion.transform.pressScale : 1
+        }]
+      },
+      onPressIn,
+      onPressOut
+    };
+  }
+  return enabledMotion;
 }
-/**
- * Fade + slide for a subtree whose mounting someone else already controls. Holds no state, so it
- * costs no extra render — use this instead of `useEnterExit` when the caller ignores `mounted`.
- */
 export function useReveal(visible, offsetY) {
   const motion = useMotion();
   const opacity = useAnimatedValue(visible ? 1 : 0);
   const translateY = useAnimatedValue(0);
   const running = useRef(null);
   const distance = offsetY ?? motion.transform.offsetY;
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{
+      translateY: translateY.value
+    }]
+  }));
   useEffect(() => {
     running.current?.stop();
     if (!motion.enabled) {
-      opacity.setValue(visible ? 1 : 0);
-      translateY.setValue(0);
+      opacity.value = visible ? 1 : 0;
+      translateY.value = 0;
       return;
     }
-    running.current = Animated.parallel([motion.timing(opacity, visible ? 1 : 0, {
+    running.current = motionParallel(motion.timing(opacity, visible ? 1 : 0, {
       duration: visible ? "normal" : "fast",
       easing: visible ? "decelerate" : "accelerate"
     }), motion.timing(translateY, visible ? 0 : -distance / 2, {
       duration: visible ? "normal" : "fast",
       easing: visible ? "decelerate" : "accelerate"
-    })]);
+    }));
     running.current.start();
   }, [visible, motion, opacity, translateY, distance]);
   useEffect(() => () => running.current?.stop(), []);
   return {
-    style: {
-      opacity,
-      transform: [{
-        translateY
-      }]
-    }
+    style: animatedStyle
   };
 }
-/**
- * Fade + slide a subtree in, and keep it mounted only until the exit settles. The unmount is
- * driven by a timer, not the animation callback: an interrupted animation must still unmount, or
- * collapsed content leaks into the tree forever.
- */
 export function useEnterExit(visible, offsetY) {
   const motion = useMotion();
   const [mounted, setMounted] = useState(visible);
@@ -127,6 +126,12 @@ export function useEnterExit(visible, offsetY) {
   const running = useRef(null);
   const exitTimer = useRef(null);
   const distance = offsetY ?? motion.transform.offsetY;
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{
+      translateY: translateY.value
+    }]
+  }));
   useEffect(() => {
     const clearExit = () => {
       if (exitTimer.current !== null) {
@@ -140,17 +145,17 @@ export function useEnterExit(visible, offsetY) {
       setMounted(true);
       if (!motion.enabled || skipFirstEnter.current) {
         skipFirstEnter.current = false;
-        opacity.setValue(1);
-        translateY.setValue(0);
+        opacity.value = 1;
+        translateY.value = 0;
         return;
       }
-      opacity.setValue(0);
-      translateY.setValue(-distance);
-      running.current = Animated.parallel([motion.timing(opacity, 1, {
+      opacity.value = 0;
+      translateY.value = -distance;
+      running.current = motionParallel(motion.timing(opacity, 1, {
         easing: "decelerate"
       }), motion.timing(translateY, 0, {
         easing: "decelerate"
-      })]);
+      }));
       running.current.start();
       return;
     }
@@ -160,13 +165,13 @@ export function useEnterExit(visible, offsetY) {
       setMounted(false);
       return;
     }
-    running.current = Animated.parallel([motion.timing(opacity, 0, {
+    running.current = motionParallel(motion.timing(opacity, 0, {
       duration: "fast",
       easing: "accelerate"
     }), motion.timing(translateY, -distance / 2, {
       duration: "fast",
       easing: "accelerate"
-    })]);
+    }));
     running.current.start();
     clearExit();
     exitTimer.current = setTimeout(() => {
@@ -181,12 +186,7 @@ export function useEnterExit(visible, offsetY) {
   }, []);
   return {
     mounted,
-    style: {
-      opacity,
-      transform: [{
-        translateY
-      }]
-    }
+    style: animatedStyle
   };
 }
 //# sourceMappingURL=presets.js.map

package/lib/module/core/motion/reanimatedEasing.js

@@ -0,0 +1,19 @@
+"use strict";
+
+import { Easing } from "react-native-reanimated";
+import { MOTION_EASING_CURVE } from "./config.js";
+const cache = {};
+export function reanimatedEasing(key) {
+  const hit = cache[key];
+  if (hit) return hit;
+  const [x1, y1, x2, y2] = MOTION_EASING_CURVE[key];
+  const built = Easing.bezier(x1, y1, x2, y2);
+  cache[key] = built;
+  return built;
+}
+export function resetReanimatedEasingCache() {
+  for (const key of Object.keys(cache)) {
+    delete cache[key];
+  }
+}
+//# sourceMappingURL=reanimatedEasing.js.map

package/lib/module/core/motion/useAnimatedValue.js

@@ -1,19 +1,7 @@
 "use strict";
 
-import { useRef } from "react";
-import { Animated } from "react-native";
-
-/**
- * A render-stable `Animated.Value`, allocated once.
- *
- * `useRef(new Animated.Value(0))` — the shape this replaces — evaluates its argument on **every**
- * render and hands `useRef` a fresh node it then discards. A list row holding two of them throws
- * away two animated nodes per row per render, which is exactly the churn the press-motion fix
- * removed from `usePressMotion`. `initial` is read on the first render only, matching `useRef`.
- */
+import { useSharedValue } from "react-native-reanimated";
 export function useAnimatedValue(initial) {
-  const ref = useRef(null);
-  ref.current ??= new Animated.Value(initial);
-  return ref.current;
+  return useSharedValue(initial);
 }
 //# sourceMappingURL=useAnimatedValue.js.map

package/lib/module/core/motion/useMotion.js

@@ -1,22 +1,13 @@
 "use strict";
 
-/**
- * The single hook every animated module uses. Resolves the global config in `config.ts` against
- * the device tier and the OS reduce-motion setting, so no component reads a raw duration.
- *
- * Reduce-motion (WCAG 2.3.3) always wins over the tier policy — `enabled` goes false and every
- * duration resolves to 0, so callers can `setValue` instead of tweening.
- */
-
 import { useCallback, useMemo } from "react";
-import { Animated } from "react-native";
 import { useReducedMotion } from "../a11y/index.js";
 import { resolveDeviceTier } from "../device/index.js";
 import { MOTION_ENABLED, MOTION_SPRING, MOTION_TIER, MOTION_TRANSFORM, motionEasing, resolveDuration } from "./config.js";
+import { runLoop, runTiming } from "./motionAnimation.js";
+import { reanimatedEasing } from "./reanimatedEasing.js";
 export function useMotion() {
   const reducedMotion = useReducedMotion();
-  // Resolved rather than `useDeviceTier()`d: that hook reads the same store, and one `useMotion`
-  // must cost one read.
   const tier = useMemo(() => resolveDeviceTier(reducedMotion), [reducedMotion]);
   const duration = useCallback(key => resolveDuration(key, tier, reducedMotion), [tier, reducedMotion]);
   const easing = useCallback(key => motionEasing(key), []);
@@ -24,13 +15,20 @@ export function useMotion() {
     if (!MOTION_ENABLED || reducedMotion || !MOTION_TIER[tier].springs) return null;
     return MOTION_SPRING[key];
   }, [tier, reducedMotion]);
-  const timing = useCallback((value, toValue, options) => Animated.timing(value, {
-    toValue,
-    duration: duration(options?.duration ?? "normal"),
-    easing: motionEasing(options?.easing ?? "standard"),
-    delay: options?.delay ?? 0,
-    useNativeDriver: true
-  }), [duration]);
+  const timing = useCallback((value, toValue, options) => {
+    const durationMs = duration(options?.duration ?? "normal");
+    const easingKey = options?.easing ?? "standard";
+    const snap = !MOTION_ENABLED || reducedMotion || durationMs === 0;
+    return runTiming(value, toValue, durationMs, reanimatedEasing(easingKey), options?.delay ?? 0, snap);
+  }, [duration, reducedMotion]);
+  const loop = useCallback((value, toValue, options) => {
+    const durationMs = duration(options?.duration ?? "deliberate");
+    const easingKey = options?.easing ?? "standard";
+    if (!MOTION_ENABLED || reducedMotion || durationMs === 0) {
+      return runTiming(value, toValue, 0, reanimatedEasing(easingKey), 0, true);
+    }
+    return runLoop(value, toValue, durationMs, reanimatedEasing(easingKey));
+  }, [duration, reducedMotion]);
   return useMemo(() => ({
     enabled: MOTION_ENABLED && !reducedMotion,
     tier,
@@ -40,7 +38,8 @@ export function useMotion() {
     duration,
     easing,
     spring,
-    timing
-  }), [reducedMotion, tier, duration, easing, spring, timing]);
+    timing,
+    loop
+  }), [reducedMotion, tier, duration, easing, spring, timing, loop]);
 }
 //# sourceMappingURL=useMotion.js.map