@octane-xplat/motion 0.9.0 → 0.11.0

package/dist/web/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "fcb6bc74-25e4-4f8e-af58-42140062b9cd",
+  "buildId": "708a1acc-6d42-4247-b187-6bea0b63c4e4",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/motion",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Declarative motion and retained presence for Octane on web, iOS and Android",
   "keywords": [
     "android",
@@ -43,21 +43,23 @@
     "access": "public"
   },
   "dependencies": {
-    "@octane-xplat/ui": "0.9.0",
+    "@octane-xplat/ui": "0.11.0",
     "motion-dom": "12.42.2"
   },
   "devDependencies": {
+    "@nativescript-community/gesturehandler": "2.0.45",
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
     "@octanejs/vite-plugin": "0.1.61",
     "jsdom": "30.1.1",
     "octane": "0.6.3",
-    "tsrx-typegen": "0.2.1",
+    "tsrx-typegen": "0.2.2",
     "typescript": "5.9.3",
     "vite": "8.3.0",
     "vitest": "5.0.1"
   },
   "peerDependencies": {
+    "@nativescript-community/gesturehandler": "2.0.45",
     "@nativescript-community/octane": ">=0.2.1 <1",
     "@nativescript/core": ">=9.1.0 <10",
     "octane": ">=0.1.51 <1"
@@ -68,6 +70,9 @@
     },
     "@nativescript/core": {
       "optional": true
+    },
+    "@nativescript-community/gesturehandler": {
+      "optional": true
     }
   },
   "scripts": {

package/src/clock.ts

@@ -1,7 +1,19 @@
 import { requestAnimationFrame, cancelAnimationFrame } from '@nativescript/core/animation-frame'
+import { Application } from '@nativescript/core'
 import type { Clock } from './clock-types'
+
+const platform = globalThis as any
+
+const now: () => number = Application.ios
+	? platform.CACurrentMediaTime
+		? () => platform.CACurrentMediaTime() * 1000
+		: (platform.__time ?? Date.now)
+	: platform.java?.lang?.System
+		? () => platform.java.lang.System.nanoTime() / 1e6
+		: Date.now
+
 export const clock: Clock = {
-	now: () => Date.now(),
+	now,
 	request: requestAnimationFrame,
 	cancel: cancelAnimationFrame,
 }

package/src/components.mobile.test.tsrx

@@ -95,3 +95,61 @@ it('retargets a retained native host on a signal write', () => {
 	expect(node.translateX).toBe(75)
 	root.unmount()
 })
+
+import { handlers, GestureHandlerStateEvent, GestureHandlerTouchEvent, GestureState } from '../test/gesturehandler'
+
+function NativeDrag() @{
+	<MotionConfig reducedMotion="always">
+		<motion.View id="native-drag" drag="x" dragConstraints={{ left: -40, right: 40 }} dragElastic={false} />
+	</MotionConfig>
+}
+
+it('drives the retained native host from its handler and snaps reduced settlement', () => {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(NativeDrag, {})
+	const node: any = container.children[0]
+	const handler = handlers.findLast((h) => h.node === node)
+	expect(handler).toBeDefined()
+	handler.emit(GestureHandlerStateEvent, { state: GestureState.ACTIVE, extraData: { translationX: 10 } })
+	handler.emit(GestureHandlerTouchEvent, { state: GestureState.ACTIVE, extraData: { translationX: 20 } })
+	expect(node.translateX).toBe(20)
+	handler.emit(GestureHandlerStateEvent, { state: GestureState.END, extraData: { translationX: 20, velocityX: 250 } })
+	expect(node.translateX).toBe(40)
+	root.unmount()
+	expect(handler.node).toBeUndefined()
+})
+
+function NativeVariants(props: any) @{
+	<motion.View animate={props.label} variants={{ show: { transition: { duration: 0, when: 'beforeChildren' } }, hide: { transition: { duration: 0 } } }}>
+		<motion.View custom={props.custom ?? 70} variants={{ show: (custom: number) => ({ x: custom, transition: { duration: 0 } }), hide: { x: 0, transition: { duration: 0 } } }} />
+	</motion.View>
+}
+
+it('propagates variant labels to retained native children', async () => {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(NativeVariants, { label: 'show' })
+	await new Promise((resolve) => setTimeout(resolve, 0))
+	const child: any = container.children[0].children[0]
+	expect(child.translateX).toBe(70)
+	flushUniversalSync(() => root.render(NativeVariants, { label: 'hide' }))
+	await new Promise((resolve) => setTimeout(resolve, 0))
+	expect(container.children[0].children[0]).toBe(child)
+	expect(child.translateX).toBe(0)
+	root.unmount()
+})
+
+it('retargets native inherited custom resolvers with an unchanged parent label', async () => {
+	const container = createObjectContainer('nativescript')
+	const root = createUniversalRoot(container, createObjectDriver('nativescript'))
+	root.render(NativeVariants, { label: 'show', custom: 30 })
+	await new Promise((resolve) => setTimeout(resolve, 0))
+	const child: any = container.children[0].children[0]
+	expect(child.translateX).toBe(30)
+	flushUniversalSync(() => root.render(NativeVariants, { label: 'show', custom: 50 }))
+	await new Promise((resolve) => setTimeout(resolve, 0))
+	expect(container.children[0].children[0]).toBe(child)
+	expect(child.translateX).toBe(50)
+	root.unmount()
+})

package/src/components.tsrx

@@ -1,42 +1,82 @@
-import { useRef, useLayoutEffect, useContext } from 'octane'
-import { View, Row, Pressable } from '@octane-xplat/ui'
+import { createContext, useRef, useLayoutEffect, useContext } from 'octane'
+import { View, HStack, Pressable } from '@octane-xplat/ui'
 import { ConfigContext, useReducedMotion } from './config.tsrx'
 import { PresenceContext } from './presence.tsrx'
 import type { PresenceMember } from './presence-state'
+import { attachDrag, validateDrag } from './drag'
 import { clock } from './clock'
 import { attachHost } from './host'
-import type { HostAdapter } from './host-types'
-import { Controller, keys, defaults, validateTarget } from './controller'
-import { validateTransition } from './engine'
+import type { GestureKind, HostAdapter } from './host-types'
+import { Controller, keys, defaults } from './controller'
+import { validateTransitionInput } from './engine'
+import { VariantNode, isLabels, resolveVariant, playbackTransition } from './variants'
 import { MotionValue } from './value'
-import type { MotionKey, MotionProps, MotionViewProps, MotionRowProps, MotionPressableProps, Target } from './types'
+import type { MotionKey, MotionProps, MotionViewProps, MotionRowProps, MotionPressableProps, Target, AnimationDefinition } from './types'
 
-function useMotion(props: MotionProps & { bind?: (host: any) => void }) {
-	for (const name of ['drag', 'layout', 'layoutId', 'variants', 'whileTap', 'whileHover', 'whileFocus', 'whileInView']) {
+const VariantContext = createContext<VariantNode | null>(null)
+
+/** host node → its motion controller; powers `useAnimate` scope lookup. */
+export const controllers = new WeakMap<object, Controller>()
+
+const GESTURE_PROPS: Record<GestureKind, { target: 'whileTap' | 'whileFocus'; transition: 'whileTapTransition' | 'whileFocusTransition' }> = {
+	press: { target: 'whileTap', transition: 'whileTapTransition' },
+	focus: { target: 'whileFocus', transition: 'whileFocusTransition' },
+}
+
+function useMotion(props: MotionProps & Pick<MotionViewProps, 'ref'>) {
+	for (const name of ['layout', 'layoutId', 'inherit', 'whileHover', 'whileInView', 'whileDrag']) {
 		if (name in props) throw new Error(`motion: ${name} is outside the supported subset`)
 	}
 
+	validateDrag(props)
+
+	const parentVariant = useContext(VariantContext)
+	const inherits = props.animate === undefined && parentVariant !== null
+	const initialDefinition = props.initial ?? parentVariant?.initial
+	const animateDefinition = props.animate ?? parentVariant?.animate
+	const resolve = (definition: AnimationDefinition | false | undefined, source: MotionProps = props) => {
+		const resolved = resolveVariant(definition, source.variants, source.custom)
+		for (const key of keys) {
+			if (resolved.target[key] !== undefined && source.style?.[key] instanceof MotionValue) throw new Error(`motion: ${key} has both an animate target and a MotionValue writer`)
+		}
+
+		return resolved
+	}
+
+	const resolvedAnimate = resolve(animateDefinition)
+	const resolvedInitial = resolve(initialDefinition)
+	const resolvedExit = resolve(props.exit)
 	const presence = useContext(PresenceContext)
 	if (props.exit && !presence) throw new Error('motion: exit requires a mounted Presence boundary')
 	const config = useContext(ConfigContext)
 	const systemReduced = useReducedMotion()
 	const reduced = config.reducedMotion === 'always' || (config.reducedMotion === 'user' && systemReduced)
 	const transition = props.transition ?? config.transition ?? {}
-	validateTransition(transition)
-	validateTarget(props.animate)
-	validateTarget(props.exit)
-	if (props.initial !== false) validateTarget(props.initial)
+	validateTransitionInput(transition)
+	resolve(props.whileTap)
+	resolve(props.whileFocus)
+	if (props.whileTapTransition) validateTransitionInput(props.whileTapTransition)
+	if (props.whileFocusTransition) validateTransitionInput(props.whileFocusTransition)
 	const latest = useRef(props)
 	latest.current = props
-	const state = useRef<{ controller: Controller; host?: any; adapter?: HostAdapter; initialized: boolean } | null>(null)
-	if (!state.current) state.current = { controller: new Controller(clock), initialized: false }
+	const state = useRef<{
+		controller: Controller
+		host?: any
+		adapter?: HostAdapter
+		initialized: boolean
+		gestureOff?: () => void
+		dragOff?: () => void
+		preGesture?: Record<GestureKind, Target | undefined>
+	} | null>(null)
+
+	if (!state.current) state.current = { controller: new Controller(clock), initialized: false, preGesture: { press: undefined, focus: undefined } }
 	const current = state.current
 	const style: Record<string, unknown> = {}
 	const bindings: [MotionKey, number | MotionValue][] = []
 	for (const [key, value] of Object.entries(props.style ?? {})) {
 		if (keys.includes(key as MotionKey)) {
 			if (!(value instanceof MotionValue) && (typeof value !== 'number' || !Number.isFinite(value))) throw new Error(`motion: invalid style ${key}`)
-			if (value instanceof MotionValue && (props.animate?.[key as MotionKey] !== undefined || props.exit?.[key as MotionKey] !== undefined || (props.initial && props.initial[key as MotionKey] !== undefined))) throw new Error(`motion: ${key} has both an animate target and a MotionValue writer`)
+			if (value instanceof MotionValue && (resolvedAnimate.target[key as MotionKey] !== undefined || resolvedExit.target[key as MotionKey] !== undefined || (resolvedInitial.target[key as MotionKey] !== undefined))) throw new Error(`motion: ${key} has both an animate target and a MotionValue writer`)
 			bindings.push([key as MotionKey, value as number | MotionValue])
 		} else {
 			if (value instanceof MotionValue || ['transform', 'translateX', 'translateY', 'animation', 'transition'].includes(key)) throw new Error(`motion: unsupported or conflicting style ${key}`)
@@ -48,11 +88,40 @@ function useMotion(props: MotionProps & { bind?: (host: any) => void }) {
 	const boundKeys = useRef<MotionKey[]>([])
 	const firstBinding = useRef(true)
 	const firstAnimation = useRef(true)
+	const inheritedRun = useRef<{ label: string; resolved: string } | null>(null)
 	if (previous.current.length !== bindings.length || previous.current.some(([key, value], i) => key !== bindings[i][0] || value !== bindings[i][1])) previous.current = bindings
-	const bind = useRef<(host: any) => void>(() => {})
-	bind.current = (host) => {
+	current.controller.onUpdate = (snapshot) => latest.current.onUpdate?.(snapshot)
+
+	const gesture = (kind: GestureKind, phase: 'start' | 'end') => {
+		const shape = GESTURE_PROPS[kind]
+		const definition = latest.current[shape.target]
+		if (!definition) return
+		const { target, transition: override } = resolve(definition, latest.current)
+		const gestureTransition = playbackTransition(override ?? latest.current[shape.transition] ?? playback.current.transition)
+		if (phase === 'start') {
+			// Snapshot the gesture's keys so release returns to where they were.
+			const snapshot = current.controller.snapshot()
+			const rest: Target = {}
+			for (const key of Object.keys(target) as MotionKey[]) rest[key] = snapshot[key]
+			current.preGesture![kind] = rest
+			void current.controller.animate(target, gestureTransition, playback.current.reduced)
+		} else {
+			const snap = current.preGesture![kind] ?? {}
+			current.preGesture![kind] = undefined
+			// The declarative animate prop wins over the pre-gesture snapshot.
+			const rest: Target = {}
+			for (const key of Object.keys(target) as MotionKey[]) rest[key] = resolve(latest.current.animate ?? parentVariant?.animate, latest.current).target[key] ?? snap[key] ?? defaults[key]
+			void current.controller.animate(rest, gestureTransition, playback.current.reduced)
+		}
+	}
+
+	const ref = useRef<(host: any) => void>(() => {})
+	ref.current = (host) => {
 		if (!host) return
 		if (current.host !== host) {
+			current.gestureOff?.()
+			current.dragOff?.()
+			current.gestureOff = undefined
 			current.adapter?.restore()
 			current.host = host
 			current.adapter = attachHost(host)
@@ -60,43 +129,73 @@ function useMotion(props: MotionProps & { bind?: (host: any) => void }) {
 				const baseline = current.adapter.read()
 				for (const [key, value] of previous.current) baseline[key] = value instanceof MotionValue ? value.get() : value
 				current.controller.seed(baseline)
-				current.controller.seed(props.initial === false ? props.animate ?? {} : props.initial ?? {})
+				current.controller.seed(initialDefinition === false ? resolvedAnimate.target : resolvedInitial.target)
 				current.initialized = true
 			}
 
-			current.controller.attach(current.adapter.write)
+			current.controller.attach(current.adapter)
+			controllers.set(host, current.controller)
+			configureDrag()
+			if (current.adapter.gesture) {
+				const offs = (['press', 'focus'] as const)
+					.map((kind) => current.adapter!.gesture!(kind, { start: () => gesture(kind, 'start'), end: () => gesture(kind, 'end') }))
+					.filter((off): off is () => void => typeof off === 'function')
+
+				current.gestureOff = () => offs.forEach((off) => off())
+			}
 		}
 
 		current.controller.flush()
-		latest.current.bind?.(host)
 	}
 
 	const playback = useRef({ transition, reduced })
 	playback.current = { transition, reduced }
+	const nodeRef = useRef<VariantNode | null>(null)
+	if (!nodeRef.current) nodeRef.current = new VariantNode()
+	const node = nodeRef.current
+	node.initial = initialDefinition === false || isLabels(initialDefinition) ? initialDefinition : undefined
+	node.animate = isLabels(animateDefinition) ? animateDefinition : undefined
+	node.resolve = (definition) => {
+		const resolved = resolve(definition, latest.current)
+		return { target: resolved.target, transition: resolved.transition ?? playback.current.transition }
+	}
+
+	node.stopOwn = () => current.controller.stop()
+	node.play = async (definition, target, timing) => {
+		latest.current.onAnimationStart?.(definition)
+		const result = await current.controller.animate(target, timing, playback.current.reduced)
+		if (result === 'finished' && current.host) latest.current.onAnimationComplete?.()
+		return result
+	}
+
+	useLayoutEffect(() => inherits ? parentVariant!.register(node) : undefined, [inherits, parentVariant])
 	const returning = useRef<Target | null>(null)
 	const member = useRef<PresenceMember | null>(null)
 	if (!member.current) member.current = {
 		exit() {
+			node.cancelPending()
 			const snapshot = current.controller.snapshot()
 			returning.current ??= {}
-			for (const key of Object.keys(latest.current.exit ?? {}) as MotionKey[]) {
+			const resolved = resolve(latest.current.exit, latest.current)
+			for (const key of Object.keys(resolved.target) as MotionKey[]) {
 				if (!(key in returning.current)) returning.current[key] = snapshot[key]
 			}
 
-			return current.controller.animate(latest.current.exit ?? {}, playback.current.transition, playback.current.reduced)
+			return current.controller.animate(resolved.target, playbackTransition(resolved.transition ?? playback.current.transition), playback.current.reduced)
 		},
 		enter() {
-			const target = { ...returning.current, ...latest.current.animate }
+			const resolved = resolve(latest.current.animate ?? parentVariant?.animate, latest.current)
+			const target = { ...returning.current, ...resolved.target }
 			returning.current = null
-			void current.controller.animate(target, playback.current.transition, playback.current.reduced).then((result) => {
+			void current.controller.animate(target, playbackTransition(resolved.transition ?? playback.current.transition), playback.current.reduced).then((result) => {
 				if (result === 'finished' && current.host && presence?.present) latest.current.onAnimationComplete?.()
 			})
 		},
 	}
 
 	useLayoutEffect(() => presence?.register(member.current!), [presence])
-	const stableBind = useRef((host: any) => bind.current(host)).current
-	useLayoutEffect(() => () => { current.controller.destroy(); current.host = undefined; current.adapter = undefined }, [])
+	const hostRef = useRef((host: any) => ref.current(host)).current
+	useLayoutEffect(() => () => { node.stop(); current.dragOff?.(); current.gestureOff?.(); current.controller.destroy(); current.host = undefined; current.adapter = undefined }, [])
 	useLayoutEffect(() => {
 		const off: (() => void)[] = []
 		for (const key of boundKeys.current) if (!previous.current.some(([next]) => key === next)) current.controller.set(key, defaults[key])
@@ -110,33 +209,80 @@ function useMotion(props: MotionProps & { bind?: (host: any) => void }) {
 		return () => off.forEach((unsubscribe) => unsubscribe())
 	}, [previous.current])
 
+	const configureDrag = () => {
+		current.dragOff?.()
+		current.dragOff = undefined
+		if (!current.adapter) return
+		current.dragOff = attachDrag(current.adapter, current.controller, latest.current, (axis) => {
+			const binding = previous.current.find(([key]) => key === axis)?.[1]
+			return binding instanceof MotionValue ? binding : current.controller.value(axis)
+		}, () => playback.current.reduced, () => latest.current)
+	}
+
 	useLayoutEffect(() => {
-		let active = true
-		const skip = firstAnimation.current && props.initial === false
+		configureDrag()
+	}, [props.drag, JSON.stringify(props.dragConstraints), props.dragElastic, props.dragMomentum, previous.current])
+
+	useLayoutEffect(() => {
+		const skip = firstAnimation.current && initialDefinition === false
 		firstAnimation.current = false
 		if (presence && !presence.present) presence.restart(member.current!)
-		else if (props.animate && !skip) void current.controller.animate(props.animate, transition, reduced).then((result) => {
-			if (active && result === 'finished') latest.current.onAnimationComplete?.()
-		})
+		else if (animateDefinition !== undefined && !skip) {
+			if (!inherits) void node.run(animateDefinition)
+			else {
+				const label = JSON.stringify(animateDefinition)
+				const resolved = JSON.stringify({ resolvedAnimate, transition, reduced })
+				const previousRun = inheritedRun.current
+				if (previousRun?.label === label && previousRun.resolved !== resolved) {
+					const parentTiming = parentVariant!.resolve(animateDefinition).transition
+					void node.run(animateDefinition, (parentTiming.delayChildren ?? 0) + [...parentVariant!.children].indexOf(node) * (parentTiming.staggerChildren ?? 0))
+				}
+
+				inheritedRun.current = { label, resolved }
+			}
+		}
 
-		return () => { active = false; current.controller.stop() }
-	}, [JSON.stringify(props.animate), JSON.stringify(props.exit), JSON.stringify(transition), reduced])
+		return () => { if (!inherits) node.stop() }
+	}, [JSON.stringify(resolvedAnimate), JSON.stringify(resolvedExit), JSON.stringify(animateDefinition), JSON.stringify(transition), reduced, inherits])
 
-	const { initial, exit, animate, transition: ignoredTransition, onAnimationComplete, style: ignoredStyle, bind: ignoredBind, ...rest } = props
-	return { ...rest, style, bind: stableBind }
+	const { drag, dragConstraints, dragElastic, dragMomentum, onDragStart, onDrag, onDragEnd, variants, custom, initial, exit, animate, transition: ignoredTransition, whileTap, whileTapTransition, whileFocus, whileFocusTransition, onAnimationStart, onAnimationComplete, onUpdate, style: ignoredStyle, ref: ignoredRef, ...rest } = props
+	return { hostProps: { ...rest, style, ref: [hostRef, props.ref] }, node }
+}
+
+function MotionLeaf(props: MotionProps & { component?: any; children?: any }) @{
+	const Component = props.component
+	const { hostProps, node } = useMotion(props)
+
+	<VariantContext value={node}><Component {...hostProps}>{props.children}</Component></VariantContext>
+}
+
+/** Wrap any component that accepts `ref`/`style`/`children` — the portable
+ *  equivalent of upstream's `motion.<tag>` host factory. Compiled components
+ *  take (props, slotState, extra) — the factory forwards them into MotionLeaf,
+ *  whose dynamic <Component> tag renders the wrapped leaf. */
+export function createMotion<P extends Record<string, unknown>>(Component: (props: P) => any) {
+	return function MotionCreated(props: P & MotionProps, __s?: any, __extra?: any) {
+		return (MotionLeaf as any)({ ...props, component: Component }, __s, __extra)
+	}
 }
 
 /** Animated View preserving the shared primitive's layout and accessibility. */
 export function MotionView(props: MotionViewProps) @{
-	<View {...useMotion(props)}>{props.children}</View>
+	const { hostProps, node } = useMotion(props)
+
+	<VariantContext value={node}><View {...hostProps}>{props.children}</View></VariantContext>
 }
 
-/** Animated horizontal Row. */
+/** Animated horizontal stack. */
 export function MotionRow(props: MotionRowProps) @{
-	<Row {...useMotion(props)}>{props.children}</Row>
+	const { hostProps, node } = useMotion(props)
+
+	<VariantContext value={node}><HStack {...hostProps}>{props.children}</HStack></VariantContext>
 }
 
 /** Animated Pressable preserving its input callbacks and disabled state. */
 export function MotionPressable(props: MotionPressableProps) @{
-	<Pressable {...useMotion(props)}>{props.children}</Pressable>
+	const { hostProps, node } = useMotion(props)
+
+	<VariantContext value={node}><Pressable {...hostProps}>{props.children}</Pressable></VariantContext>
 }