@octane-xplat/motion 0.9.0 → 0.10.0

package/src/engine.ts

@@ -1,6 +1,12 @@
 import { keyframes, spring } from 'motion-dom'
 import type { Clock } from './clock-types.js'
-import type { Transition } from './types.js'
+import type {
+	Transition,
+	TransitionInput,
+	TransitionOrchestration,
+	MotionKey,
+	RepeatType,
+} from './types.js'
 
 /** Terminal status; cancellation never masquerades as completion. */
 export type AnimationResult = 'finished' | 'cancelled' | 'replaced'
@@ -10,16 +16,55 @@ export interface AnimationControls {
 	stop(reason?: Exclude<AnimationResult, 'finished'>): void
 }
 
+const MOTION_KEYS: MotionKey[] = ['opacity', 'x', 'y', 'scale', 'scaleX', 'scaleY', 'rotate']
+
+/** Platform animators take one timing curve per run — cubic-bezier only. */
+const BEZIER_EASES = new Set(['linear', 'easeIn', 'easeOut', 'easeInOut'])
+export function isBezierEase(ease: Transition['ease']): boolean {
+	return ease === undefined || Array.isArray(ease) || BEZIER_EASES.has(ease)
+}
+
+const BEZIER_POINTS: Record<string, [number, number, number, number]> = {
+	linear: [0, 0, 1, 1],
+	easeIn: [0.42, 0, 1, 1],
+	easeOut: [0, 0, 0.58, 1],
+	easeInOut: [0.42, 0, 0.58, 1],
+}
+
+/** CSS cubic-bezier control points for a delegatable ease; tuples pass through. */
+export function bezierPoints(ease: Transition['ease']): [number, number, number, number] {
+	return Array.isArray(ease) ? ease : BEZIER_POINTS[ease ?? 'easeInOut']
+}
+
+export function isOrchestrated(t: TransitionInput | undefined): t is TransitionOrchestration {
+	if (!t || typeof t !== 'object') {
+		return false
+	}
+
+	return 'default' in t || MOTION_KEYS.some((key) => key in t)
+}
+
+export function resolveTransition(t: TransitionInput, key: MotionKey): Transition {
+	return isOrchestrated(t) ? { ...t.default, ...t[key] } : t
+}
+
 export function validateTransition(t: Transition): void {
-	if (t.type === 'spring' && (t.duration !== undefined || t.ease !== undefined)) {
-		throw new Error('motion: physical springs do not accept duration or ease')
+	if (t.type === 'spring' && t.ease !== undefined) {
+		throw new Error('motion: physical springs do not accept ease')
 	}
 
 	const allowed = [
+		'staggerChildren',
+		'delayChildren',
+		'when',
 		'type',
 		'duration',
 		'delay',
 		'ease',
+		'repeat',
+		'repeatType',
+		'repeatDelay',
+		'bounce',
 		'stiffness',
 		'damping',
 		'mass',
@@ -34,13 +79,21 @@ export function validateTransition(t: Transition): void {
 		}
 	}
 
+	if (t.when !== undefined && !['beforeChildren', 'afterChildren'].includes(t.when)) {
+		throw new Error('motion: unsupported when')
+	}
+
 	if (t.type !== undefined && t.type !== 'tween' && t.type !== 'spring') {
 		throw new Error('motion: unsupported transition type')
 	}
 
 	for (const key of [
+		'staggerChildren',
+		'delayChildren',
 		'duration',
 		'delay',
+		'repeatDelay',
+		'bounce',
 		'stiffness',
 		'damping',
 		'mass',
@@ -54,6 +107,17 @@ export function validateTransition(t: Transition): void {
 		}
 	}
 
+	if (
+		t.repeat !== undefined &&
+		(t.repeat < 0 || (!Number.isInteger(t.repeat) && t.repeat !== Infinity))
+	) {
+		throw new Error('motion: repeat must be a non-negative integer or Infinity')
+	}
+
+	if (t.repeatType !== undefined && !['loop', 'reverse', 'mirror'].includes(t.repeatType)) {
+		throw new Error('motion: unsupported repeatType')
+	}
+
 	for (const key of ['mass', 'stiffness', 'damping', 'restSpeed', 'restDelta'] as const) {
 		if (t[key] === 0) {
 			throw new Error(`motion: ${key} must be positive`)
@@ -72,12 +136,44 @@ export function validateTransition(t: Transition): void {
 			) {
 				throw new Error('motion: invalid cubic Bezier')
 			}
-		} else if (!['linear', 'easeIn', 'easeOut', 'easeInOut'].includes(t.ease)) {
+		} else if (
+			![
+				'linear',
+				'easeIn',
+				'easeOut',
+				'easeInOut',
+				'circIn',
+				'circOut',
+				'circInOut',
+				'backIn',
+				'backOut',
+				'backInOut',
+				'anticipate',
+			].includes(t.ease)
+		) {
 			throw new Error('motion: unsupported easing')
 		}
 	}
 }
 
+export function validateTransitionInput(t: TransitionInput): void {
+	if (isOrchestrated(t)) {
+		const { staggerChildren, delayChildren, when, ...channels } = t
+		validateTransition({ staggerChildren, delayChildren, when })
+		for (const [key, value] of Object.entries(channels)) {
+			if (key !== 'default' && !MOTION_KEYS.includes(key as MotionKey)) {
+				throw new Error(`motion: unsupported transition ${key}`)
+			}
+
+			if (value) {
+				validateTransition(value as Transition)
+			}
+		}
+	} else {
+		validateTransition(t)
+	}
+}
+
 // Pure upstream generators share trajectories across platforms; host scheduling
 // stays outside Motion's browser-global frame loop.
 export function runAnimation(
@@ -110,37 +206,63 @@ export function runAnimation(
 	}
 
 	const duration = transition.duration ?? 0.3
-	const generator =
+	const repeat = transition.repeat ?? 0
+	const repeatType: RepeatType = transition.repeatType ?? 'loop'
+	const repeatDelay = (transition.repeatDelay ?? 0) * 1000
+
+	const makeGenerator = (legFrom: number, legTo: number) =>
 		transition.type === 'spring'
 			? spring({
-					keyframes: [from, to],
+					keyframes: [legFrom, legTo],
 					stiffness: transition.stiffness ?? 100,
 					damping: transition.damping ?? 10,
 					mass: transition.mass ?? 1,
 					velocity: transition.velocity ?? 0,
 					restSpeed: transition.restSpeed,
 					restDelta: transition.restDelta,
+					// Visual-duration spring spec — duration/bounce instead of
+					// stiffness/damping; motion-dom takes milliseconds.
+					duration: transition.duration !== undefined ? duration * 1000 : undefined,
+					bounce: transition.bounce,
 				})
 			: keyframes({
-					keyframes: [from, to],
+					keyframes: [legFrom, legTo],
 					duration: duration * 1000,
 					ease: transition.ease ?? 'easeInOut',
 				})
 
-	const start = clock.now() + (transition.delay ?? 0) * 1000
+	let leg = 0
+	let generator = makeGenerator(from, to)
+	let legStart = clock.now() + (transition.delay ?? 0) * 1000
 	const tick = () => {
 		if (settled) {
 			return
 		}
 
-		const elapsed = Math.max(0, clock.now() - start)
-		if (clock.now() >= start) {
-			const state = generator.next(elapsed)
-			update(state.done ? to : state.value)
-			if (state.done) {
-				settle('finished')
+		const now = clock.now()
+		if (now < legStart) {
+			frame = clock.request(tick)
+			return
+		}
+
+		const elapsed = Math.max(0, now - legStart)
+		const state = generator.next(elapsed)
+		const legEnd = repeatType === 'loop' || leg % 2 === 0 ? to : from
+		update(state.done ? legEnd : state.value)
+		if (state.done) {
+			if (leg < repeat) {
+				leg++
+				// 'loop' replays the same direction; 'reverse'/'mirror' alternate
+				// legs (identical for two keyframes, which is all we generate).
+				const [legFrom, legTo] = repeatType === 'loop' || leg % 2 === 0 ? [from, to] : [to, from]
+				generator = makeGenerator(legFrom, legTo)
+				legStart = now + repeatDelay
+				frame = clock.request(tick)
 				return
 			}
+
+			settle('finished')
+			return
 		}
 
 		if (!settled) {
@@ -148,7 +270,7 @@ export function runAnimation(
 		}
 	}
 
-	if (transition.type !== 'spring' && duration === 0 && !transition.delay) {
+	if (transition.type !== 'spring' && duration === 0 && !transition.delay && repeat === 0) {
 		update(to)
 		settle('finished')
 	} else {

package/src/hooks.tsrx

@@ -1,8 +1,11 @@
-import { useRef, useLayoutEffect } from 'octane'
+import { useRef, useLayoutEffect, useContext } from 'octane'
 import { interpolate } from 'motion-dom'
 import { clock } from './clock'
+import { ConfigContext, useReducedMotion } from './config.tsrx'
+import { controllers } from './components.tsrx'
 import { MotionValue, type MotionValueEvents } from './value'
-import type { Transition } from './types'
+import type { AnimationControls, AnimationResult } from './engine'
+import type { Target, Transition, TransitionInput } from './types'
 
 /** Create an owned numeric value that writes to bound hosts without rendering. */
 export function useMotionValue(initial: number): MotionValue {
@@ -54,3 +57,51 @@ export function useSpring(source: number | MotionValue, options: Omit<Transition
 
 	return value
 }
+
+/** Scoped imperative animation: `const [scope, animate] = useAnimate()` then
+ *  `ref={scope}` on a motion host. `animate(target, transition)` drives that
+ *  host; `animate(value, to, transition)` drives a MotionValue directly. */
+export function useAnimate(): [
+	{ current: any },
+	(
+		target: Target | MotionValue | object,
+		transitionOrTo?: TransitionInput | number,
+		transition?: Transition,
+	) => Promise<AnimationResult> | AnimationControls,
+] {
+	const scope = useRef<any>(null)
+	const config = useContext(ConfigContext)
+	const systemReduced = useReducedMotion()
+	const reducedRef = useRef(config.reducedMotion === 'always' || (config.reducedMotion === 'user' && systemReduced))
+	reducedRef.current = config.reducedMotion === 'always' || (config.reducedMotion === 'user' && systemReduced)
+	const animate = useRef(
+		(
+			target: any,
+			transitionOrTo?: any,
+			transition?: any,
+		): Promise<AnimationResult> | AnimationControls => {
+			if (target instanceof MotionValue) {
+				return target.animate(transitionOrTo, transition)
+			}
+
+			// A registered host node targets that element's controller; a plain
+			// channel target drives the scope's host.
+			const controller =
+				target && typeof target === 'object' && controllers.has(target)
+					? controllers.get(target)!
+					: scope.current
+						? controllers.get(scope.current)
+						: undefined
+
+			if (!controller) {
+				return Promise.resolve('cancelled' as const)
+			}
+
+			const destination = controllers.has(target) ? (transitionOrTo ?? {}) : target
+			const spec = controllers.has(target) ? (transition ?? {}) : (transitionOrTo ?? {})
+			return controller.animate(destination, spec, reducedRef.current)
+		},
+	).current
+
+	return [scope, animate]
+}

package/src/host-types.ts

@@ -1,6 +1,49 @@
-import type { Target } from './types'
+import type { Target, Transition, DragInfo } from './types'
+
+export interface DelegatedRequest {
+	/** Channels the caller asked to animate. */
+	target: Target
+	/** Full channel-space destination: retained values plus the target. */
+	dest: Target
+	/** Effective native destination — `scale` folded into scaleX/scaleY. */
+	eff: Target
+	transition: Transition
+}
+
+/** A run handed to the platform animator; presentation state stays readable. */
+export interface DelegatedRun {
+	/** Reads current rendered values in effective channels (scale folded). */
+	sample(): Target
+	/** Stops the run at its presentation state; the model is synced to it. */
+	cancel(): void
+	finished: Promise<'finished' | 'cancelled'>
+}
+
+/** Gesture-target kinds: press covers whileTap, focus covers whileFocus. */
+export type GestureKind = 'press' | 'focus'
+
+export interface GestureCallbacks {
+	start(): void
+	end(): void
+}
+
+export interface PanCallbacks {
+	start(event: any, info: DragInfo): void
+	move(event: any, info: DragInfo): void
+	end(event: any, info: DragInfo): void
+}
+
 export interface HostAdapter {
+	pan?(axis: true | 'x' | 'y', callbacks: PanCallbacks): () => void
 	read(): Target
 	write(values: Target): void
 	restore(): void
+	/**
+	 * Run a declarative tween on the platform animator. Returns null to fall
+	 * back to the JS engine.
+	 */
+	delegate?(request: DelegatedRequest): DelegatedRun | null
+	/** Subscribe to a gesture lifecycle; returns an unsubscribe, or null if the
+	 *  host cannot emit it (focus events only exist on focusable hosts). */
+	gesture?(kind: GestureKind, callbacks: GestureCallbacks): (() => void) | null
 }

package/src/host.ts

@@ -1,4 +1,6 @@
-import type { HostAdapter } from './host-types'
+import type { DelegatedRequest, DelegatedRun, HostAdapter } from './host-types'
+import { attachPan } from './pan'
+import { delegatedRun } from './driver'
 // The retained NativeScript View exposes direct transform channels in DIP.
 export function attachHost(node: any): HostAdapter {
 	const original = {
@@ -46,5 +48,40 @@ export function attachHost(node: any): HostAdapter {
 		}
 	}
 
-	return { read: () => ({ ...original, scale: 1 }), write, restore: () => write(original) }
+	return {
+		pan: (axis, callbacks) => attachPan(node, axis, callbacks),
+		read: () => ({ ...original, scale: 1 }),
+		write,
+		restore: () => write(original),
+		delegate: (req: DelegatedRequest): DelegatedRun | null => delegatedRun(node, req, write),
+		gesture(kind, callbacks) {
+			if (typeof node.on !== 'function' || typeof node.off !== 'function') {
+				return null
+			}
+
+			if (kind === 'press') {
+				// NativeScript's `touch` event: action down/up/cancel.
+				const onTouch = (event: any) => {
+					if (event.action === 'down') {
+						callbacks.start()
+					} else if (event.action === 'up' || event.action === 'cancel') {
+						callbacks.end()
+					}
+				}
+
+				node.on('touch', onTouch)
+				return () => node.off('touch', onTouch)
+			}
+
+			// focus/blur exist only on focusable hosts (editable text, buttons).
+			const onFocus = () => callbacks.start()
+			const onBlur = () => callbacks.end()
+			node.on('focus', onFocus)
+			node.on('blur', onBlur)
+			return () => {
+				node.off('focus', onFocus)
+				node.off('blur', onBlur)
+			}
+		},
+	}
 }

package/src/host.web.ts

@@ -1,4 +1,7 @@
-import type { HostAdapter } from './host-types'
+import { attachPan } from './pan.web'
+import { delegatedRun } from './driver.web'
+import type { DelegatedRequest, DelegatedRun, HostAdapter } from './host-types'
+import type { Target } from './types'
 export function attachHost(node: HTMLElement): HostAdapter {
 	const transform = node.style.transform
 	const opacity = node.style.opacity
@@ -7,7 +10,18 @@ export function attachHost(node: HTMLElement): HostAdapter {
 		throw new Error('motion: put existing CSS transforms on an outer container')
 	}
 
+	const write = (values: Target) => {
+		if (values.opacity !== undefined) {
+			node.style.opacity = String(Math.min(1, Math.max(0, values.opacity)))
+		}
+
+		if (Object.keys(values).some((key) => key !== 'opacity')) {
+			node.style.transform = `translateX(${values.x ?? 0}px) translateY(${values.y ?? 0}px) scale(${values.scale ?? 1}) scaleX(${values.scaleX ?? 1}) scaleY(${values.scaleY ?? 1}) rotate(${values.rotate ?? 0}deg)`
+		}
+	}
+
 	return {
+		pan: (axis, callbacks) => attachPan(node, axis, callbacks),
 		read: () => ({
 			opacity: Number(computed.opacity || 1),
 			x: 0,
@@ -17,18 +31,45 @@ export function attachHost(node: HTMLElement): HostAdapter {
 			scaleY: 1,
 			rotate: 0,
 		}),
-		write(values) {
-			if (values.opacity !== undefined) {
-				node.style.opacity = String(Math.min(1, Math.max(0, values.opacity)))
-			}
-
-			if (Object.keys(values).some((key) => key !== 'opacity')) {
-				node.style.transform = `translateX(${values.x ?? 0}px) translateY(${values.y ?? 0}px) scale(${values.scale ?? 1}) scaleX(${values.scaleX ?? 1}) scaleY(${values.scaleY ?? 1}) rotate(${values.rotate ?? 0}deg)`
-			}
-		},
+		write,
+		delegate: (req: DelegatedRequest): DelegatedRun | null => delegatedRun(node, req, write),
 		restore() {
 			node.style.transform = transform
 			node.style.opacity = opacity
 		},
+		gesture(kind, callbacks) {
+			if (kind === 'press') {
+				const down = (event: PointerEvent) => {
+					try {
+						// Preserve descendant click targets when this host wraps controls.
+						;(event.target as Element | null)?.setPointerCapture?.(event.pointerId)
+					} catch (error) {
+						// Synthetic pointer dispatch has no active browser pointer.
+						if (event.isTrusted || (error as Error).name !== 'NotFoundError') {
+							throw error
+						}
+					}
+
+					callbacks.start()
+				}
+
+				const end = () => callbacks.end()
+				node.addEventListener('pointerdown', down)
+				node.addEventListener('pointerup', end)
+				node.addEventListener('pointercancel', end)
+				return () => {
+					node.removeEventListener('pointerdown', down)
+					node.removeEventListener('pointerup', end)
+					node.removeEventListener('pointercancel', end)
+				}
+			}
+
+			node.addEventListener('focus', callbacks.start)
+			node.addEventListener('blur', callbacks.end)
+			return () => {
+				node.removeEventListener('focus', callbacks.start)
+				node.removeEventListener('blur', callbacks.end)
+			}
+		},
 	}
 }

package/src/index.ts

@@ -1,8 +1,22 @@
-import { MotionView, MotionRow, MotionPressable } from './components.tsrx'
-/** Bounded motion hosts for shared xplat UI primitives. */
-export const motion = { View: MotionView, Row: MotionRow, Pressable: MotionPressable }
+import { MotionView, MotionRow, MotionPressable, createMotion } from './components.tsrx'
+/** Bounded motion hosts for shared xplat UI primitives; `motion.create` wraps
+ *  any component that accepts `ref`/`style`/`children`. */
+export const motion = {
+	View: MotionView,
+	Row: MotionRow,
+	Pressable: MotionPressable,
+	create: createMotion,
+}
+
 export { MotionConfig, useReducedMotion } from './config.tsrx'
-export { useMotionValue, useTransform, useSpring, useMotionValueEvent } from './hooks.tsrx'
+export {
+	useMotionValue,
+	useTransform,
+	useSpring,
+	useMotionValueEvent,
+	useAnimate,
+} from './hooks.tsrx'
+
 export type { MotionValue, MotionValueEvents } from './value'
 export type { AnimationControls, AnimationResult } from './engine'
 export type * from './types'

package/src/index.web.ts

@@ -1,8 +1,22 @@
-import { MotionView, MotionRow, MotionPressable } from './components.tsrx'
-/** Bounded motion hosts for shared xplat UI primitives. */
-export const motion = { View: MotionView, Row: MotionRow, Pressable: MotionPressable }
+import { MotionView, MotionRow, MotionPressable, createMotion } from './components.tsrx'
+/** Bounded motion hosts for shared xplat UI primitives; `motion.create` wraps
+ *  any component that accepts `ref`/`style`/`children`. */
+export const motion = {
+	View: MotionView,
+	Row: MotionRow,
+	Pressable: MotionPressable,
+	create: createMotion,
+}
+
 export { MotionConfig, useReducedMotion } from './config.tsrx'
-export { useMotionValue, useTransform, useSpring, useMotionValueEvent } from './hooks.tsrx'
+export {
+	useMotionValue,
+	useTransform,
+	useSpring,
+	useMotionValueEvent,
+	useAnimate,
+} from './hooks.tsrx'
+
 export type { MotionValue, MotionValueEvents } from './value'
 export type { AnimationControls, AnimationResult } from './engine'
 export type * from './types'

package/src/pan.ts

@@ -0,0 +1,92 @@
+import {
+	Manager,
+	HandlerType,
+	GestureState,
+	GestureHandlerStateEvent,
+	GestureHandlerTouchEvent,
+} from '@nativescript-community/gesturehandler'
+
+import { Utils } from '@nativescript/core'
+import type { PanCallbacks } from './host-types'
+import type { DragInfo } from './types'
+
+// Separate tag range from the plugin's built-in gesture observers. Manager
+// shares the registry; applications should reserve this range for motion.
+let tag = 700000000
+
+export function attachPan(node: any, axis: true | 'x' | 'y', callbacks: PanCallbacks) {
+	// 2.0.45 config setters take raw Android pixels (their converter is
+	// getter-only); payloads already convert back to DIP.
+	const androidHost = Boolean((globalThis as any).android)
+	const slop = androidHost ? Utils.layout.toDevicePixels(8) : 8
+	const handler = Manager.getInstance().createGestureHandler(HandlerType.PAN, tag++, {
+		shouldCancelWhenOutside: false,
+		// Android retains its radial touch-slop default alongside activeOffset.
+		// Disable that alternative trigger for single-axis arbitration.
+		...(androidHost && axis !== true ? { minDist: 1e9 } : {}),
+		...(axis === true
+			? { minDist: slop }
+			: axis === 'x'
+				? {
+						activeOffsetXStart: -slop,
+						activeOffsetXEnd: slop,
+						failOffsetYStart: -slop,
+						failOffsetYEnd: slop,
+					}
+				: {
+						activeOffsetYStart: -slop,
+						activeOffsetYEnd: slop,
+						failOffsetXStart: -slop,
+						failOffsetXEnd: slop,
+					}),
+	})
+
+	let active = false
+	let last = { x: 0, y: 0 }
+	const sample = (args: any, cancelled = false): DragInfo => {
+		const extra = args.data.extraData ?? {}
+		const offset = { x: extra.translationX ?? last.x, y: extra.translationY ?? last.y }
+		const delta = { x: offset.x - last.x, y: offset.y - last.y }
+		last = offset
+		return {
+			point: { x: extra.absoluteX ?? extra.x ?? 0, y: extra.absoluteY ?? extra.y ?? 0 },
+			delta,
+			offset,
+			velocity: { x: extra.velocityX ?? 0, y: extra.velocityY ?? 0 },
+			cancelled,
+		}
+	}
+
+	const state = (args: any) => {
+		const next = args.data.state
+		if (next === GestureState.ACTIVE && !active) {
+			last = { x: 0, y: 0 }
+			active = true
+			const info = sample(args)
+			callbacks.start(args, info)
+			callbacks.move(args, info)
+		} else if (
+			active &&
+			[GestureState.END, GestureState.CANCELLED, GestureState.FAILED].includes(next)
+		) {
+			active = false
+			callbacks.end(args, sample(args, next !== GestureState.END))
+		}
+	}
+
+	const touch = (args: any) => {
+		if (active && args.data.state === GestureState.ACTIVE) {
+			callbacks.move(args, sample(args))
+		}
+	}
+
+	handler.on(GestureHandlerStateEvent, state)
+	handler.on(GestureHandlerTouchEvent, touch)
+	handler.attachToView(node)
+	return () => {
+		active = false
+		handler.off(GestureHandlerStateEvent, state)
+		handler.off(GestureHandlerTouchEvent, touch)
+		handler.detachFromView(node)
+	}
+}