@octane-xplat/motion 0.9.0 → 0.10.0

package/src/driver.ts

@@ -0,0 +1,249 @@
+import type { DelegatedRequest, DelegatedRun } from './host-types'
+import { bezierPoints, isBezierEase } from './engine'
+import { delegationStats, trackDelegatedRun } from './delegation'
+import type { Target } from './types'
+
+const platform = globalThis as any
+
+function iosRun(node: any, req: DelegatedRequest, write: (t: Target) => void): DelegatedRun | null {
+	const view = node.ios ?? node.nativeViewProtected
+	if (!view?.layer || !platform.UIViewPropertyAnimator) {
+		return null
+	}
+
+	const { eff, target, transition: t } = req
+	const [x1, y1, x2, y2] = bezierPoints(t.ease)
+	const params = platform.UICubicTimingParameters.alloc().initWithControlPoint1ControlPoint2(
+		platform.CGPointMake(x1, y1),
+		platform.CGPointMake(x2, y2),
+	)
+
+	const animator = platform.UIViewPropertyAnimator.alloc().initWithDurationTimingParameters(
+		t.duration ?? 0.3,
+		params,
+	)
+
+	// UIViewPropertyAnimator owns view.transform/alpha presentation; the model
+	// props land at the destination immediately, so sample() reads the
+	// presentation layer and cancel() syncs the model back before stopping.
+	const radians = ((eff.rotate ?? 0) * Math.PI) / 180
+	const dest = platform.CGAffineTransformScale(
+		platform.CGAffineTransformRotate(
+			platform.CGAffineTransformMakeTranslation(eff.x ?? 0, eff.y ?? 0),
+			radians,
+		),
+		eff.scaleX ?? 1,
+		eff.scaleY ?? 1,
+	)
+
+	const sample = (): Target => {
+		const layer = view.layer.presentationLayer?.() ?? view.layer
+		const tr = layer.transform
+		return {
+			opacity: layer.opacity,
+			x: tr.m41,
+			y: tr.m42,
+			scaleX: Math.hypot(tr.m11, tr.m12),
+			scaleY: Math.hypot(tr.m21, tr.m22),
+			rotate: (Math.atan2(tr.m12, tr.m11) * 180) / Math.PI,
+		}
+	}
+
+	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)
+		}
+	}
+
+	animator.addAnimations(() => {
+		if (
+			target.x !== undefined ||
+			target.y !== undefined ||
+			target.rotate !== undefined ||
+			target.scale !== undefined ||
+			target.scaleX !== undefined ||
+			target.scaleY !== undefined
+		) {
+			view.transform = dest
+		}
+
+		if (target.opacity !== undefined) {
+			view.alpha = Math.min(1, Math.max(0, eff.opacity ?? target.opacity))
+		}
+	})
+
+	animator.addCompletion((position: number) => {
+		if (position === 0) {
+			write(req.dest)
+			settle('finished')
+		} else {
+			settle('cancelled')
+		}
+	})
+
+	if (t.delay) {
+		animator.startAnimationAfterDelay(t.delay)
+	} else {
+		animator.startAnimation()
+	}
+
+	return {
+		finished,
+		sample,
+		cancel() {
+			const current = sample()
+			animator.stopAnimation(true)
+			write({
+				opacity: current.opacity,
+				x: current.x,
+				y: current.y,
+				scaleX: current.scaleX,
+				scaleY: current.scaleY,
+				rotate: current.rotate,
+			})
+
+			settle('cancelled')
+		},
+	}
+}
+
+function androidRun(
+	node: any,
+	req: DelegatedRequest,
+	write: (t: Target) => void,
+): DelegatedRun | null {
+	const view = node.nativeViewProtected ?? node.android
+	const android = platform.android
+	const androidx = platform.androidx
+	if (
+		!view?.animate ||
+		!android?.animation ||
+		!androidx?.core?.view?.animation?.PathInterpolatorCompat
+	) {
+		return null
+	}
+
+	const { eff, target, transition: t } = req
+	const animator = view.animate()
+	const [x1, y1, x2, y2] = bezierPoints(t.ease)
+	animator.setInterpolator(
+		androidx.core.view.animation.PathInterpolatorCompat.create(x1, y1, x2, y2),
+	)
+
+	animator.setDuration(Math.round((t.duration ?? 0.3) * 1000))
+	animator.setStartDelay(Math.round((t.delay ?? 0) * 1000))
+	if (target.x !== undefined) {
+		animator.translationX(eff.x)
+	}
+
+	if (target.y !== undefined) {
+		animator.translationY(eff.y)
+	}
+
+	if (target.scale !== undefined || target.scaleX !== undefined) {
+		animator.scaleX(eff.scaleX)
+	}
+
+	if (target.scale !== undefined || target.scaleY !== undefined) {
+		animator.scaleY(eff.scaleY)
+	}
+
+	if (target.rotate !== undefined) {
+		animator.rotation(eff.rotate)
+	}
+
+	if (target.opacity !== undefined) {
+		animator.alpha(Math.min(1, Math.max(0, eff.opacity ?? target.opacity)))
+	}
+
+	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)
+		}
+	}
+
+	// onAnimationCancel is always followed by onAnimationEnd — track it so the
+	// end callback only commits the destination for a run that truly finished.
+	let cancelled = false
+	animator.setListener(
+		new android.animation.Animator.AnimatorListener({
+			onAnimationCancel() {
+				cancelled = true
+				settle('cancelled')
+			},
+			onAnimationEnd() {
+				if (!cancelled) {
+					// ViewPropertyAnimator leaves native props at the destination;
+					// committing keeps the NativeScript property cache coherent.
+					write(req.dest)
+				}
+
+				settle(cancelled ? 'cancelled' : 'finished')
+			},
+			onAnimationStart() {},
+			onAnimationRepeat() {},
+		}),
+	)
+
+	animator.start()
+
+	return {
+		finished,
+		sample: () => ({
+			opacity: view.getAlpha(),
+			x: view.getTranslationX(),
+			y: view.getTranslationY(),
+			scaleX: view.getScaleX(),
+			scaleY: view.getScaleY(),
+			rotate: view.getRotation(),
+		}),
+		cancel() {
+			animator.cancel()
+		},
+	}
+}
+
+// Platform animators drive the presentation while MotionValues track sampled
+// state; interruption stays velocity-exact on the JS engine. Falls back to
+// null anywhere the platform object is missing (tests, unknown targets).
+export function delegatedRun(
+	node: any,
+	req: DelegatedRequest,
+	write: (t: Target) => void,
+): DelegatedRun | null {
+	// Dispatch on platform-object presence — no @nativescript/core import, so
+	// this module stays loadable in the object-driver test environment. Eases
+	// that are not cubic-bezier-expressible stay on the JS engine.
+	if (!isBezierEase(req.transition.ease)) {
+		delegationStats().fallback++
+		return null
+	}
+
+	const run =
+		node.ios && platform.UIViewPropertyAnimator
+			? iosRun(node, req, write)
+			: platform.android?.animation && (node.nativeViewProtected ?? node.android)
+				? androidRun(node, req, write)
+				: null
+
+	if (!run) {
+		delegationStats().fallback++
+		return null
+	}
+
+	return trackDelegatedRun(run)
+}

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

@@ -137,3 +137,89 @@ describe('portable playback', () => {
 		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',
+		)
+	})
+})