@octane-xplat/motion 0.7.3 → 0.10.0

package/src/delegation.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest'
+import { Controller } from './controller'
+import type { Clock } from './clock-types'
+import type { DelegatedRequest, DelegatedRun, HostAdapter } from './host-types'
+import type { Target } from './types'
+
+function fakeClock() {
+	let time = 0,
+		id = 0
+
+	const callbacks = new Map<number, () => void>()
+	const clock: Clock = {
+		now: () => time,
+		request: (fn) => {
+			callbacks.set(++id, fn)
+			return id
+		},
+		cancel: (key) => {
+			callbacks.delete(key)
+		},
+	}
+
+	return {
+		clock,
+		advance(ms: number) {
+			time += ms
+			const pending = [...callbacks.values()]
+			callbacks.clear()
+			pending.forEach((fn) => fn())
+		},
+		count: () => callbacks.size,
+	}
+}
+
+interface FakeRun extends DelegatedRun {
+	resolve(result: 'finished' | 'cancelled'): void
+	setEff(next: Target): void
+	cancelCalls: number
+}
+
+function fakeRun(eff: Target): FakeRun {
+	let resolve!: (result: 'finished' | 'cancelled') => void
+	let current = { ...eff }
+	const run: FakeRun = {
+		finished: new Promise((done) => {
+			resolve = done
+		}),
+		sample: () => ({ ...current }),
+		cancelCalls: 0,
+		cancel() {
+			run.cancelCalls++
+			run.resolve('cancelled')
+		},
+		resolve,
+		setEff(next) {
+			current = { ...next }
+		},
+	}
+
+	return run
+}
+
+function stubHost(onDelegate?: (req: DelegatedRequest) => DelegatedRun | null) {
+	const written: Target[] = []
+	const adapter: HostAdapter = {
+		read: () => ({ opacity: 1, x: 0, y: 0, scale: 1, scaleX: 1, scaleY: 1, rotate: 0 }),
+		write: (target) => {
+			written.push({ ...target })
+		},
+		restore: () => {},
+		delegate: onDelegate,
+	}
+
+	return { adapter, written }
+}
+
+describe('delegated runs', () => {
+	it('hands a tween to the host driver and resolves finished at the destination', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		let request: DelegatedRequest | undefined
+		const run = fakeRun({ x: 0 })
+		const { adapter } = stubHost((req) => {
+			request = req
+			return run
+		})
+
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const done = controller.animate({ x: 100 }, { duration: 0.5 }, false)
+		expect(request?.eff.x).toBe(100)
+		expect(request?.target.x).toBe(100)
+
+		run.setEff({ x: 40 })
+		time.advance(16)
+		run.resolve('finished')
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(100)
+		expect(time.count()).toBe(0)
+	})
+
+	it('folds scale into the effective axis and tracks samples back', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		let request: DelegatedRequest | undefined
+		const run = fakeRun({ scaleX: 0.5, scaleY: 0.5 })
+		const { adapter } = stubHost((req) => {
+			request = req
+			return run
+		})
+
+		controller.attach(adapter)
+		controller.seed({ scaleX: 0.5 })
+
+		const done = controller.animate({ scale: 2 }, { duration: 0.4 }, false)
+		// Retained scaleX=0.5 folds into the effective destination.
+		expect(request?.eff.scaleX).toBe(1)
+		expect(request?.eff.scaleY).toBe(2)
+		run.setEff({ scaleX: 0.9, scaleY: 0.9 })
+		time.advance(16)
+		// scale channel tracks effective / retained scaleX.
+		expect(controller.values.get('scale')?.get()).toBeCloseTo(1.8)
+		run.resolve('finished')
+		expect(await done).toBe('finished')
+		expect(controller.values.get('scale')?.get()).toBe(2)
+	})
+
+	it('interrupts a delegated run with a tracked sample and resolves replaced', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		const first = fakeRun({ x: 0 })
+		const second = fakeRun({ x: 30 })
+		const runs = [first, second]
+		let calls = 0
+		const { adapter } = stubHost(() => runs[calls++ % runs.length])
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const doneFirst = controller.animate({ x: 100 }, { duration: 0.5 }, false)
+		first.setEff({ x: 30 })
+		time.advance(16)
+		const doneSecond = controller.animate({ x: -50 }, { duration: 0.5 }, false)
+		expect(first.cancelCalls).toBe(1)
+		// The interruption sample is written into the channel value.
+		expect(controller.values.get('x')?.get()).toBe(30)
+		expect(await doneFirst).toBe('replaced')
+		second.setEff({ x: -20 })
+		time.advance(16)
+		expect(controller.values.get('x')?.get()).toBe(-20)
+		second.resolve('finished')
+		expect(await doneSecond).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(-50)
+	})
+
+	it('keeps springs on the JS engine', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		let delegated = false
+		const { adapter } = stubHost(() => {
+			delegated = true
+			return null
+		})
+
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const done = controller.animate(
+			{ x: 100 },
+			{ type: 'spring', stiffness: 100, damping: 10 },
+			false,
+		)
+
+		expect(delegated).toBe(false)
+		for (let i = 0; i < 400; i++) {
+			time.advance(16)
+		}
+
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(100)
+	})
+
+	it('keeps reduced-motion runs on the JS engine for instant settle', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		let delegated = false
+		const { adapter, written } = stubHost(() => {
+			delegated = true
+			return null
+		})
+
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const done = controller.animate({ x: 50 }, { duration: 0.5 }, true)
+		expect(delegated).toBe(false)
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(50)
+		expect(written[written.length - 1]?.x).toBe(50)
+	})
+
+	it('resolves replaced when the delegated run is stopped', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		const run = fakeRun({ x: 0 })
+		const { adapter } = stubHost(() => run)
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const done = controller.animate({ x: 100 }, { duration: 0.5 }, false)
+		controller.stop()
+		expect(run.cancelCalls).toBe(1)
+		expect(await done).toBe('replaced')
+	})
+
+	it.each([
+		['per-key transitions', { default: { duration: 0.5 }, x: { duration: 1 } }],
+		['a non-bezier ease', { duration: 0.5, ease: 'backOut' as const }],
+		['a repeating run', { duration: 0.5, repeat: 2 }],
+	])('stays on the JS engine for %s', async (_label, transition) => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		let delegated = false
+		const { adapter } = stubHost(() => {
+			delegated = true
+			return null
+		})
+
+		controller.attach(adapter)
+		controller.seed({ x: 0 })
+
+		const done = controller.animate({ x: 100 }, transition as any, false)
+		expect(delegated).toBe(false)
+		for (let i = 0; i < 500; i++) {
+			time.advance(16)
+		}
+
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(100)
+	})
+
+	it('applies per-key overrides to each channel independently', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		const { adapter } = stubHost()
+		controller.attach(adapter)
+		controller.seed({ x: 0, y: 0 })
+
+		const done = controller.animate(
+			{ x: 100, y: 100 },
+			{ default: { duration: 0.1, ease: 'linear' }, x: { duration: 0.3 } },
+			false,
+		)
+
+		for (let i = 0; i < 8; i++) {
+			time.advance(16)
+		}
+
+		// y finished at 100ms; x still travelling on its 300ms override.
+		expect(controller.values.get('y')?.get()).toBe(100)
+		expect(controller.values.get('x')?.get()).toBeLessThan(100)
+		for (let i = 0; i < 30; i++) {
+			time.advance(16)
+		}
+
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(100)
+	})
+})

package/src/delegation.ts

@@ -0,0 +1,29 @@
+import type { DelegatedRun } from './host-types'
+
+// Probe-visible counters so retained probes can distinguish a real delegated
+// run from a silent JS-engine fallback without widening the public API.
+export function delegationStats() {
+	const platform = globalThis as any
+	return (platform.__xplatMotionDelegations ??= {
+		started: 0,
+		finished: 0,
+		cancelled: 0,
+		fallback: 0,
+	})
+}
+
+/** Count a delegated run and fold its settled result into the counters. */
+export function trackDelegatedRun(run: DelegatedRun): DelegatedRun {
+	delegationStats().started++
+	const finished = run.finished.then((result) => {
+		if (result === 'finished') {
+			delegationStats().finished++
+		} else {
+			delegationStats().cancelled++
+		}
+
+		return result
+	})
+
+	return { ...run, finished }
+}

package/src/delegation.web.test.ts

@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { Controller } from './controller'
+import { delegatedRun } from './driver.web'
+import { attachHost } from './host.web'
+import type { Clock } from './clock-types'
+import type { Target } from './types'
+
+function fakeClock() {
+	let time = 0,
+		id = 0
+
+	const callbacks = new Map<number, () => void>()
+	const clock: Clock = {
+		now: () => time,
+		request: (fn) => {
+			callbacks.set(++id, fn)
+			return id
+		},
+		cancel: (key) => {
+			callbacks.delete(key)
+		},
+	}
+
+	return {
+		clock,
+		advance(ms: number) {
+			time += ms
+			const pending = [...callbacks.values()]
+			callbacks.clear()
+			pending.forEach((fn) => fn())
+		},
+		count: () => callbacks.size,
+	}
+}
+
+// Web delegated driver — jsdom ships no `element.animate`, so a fake
+// Animation models the browser: `presented` stands in for the animation
+// cascade over the element's base styles, and cancel() reveals the base
+// again like a real reverted WAAPI run.
+function styleToMatrix(style: string): string {
+	if (!style || style === 'none' || style.startsWith('matrix')) {
+		return style || 'none'
+	}
+
+	const channel = (name: string, dflt: number) => {
+		const match = new RegExp(`${name}\\((-?[\\d.eE+-]+)`).exec(style)
+		return match ? Number.parseFloat(match[1]) : dflt
+	}
+
+	const x = channel('translateX', 0)
+	const y = channel('translateY', 0)
+	const sx = channel('scale', 1) * channel('scaleX', 1)
+	const sy = channel('scale', 1) * channel('scaleY', 1)
+	const rad = (channel('rotate', 0) * Math.PI) / 180
+	return `matrix(${sx * Math.cos(rad)}, ${sy * Math.sin(rad)}, ${-sx * Math.sin(rad)}, ${sy * Math.cos(rad)}, ${x}, ${y})`
+}
+
+function fakeWebElement() {
+	const animations: any[] = []
+	let presented: { transform?: string; opacity?: string } | null = null
+	const el: any = {
+		style: { transform: '', opacity: '', transformOrigin: '' },
+	}
+
+	el.animate = (keyframes: any[], options: any) => {
+		let resolve!: (value: any) => void
+		let reject!: (reason: any) => void
+		const animation: any = {
+			keyframes,
+			options,
+			cancelled: false,
+			finished: new Promise((res, rej) => {
+				resolve = res
+				reject = rej
+			}),
+			present(transform: string, opacity?: string) {
+				presented = { transform, opacity }
+			},
+			finish() {
+				const last = keyframes[keyframes.length - 1] ?? {}
+				presented = {
+					transform: last.transform,
+					opacity: last.opacity === undefined ? undefined : String(last.opacity),
+				}
+
+				resolve(animation)
+			},
+			cancel() {
+				animation.cancelled = true
+				presented = null
+				reject(new Error('AbortError'))
+			},
+		}
+
+		animations.push(animation)
+		return animation
+	}
+
+	const computedFor = (node: any) => ({
+		transform: node === el ? (presented?.transform ?? styleToMatrix(el.style.transform)) : 'none',
+		opacity:
+			node === el
+				? (presented?.opacity ?? (el.style.opacity === '' ? '1' : el.style.opacity))
+				: '1',
+		transformOrigin: node === el ? el.style.transformOrigin || '0px 0px' : '0px 0px',
+	})
+
+	vi.stubGlobal('getComputedStyle', computedFor)
+	return { el, animations }
+}
+
+const delegationCounters = () =>
+	((globalThis as any).__xplatMotionDelegations ??= {
+		started: 0,
+		finished: 0,
+		cancelled: 0,
+		fallback: 0,
+	})
+
+describe('web WAAPI delegation', () => {
+	beforeEach(() => {
+		delete (globalThis as any).__xplatMotionDelegations
+	})
+
+	afterEach(() => {
+		vi.unstubAllGlobals()
+	})
+
+	const request = (target: Target, transition: any = { duration: 0.5, ease: 'easeOut' }) => ({
+		target,
+		dest: { opacity: 1, x: 0, y: 0, scale: 1, scaleX: 1, scaleY: 1, rotate: 0, ...target },
+		eff: { opacity: 1, x: 0, y: 0, scaleX: 1, scaleY: 1, rotate: 0, ...target },
+		transition,
+	})
+
+	it('hands a bezier tween to element.animate and commits the destination on finish', async () => {
+		const { el, animations } = fakeWebElement()
+		const written: Target[] = []
+		const run = delegatedRun(
+			el,
+			request({ x: 100, opacity: 0.5 }, { duration: 0.5, delay: 0.1, ease: 'easeOut' }),
+			(target) => written.push({ ...target }),
+		)
+
+		expect(run).not.toBeNull()
+		expect(animations).toHaveLength(1)
+		const animation = animations[0]
+		expect(animation.options).toMatchObject({
+			duration: 500,
+			delay: 100,
+			easing: 'cubic-bezier(0, 0, 0.58, 1)',
+			fill: 'forwards',
+		})
+
+		expect(animation.keyframes[0].transform).toBe(
+			'translateX(0px) translateY(0px) scaleX(1) scaleY(1) rotate(0deg)',
+		)
+
+		expect(animation.keyframes[1].transform).toBe(
+			'translateX(100px) translateY(0px) scaleX(1) scaleY(1) rotate(0deg)',
+		)
+
+		expect(animation.keyframes[1].opacity).toBe(0.5)
+		expect(delegationCounters().started).toBe(1)
+
+		animation.present('matrix(1, 0, 0, 1, 40, 0)')
+		expect(run!.sample()).toMatchObject({ x: 40, scaleX: 1 })
+		animation.finish()
+		await expect(run!.finished).resolves.toBe('finished')
+		expect(written.at(-1)).toMatchObject({ x: 100, opacity: 0.5 })
+		expect(delegationCounters().finished).toBe(1)
+	})
+
+	it('samples the presentation before cancelling so the frozen values hold', async () => {
+		const { el, animations } = fakeWebElement()
+		const written: Target[] = []
+		const run = delegatedRun(el, request({ x: 100 }), (target) => written.push({ ...target }))
+
+		const animation = animations[0]
+		animation.present('matrix(0.5, 0, 0, 0.5, 42, 7)')
+		run!.cancel()
+		expect(animation.cancelled).toBe(true)
+		// cancel() reveals the base style — if the sample ran after it, the
+		// write would carry identity values instead of the mid-flight frame.
+		expect(written.at(-1)).toMatchObject({ x: 42, y: 7, scaleX: 0.5, scaleY: 0.5, rotate: 0 })
+		await expect(run!.finished).resolves.toBe('cancelled')
+		expect(delegationCounters().cancelled).toBe(1)
+	})
+
+	it('decomposes matrix3d and peels transform-origin out of x/y', () => {
+		const { el, animations } = fakeWebElement()
+		el.style.transformOrigin = '10px 20px'
+		const run = delegatedRun(el, request({ rotate: 90 }), () => {})
+
+		const animation = animations[0]
+		animation.present('matrix3d(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 25, 5, 0, 1)')
+		expect(run!.sample()).toMatchObject({ x: 25, y: 5, scaleX: 1, scaleY: 1, rotate: 0 })
+		// rotate(90deg) about a (10, 20) origin resolves to this matrix.
+		animation.present('matrix(0, 1, -1, 0, 30, 10)')
+		const sampled = run!.sample()
+		expect(sampled.rotate).toBeCloseTo(90)
+		expect(sampled.x).toBeCloseTo(0)
+		expect(sampled.y).toBeCloseTo(0)
+	})
+
+	it('refuses non-bezier eases and elements without a WAAPI driver', () => {
+		const { el } = fakeWebElement()
+		const run = delegatedRun(el, request({ x: 100 }, { duration: 0.5, ease: 'backOut' }), () => {})
+
+		expect(run).toBeNull()
+		expect(delegatedRun({ style: {} }, request({ x: 50 }), () => {})).toBeNull()
+		expect(delegationCounters().fallback).toBe(2)
+		expect(delegationCounters().started).toBe(0)
+	})
+
+	it('delegates through the real web adapter and hands mid-flight state to the next run', async () => {
+		const { el, animations } = fakeWebElement()
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		controller.attach(attachHost(el))
+		controller.seed({ x: 0 })
+
+		const doneFirst = controller.animate({ x: 100 }, { duration: 0.5, ease: 'linear' }, false)
+		expect(animations).toHaveLength(1)
+		animations[0].present('matrix(1, 0, 0, 1, 30, 0)')
+		time.advance(16)
+
+		const doneSecond = controller.animate({ x: -50 }, { duration: 0.5 }, false)
+		expect(animations[0].cancelled).toBe(true)
+		// Interruption sampled into the channel value and velocity.
+		expect(controller.values.get('x')?.get()).toBe(30)
+		expect(controller.values.get('x')?.getVelocity()).toBeGreaterThan(0)
+		// The replacement run's "from" keyframe continues the frozen frame.
+		expect(animations[1].keyframes[0].transform).toBe(
+			'translateX(30px) translateY(0px) scaleX(1) scaleY(1) rotate(0deg)',
+		)
+
+		expect(await doneFirst).toBe('replaced')
+		animations[1].finish()
+		expect(await doneSecond).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(-50)
+		expect(el.style.transform).toBe(
+			'translateX(-50px) translateY(0px) scale(1) scaleX(1) scaleY(1) rotate(0deg)',
+		)
+	})
+
+	it.each([
+		['a spring', { type: 'spring', stiffness: 100, damping: 10 }, false],
+		['a non-bezier ease', { duration: 0.5, ease: 'backOut' as const }, false],
+		['a repeating run', { duration: 0.5, repeat: 2 }, false],
+		['per-key transitions', { default: { duration: 0.5 }, x: { duration: 1 } }, false],
+		['an instant run', { duration: 0 }, false],
+		['reduced motion', { duration: 0.5 }, true],
+	])('stays on the JS engine for %s', async (_label, transition, reduced) => {
+		const { el, animations } = fakeWebElement()
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		controller.attach(attachHost(el))
+		controller.seed({ x: 0 })
+
+		const done = controller.animate({ x: 100 }, transition as any, reduced)
+		expect(animations).toHaveLength(0)
+		for (let i = 0; i < 500; i++) {
+			time.advance(16)
+		}
+
+		expect(await done).toBe('finished')
+		expect(controller.values.get('x')?.get()).toBe(100)
+	})
+})

package/src/drag.mobile.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest'
+import { attachPan } from './pan'
+import {
+	handlers,
+	GestureHandlerStateEvent,
+	GestureHandlerTouchEvent,
+	GestureState,
+} from '../test/gesturehandler'
+
+describe('native handler drag surface', () => {
+	it('configures arbitration, normalizes velocity, and detaches handlers', () => {
+		const start = vi.fn(),
+			move = vi.fn(),
+			end = vi.fn()
+
+		const node = {}
+		const off = attachPan(node, 'x', { start, move, end })
+		const h = handlers.at(-1)
+		expect(h.node).toBe(node)
+		expect(h.options).toMatchObject({
+			activeOffsetXStart: -8,
+			activeOffsetXEnd: 8,
+			failOffsetYStart: -8,
+			failOffsetYEnd: 8,
+		})
+
+		h.emit(GestureHandlerStateEvent, { state: GestureState.BEGAN })
+		expect(start).not.toHaveBeenCalled()
+		h.emit(GestureHandlerStateEvent, {
+			state: GestureState.ACTIVE,
+			extraData: { translationX: 10, velocityX: 300 },
+		})
+
+		h.emit(GestureHandlerTouchEvent, {
+			state: GestureState.ACTIVE,
+			extraData: { translationX: 25, velocityX: 400 },
+		})
+
+		expect(move.mock.calls.at(-1)?.[1]).toMatchObject({
+			offset: { x: 25, y: 0 },
+			delta: { x: 15, y: 0 },
+			velocity: { x: 400, y: 0 },
+		})
+
+		h.emit(GestureHandlerStateEvent, {
+			state: GestureState.CANCELLED,
+			extraData: { translationX: 25 },
+		})
+
+		h.emit(GestureHandlerStateEvent, { state: GestureState.END })
+		expect(end).toHaveBeenCalledTimes(1)
+		expect(end.mock.calls[0][1].cancelled).toBe(true)
+		off()
+		expect(h.node).toBeUndefined()
+		h.emit(GestureHandlerTouchEvent, { state: GestureState.ACTIVE })
+		expect(move).toHaveBeenCalledTimes(2)
+	})
+
+	it('uses minDist for both axes and fails perpendicular movement for vertical drag', () => {
+		const callbacks = { start() {}, move() {}, end() {} }
+		const both = attachPan({}, true, callbacks)
+		expect(handlers.at(-1).options.minDist).toBe(8)
+		both()
+		const vertical = attachPan({}, 'y', callbacks)
+		expect(handlers.at(-1).options).toMatchObject({ activeOffsetYEnd: 8, failOffsetXStart: -8 })
+		vertical()
+		vi.stubGlobal('android', {})
+		const density = attachPan({}, true, callbacks)
+		expect(handlers.at(-1).options.minDist).toBe(16)
+		density()
+		const directional = attachPan({}, 'x', callbacks)
+		expect(handlers.at(-1).options).toMatchObject({
+			minDist: 1e9,
+			activeOffsetXEnd: 16,
+			failOffsetYEnd: 16,
+		})
+
+		directional()
+		vi.unstubAllGlobals()
+	})
+})