@octane-xplat/motion 0.7.3 → 0.10.0

package/src/driver.web.ts

@@ -0,0 +1,180 @@
+import type { DelegatedRequest, DelegatedRun } from './host-types'
+import { bezierPoints, isBezierEase } from './engine'
+import { delegationStats, trackDelegatedRun } from './delegation'
+import type { Target } from './types'
+
+// All declarative channels map onto compositor-accelerated WAAPI properties:
+// the spatial channels share one transform keyframe pair, opacity animates
+// on its own property.
+const TRANSFORM_KEYS: (keyof Target)[] = ['x', 'y', 'scale', 'scaleX', 'scaleY', 'rotate']
+
+// Matched function lists make WAAPI interpolate each channel numerically —
+// the same order the adapter's write() composes (matrix = T·S·R). The scale
+// channel arrives already folded into scaleX/scaleY on the request's `eff`.
+const transform = (values: Target) =>
+	`translateX(${values.x ?? 0}px) translateY(${values.y ?? 0}px) scaleX(${values.scaleX ?? 1}) scaleY(${values.scaleY ?? 1}) rotate(${values.rotate ?? 0}deg)`
+
+// A computed transform resolves to a matrix composed around transform-origin;
+// peel the origin back off so rotation/scale do not leak into x/y. For the
+// T·S·R order: a = sx·cos θ, b = sy·sin θ, c = -sx·sin θ, d = sy·cos θ.
+function decompose(v: number[], origin: string): Target {
+	const [ox, oy] = origin.split(' ').map((part) => Number.parseFloat(part) || 0)
+	const [a, b, c, d, e, f] = v.length === 16 ? [v[0], v[1], v[4], v[5], v[12], v[13]] : v
+	const scaleX = Math.hypot(a, c)
+	const scaleY = Math.hypot(b, d)
+	let rotate = scaleX && scaleY ? (Math.atan2(b / scaleY, a / scaleX) * 180) / Math.PI : 0
+	if (!Number.isFinite(rotate)) {
+		rotate = 0
+	}
+
+	let flippedY = scaleY
+	// A negative determinant means one axis flipped; folding the sign into
+	// scaleY and the angle round-trips the same matrix for every composition.
+	if (a * d - b * c < 0) {
+		flippedY = -scaleY
+		rotate = -rotate
+	}
+
+	return {
+		x: e + (a - 1) * ox + c * oy,
+		y: f + b * ox + (d - 1) * oy,
+		scaleX,
+		scaleY: flippedY,
+		rotate,
+	}
+}
+
+function readChannels(node: HTMLElement, fallback: Target): Target {
+	const computed = getComputedStyle(node)
+	const opacity = Number(computed.opacity)
+	const base: Target = {
+		...fallback,
+		opacity: Number.isFinite(opacity) ? opacity : (fallback.opacity ?? 1),
+	}
+
+	const match = /matrix(?:3d)?\(([^)]*)\)/.exec(computed.transform)
+	if (!match) {
+		return computed.transform === 'none'
+			? { ...base, x: 0, y: 0, scaleX: 1, scaleY: 1, rotate: 0 }
+			: base
+	}
+
+	const values = match[1].split(',').map(Number.parseFloat)
+	return values.every(Number.isFinite)
+		? { ...base, ...decompose(values, computed.transformOrigin) }
+		: base
+}
+
+function waapiRun(
+	node: HTMLElement,
+	req: DelegatedRequest,
+	write: (t: Target) => void,
+): DelegatedRun | null {
+	if (typeof node.animate !== 'function') {
+		return null
+	}
+
+	const { target, eff, transition: t } = req
+	const animatesTransform = TRANSFORM_KEYS.some((key) => target[key] !== undefined)
+	if (!animatesTransform && target.opacity === undefined) {
+		return null
+	}
+
+	// Explicit keyframe pairs keep the interpolation in matched-list mode; an
+	// implicit "from" resolves to a matrix and would lose rotate windings.
+	let last = readChannels(node, { opacity: 1, x: 0, y: 0, scaleX: 1, scaleY: 1, rotate: 0 })
+	const frames: Keyframe[] = [{}, {}]
+	if (animatesTransform) {
+		frames[0].transform = transform(last)
+		frames[1].transform = transform(eff)
+	}
+
+	if (target.opacity !== undefined) {
+		frames[0].opacity = last.opacity ?? 1
+		frames[1].opacity = Math.min(1, Math.max(0, eff.opacity ?? 1))
+	}
+
+	const [x1, y1, x2, y2] = bezierPoints(t.ease)
+	let animation: Animation
+	try {
+		animation = node.animate(frames, {
+			duration: (t.duration ?? 0.3) * 1000,
+			delay: (t.delay ?? 0) * 1000,
+			easing: `cubic-bezier(${x1}, ${y1}, ${x2}, ${y2})`,
+			fill: 'forwards',
+		})
+	} catch {
+		return null
+	}
+
+	const sample = (): Target => {
+		last = readChannels(node, last)
+		return { ...last }
+	}
+
+	let resolve!: (result: 'finished' | 'cancelled') => void
+	const finished = new Promise<'finished' | 'cancelled'>((done) => {
+		resolve = done
+	})
+
+	let settled = false
+	const settle = (result: 'finished' | 'cancelled') => {
+		if (!settled) {
+			settled = true
+			resolve(result)
+		}
+	}
+
+	// The platform run owns presentation; sample() reads the composited state.
+	// On finish the destination is committed to the base styles before the
+	// fill is released, so later adapter writes still apply.
+	const complete = () => {
+		write(req.dest)
+		settle('finished')
+		animation.cancel()
+	}
+
+	const cancelled = () => settle('cancelled')
+	if (typeof animation.finished?.then === 'function') {
+		// finished rejects with AbortError on cancel — observed here.
+		void animation.finished.then(complete, cancelled)
+	} else {
+		animation.onfinish = complete
+		animation.oncancel = cancelled
+	}
+
+	return {
+		finished,
+		sample,
+		cancel() {
+			// Cancel reverts the element to its base styles synchronously, so the
+			// presentation is sampled first and the adapter write holds the
+			// frozen values for the next run's "from" keyframe.
+			const current = sample()
+			animation.cancel()
+			write(current)
+			settle('cancelled')
+		},
+	}
+}
+
+// Mirrors the native delegatedRun contract: cubic-bezier eases only, null on
+// any missing capability so the caller stays on the JS engine.
+export function delegatedRun(
+	node: HTMLElement,
+	req: DelegatedRequest,
+	write: (t: Target) => void,
+): DelegatedRun | null {
+	if (!isBezierEase(req.transition.ease)) {
+		delegationStats().fallback++
+		return null
+	}
+
+	const run = waapiRun(node, req, write)
+	if (!run) {
+		delegationStats().fallback++
+		return null
+	}
+
+	return trackDelegatedRun(run)
+}

package/src/engine.test.ts

@@ -123,4 +123,103 @@ describe('portable playback', () => {
 		expect(await result).toBe('replaced')
 		expect(time.count()).toBe(0)
 	})
+
+	it('reduces positional springs immediately while preserving opacity motion', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		const result = controller.animate({ x: 100, opacity: 0 }, { type: 'spring' }, true)
+
+		expect(controller.snapshot()).toMatchObject({ x: 100, opacity: 1 })
+		expect(time.count()).toBe(1)
+		time.advance(10000)
+		expect(await result).toBe('finished')
+		expect(controller.snapshot()).toEqual({ x: 100, opacity: 0 })
+		controller.destroy()
+	})
+})
+
+describe('upstream-shaped transitions', () => {
+	it('repeats a tween for the given number of additional legs', async () => {
+		const time = fakeClock()
+		const seen: number[] = []
+		const controls = runAnimation(
+			time.clock,
+			0,
+			100,
+			{ duration: 0.1, ease: 'linear', repeat: 1 },
+			(value) => seen.push(value),
+		)
+
+		time.advance(120)
+		expect(seen.at(-1)).toBe(100)
+		time.advance(50)
+		expect(seen.at(-1)).toBe(50)
+		time.advance(120)
+		expect(seen.at(-1)).toBe(100)
+		expect(await controls.finished).toBe('finished')
+	})
+
+	it('reverses each repeated leg under repeatType reverse', async () => {
+		const time = fakeClock()
+		const seen: number[] = []
+		const controls = runAnimation(
+			time.clock,
+			0,
+			100,
+			{ duration: 0.1, ease: 'linear', repeat: 1, repeatType: 'reverse' },
+			(value) => seen.push(value),
+		)
+
+		time.advance(120)
+		time.advance(50)
+		expect(seen.at(-1)).toBe(50)
+		time.advance(120)
+		expect(seen.at(-1)).toBe(0)
+		expect(await controls.finished).toBe('finished')
+	})
+
+	it('accepts a duration/bounce spring spec', async () => {
+		const time = fakeClock()
+		let value = 0
+		const controls = runAnimation(
+			time.clock,
+			0,
+			100,
+			{ type: 'spring', duration: 0.4, bounce: 0.2 },
+			(next) => {
+				value = next
+			},
+		)
+
+		for (let i = 0; i < 100; i++) {
+			time.advance(16)
+		}
+
+		expect(await controls.finished).toBe('finished')
+		expect(value).toBe(100)
+	})
+
+	it('accepts the full named-ease set on the JS engine', async () => {
+		for (const ease of ['circIn', 'backOut', 'anticipate', 'circInOut', 'backInOut'] as const) {
+			const time = fakeClock()
+			let value = 0
+			const controls = runAnimation(time.clock, 0, 50, { duration: 0.1, ease }, (next) => {
+				value = next
+			})
+
+			for (let i = 0; i < 20; i++) {
+				time.advance(16)
+			}
+
+			expect(await controls.finished).toBe('finished')
+			expect(value).toBe(50)
+		}
+	})
+
+	it('rejects fractional repeats', () => {
+		const time = fakeClock()
+		expect(() => runAnimation(time.clock, 0, 1, { duration: 1, repeat: 1.5 }, () => {})).toThrow(
+			'repeat',
+		)
+	})
 })

package/src/engine.ts

@@ -1,6 +1,12 @@
 import { keyframes, spring } from 'motion-dom'
-import type { Clock } from './clock-types'
-import type { Transition } from './types'
+import type { Clock } from './clock-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 = [
+	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)
+			}
+		},
+	}
 }