feat: expose new x|y progress values

+ Expose 0-1 interpolated progress values based on current scroll position, as framer-motion do with `useScroll`

README.md

@@ -111,14 +111,24 @@ All props are optional.
 This hook allows you to consume the internal `MotionValue` values, returning an object of the following type:
 
 ```ts
-{ scrollX: MotionValue, scrollY: MotionValue, x: MotionValue, y: MotionValue }
+{
+  scrollX: MotionValue,
+  scrollXProgress: MotionValue,
+  scrollY: MotionValue,
+  scrollYProgress: MotionValue,
+  x: MotionValue,
+  y: MotionValue
+}
 ```
 
-- `scrollX` & `scrollY`: The current (spring) scroll position.
-- `x` & `y`: The current transform (useful for calculating scroll position when `scale` is in-use).
+- `scrollX` & `scrollY`: The current scroll position.
+- `scrollXProgress` & `scrollYProgress`: A `0` to `1` transform of `scrollX|scrollY`, similar to those returned by [`useScroll`](https://www.framer.com/docs/use-scroll/#usage).
+- `x` & `y`: A negative representation of `scrollX|scrollY`.
 
 It must be used within a `<ScrollerMotion />`, to read the values in the parent component see [Motion Listeners](#motion-listeners).
 
+> ℹ️ For accessing _native_ scroll values (without spring motion or scale calculation) we suggest using framer-motion's [`useScroll`](https://www.framer.com/docs/use-scroll).
+
 ```tsx
 import { ScrollerMotion, useScrollerMotion } from 'scroller-motion'
 import { motion } from 'framer-motion'
@@ -169,7 +179,7 @@ export default () => {
 }
 ```
 
-For accessing the _native_ scroll value (without any spring motion) we suggest using framer-motion's [`useScroll`](https://www.framer.com/docs/use-scroll).
+> ℹ️ For accessing _native_ scroll values (without spring motion or scale calculation) we suggest using framer-motion's [`useScroll`](https://www.framer.com/docs/use-scroll).
 
 ### Recipes
 

src/components/Core/index.tsx

@@ -27,22 +27,30 @@ export const Core = forwardRef<CoreRef, CoreProps>(
   ) => {
     const childrenRef = useRef(null)
 
-    const { height, width, scrollX, scrollY, x, y } = useCore({
+    const {
+      height,
+      width,
+      scrollX,
+      scrollXProgress,
+      scrollY,
+      scrollYProgress,
+      x,
+      y
+    } = useCore({
       ref: childrenRef,
       scale,
       spring
     })
 
-    useImperativeHandle(ref, () => ({ scrollX, scrollY, x, y }), [
-      scrollX,
-      scrollY,
-      x,
-      y
-    ])
+    useImperativeHandle(
+      ref,
+      () => ({ scrollX, scrollXProgress, scrollY, scrollYProgress, x, y }),
+      [scrollX, scrollXProgress, scrollY, scrollYProgress, x, y]
+    )
 
     const contextValue = useMemo(
-      () => ({ scrollX, scrollY, x, y }),
-      [scrollX, scrollY, x, y]
+      () => ({ scrollX, scrollXProgress, scrollY, scrollYProgress, x, y }),
+      [scrollX, scrollXProgress, scrollY, scrollYProgress, x, y]
     )
 
     return (

src/hooks/useCore/index.ts

@@ -21,19 +21,36 @@ export const useCore = ({ ref, scale, spring }: Options) => {
 
   const { x: springX, y: springY } = useSpringScroll(spring)
 
-  const { axis: x, size: width } = useAxis({
+  const {
+    axis: x,
+    progress: progressX,
+    size: width
+  } = useAxis({
     axisSpring: springX,
     scale: innerScale,
     refSize: refWidth,
     windowSize: windowWidth
   })
 
-  const { axis: y, size: height } = useAxis({
+  const {
+    axis: y,
+    progress: progressY,
+    size: height
+  } = useAxis({
     axisSpring: springY,
     scale: innerScale,
     refSize: refHeight,
     windowSize: windowHeight
   })
 
-  return { height, width, scrollX: springX, scrollY: springY, x, y }
+  return {
+    height,
+    width,
+    scrollX: springX,
+    scrollXProgress: progressX,
+    scrollY: springY,
+    scrollYProgress: progressY,
+    x,
+    y
+  }
 }

src/hooks/useCore/useAxis.ts

@@ -34,8 +34,13 @@ export const useAxis = ({
     clamp: false
   })
 
+  const progress = useTransform(axis, transformTo, [0, 1], {
+    clamp: true
+  })
+
   return {
     axis,
+    progress,
     size: scaledSize
   }
 }

src/types.ts

@@ -19,7 +19,9 @@ type CoreRef = ScrollerMotionValues | undefined
 
 interface ScrollerMotionValues {
   scrollX: MotionValue
+  scrollXProgress: MotionValue
   scrollY: MotionValue
+  scrollYProgress: MotionValue
   x: MotionValue
   y: MotionValue
 }