@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/useScroll.ts

@@ -0,0 +1,162 @@
+// REQ-API-037 — useScroll on the native entry: scroll-fed motion values into the R4 value
+// channel. Binds a consumer-supplied animated scrollable ref; offsets/progress update without
+// React re-renders. Scroll events are handled on the UI thread (reanimated useEvent worklet)
+// and cross into the value channel via scheduleOnRN — never a JS-thread per-frame poll.
+// Web is a thin pin re-export (native-motion-web).
+
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { MotionValue } from '@unrulysystems/native-motion-core'
+import { useEvent } from 'react-native-reanimated'
+import { scheduleOnRN } from 'react-native-worklets'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import {
+  applyScrollOffsets,
+  gateUseScrollOptions,
+  isBindableScrollContainer,
+  refuseUnbindableScrollContainer,
+  resolveNativeScrollSource,
+  settleNativeScrollBinding,
+  type AnimatedScrollContainer,
+  type ScrollMotionValues,
+  type UseScrollOptions,
+} from './scrollValues'
+import { useInternalMotionValue } from './valueHooks'
+
+export type { ScrollMotionValues, UseScrollOptions } from './scrollValues'
+
+interface NativeScrollEvent {
+  readonly contentOffset: { readonly x: number; readonly y: number }
+  readonly contentSize: { readonly width: number; readonly height: number }
+  readonly layoutMeasurement: { readonly width: number; readonly height: number }
+}
+
+const SCROLL_EVENT_NAMES = [
+  'onScroll',
+  'onScrollBeginDrag',
+  'onScrollEndDrag',
+  'onMomentumScrollBegin',
+  'onMomentumScrollEnd',
+] as const
+
+export function useScroll(options: UseScrollOptions = {}): ScrollMotionValues {
+  const severity = ambientNativeSeverity()
+  const gate = { severity, report: consoleReporter }
+  const gated = gateUseScrollOptions(options as Readonly<Record<string, unknown>>, gate)
+
+  const scrollX = useInternalMotionValue(0)
+  const scrollY = useInternalMotionValue(0)
+  const scrollXProgress = useInternalMotionValue(0)
+  const scrollYProgress = useInternalMotionValue(0)
+
+  const valuesRef = useRef<ScrollMotionValues | null>(null)
+  if (valuesRef.current === null) {
+    valuesRef.current = { scrollX, scrollY, scrollXProgress, scrollYProgress }
+  }
+  const values = valuesRef.current
+
+  // Deferred settle (microtask) throws outside React's effect try/catch — rethrow on the next
+  // render so createRoot/act and Error Boundaries observe the pin use-scroll-ref refuse
+  // (major a41c9e7f2b08). Production path reports without throwing; no re-render needed.
+  const [settleError, setSettleError] = useState<Error | null>(null)
+  if (settleError !== null) throw settleError
+
+  // Stable hop target: a per-render function is a new JS identity the UI worklet cannot
+  // reliably scheduleOnRN. valuesRef is mount-stable.
+  const applyOnJS = useRef(
+    (xOffset: number, yOffset: number, xMaxOffset: number, yMaxOffset: number) => {
+      if (valuesRef.current === null) return
+      applyScrollOffsets(valuesRef.current, { xOffset, yOffset, xMaxOffset, yMaxOffset })
+    },
+  ).current
+
+  // UI-thread scroll handler — worklet body; one scheduleOnRN hop per native scroll event.
+  const eventHandler = useEvent<NativeScrollEvent>((event) => {
+    'worklet'
+    const xOffset = event.contentOffset.x
+    const yOffset = event.contentOffset.y
+    const xMax = Math.max(0, event.contentSize.width - event.layoutMeasurement.width)
+    const yMax = Math.max(0, event.contentSize.height - event.layoutMeasurement.height)
+    scheduleOnRN(applyOnJS, xOffset, yOffset, xMax, yMax)
+  }, SCROLL_EVENT_NAMES) as unknown as {
+    workletEventHandler: {
+      registerForEvents: (tag: number) => void
+      unregisterFromEvents: (tag: number) => void
+    }
+  }
+
+  const containerRef = useRef(gated.container)
+  containerRef.current = gated.container
+
+  // Severity authority for the hydrated path (single throw — avoid layout+effect AggregateError):
+  // missing / non-scrollable / unbindable (no observe) fail loud here. Pending waits for settle.
+  useLayoutEffect(() => {
+    const resolved = resolveNativeScrollSource({ container: containerRef.current }, gate)
+    if (resolved.kind === 'scrollable' && !isBindableScrollContainer(containerRef.current)) {
+      refuseUnbindableScrollContainer(gate)
+    }
+  })
+
+  // Bindable animated refs observe-wait immediately (even while current is null). Plain
+  // refs keep the pin's one-microtask sibling-hydrate window, then refuse unhydrated.
+  useEffect(() => {
+    const container = containerRef.current as AnimatedScrollContainer | null | undefined
+    if (container === null || container === undefined) return
+
+    let cleanup: (() => void) | undefined
+    let cancelled = false
+
+    const runSettle = () => {
+      if (cancelled) return
+      try {
+        cleanup = settleNativeScrollBinding(container, gate, (tag) => {
+          eventHandler.workletEventHandler.registerForEvents(tag)
+          return () => {
+            eventHandler.workletEventHandler.unregisterFromEvents(tag)
+          }
+        })
+      } catch (error) {
+        // Surface outside the microtask as a render throw (act-observable).
+        setSettleError(error instanceof Error ? error : new Error(String(error)))
+      }
+    }
+
+    if (isBindableScrollContainer(container)) {
+      runSettle()
+      return () => {
+        cancelled = true
+        cleanup?.()
+      }
+    }
+
+    if (container.current === null || container.current === undefined) {
+      queueMicrotask(runSettle)
+      return () => {
+        cancelled = true
+        cleanup?.()
+      }
+    }
+    return
+  }, [gated.container, eventHandler])
+
+  return values
+}
+
+/** Test seam: drive the four values as a native scroll event would (no React re-render). */
+export function applyScrollOffsetsForTests(
+  values: ScrollMotionValues,
+  offsets: {
+    readonly xOffset: number
+    readonly yOffset: number
+    readonly xMaxOffset: number
+    readonly yMaxOffset: number
+  },
+): void {
+  applyScrollOffsets(values, offsets)
+}
+
+export type ScrollValueBundle = {
+  readonly scrollX: MotionValue<number>
+  readonly scrollY: MotionValue<number>
+  readonly scrollXProgress: MotionValue<number>
+  readonly scrollYProgress: MotionValue<number>
+}

package/src/native/motion/useViewportScroll.ts

@@ -0,0 +1,29 @@
+// U7i (REQ-API-037(e)) — useViewportScroll, the pin's deprecated zero-argument alias of
+// useScroll(). Pin: framer-motion@12.42.2 value/scroll/use-viewport-scroll.ts — dev warnOnce
+// then `return useScroll()`. Native inherits the container-required refusal (no window
+// viewport analog). Shipping the alias is not a viewport claim.
+
+import { useScroll, type ScrollMotionValues } from './useScroll'
+
+declare const __DEV__: boolean | undefined
+
+const warnedKeys = new Set<string>()
+function warnOnce(condition: boolean, message: string): void {
+  if (condition || warnedKeys.has(message)) return
+  warnedKeys.add(message)
+  console.warn(message)
+}
+
+/**
+ * @deprecated useViewportScroll is deprecated. Convert to useScroll()
+ */
+export function useViewportScroll(): ScrollMotionValues {
+  if (typeof __DEV__ === 'undefined' || __DEV__ !== false) {
+    warnOnce(false, 'useViewportScroll is deprecated. Convert to useScroll().')
+  }
+  return useScroll()
+}
+
+export function resetUseViewportScrollWarningForTests(): void {
+  warnedKeys.clear()
+}