@octane-xplat/motion 0.0.0 → 0.7.0

package/src/engine.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+import { spring } from 'motion-dom'
+import { runAnimation } from './engine'
+import { MotionValue } from './value'
+import { Controller } from './controller'
+import type { Clock } from './clock-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,
+	}
+}
+
+describe('portable playback', () => {
+	it('uses elapsed time and reaches the exact tween endpoint after suspension', async () => {
+		const time = fakeClock()
+		let value = 0
+		const controls = runAnimation(
+			time.clock,
+			0,
+			100,
+			{ duration: 1, delay: 0.1, ease: 'linear' },
+			(next) => {
+				value = next
+			},
+		)
+
+		time.advance(50)
+		expect(value).toBe(0)
+		time.advance(550)
+		expect(value).toBeCloseTo(50)
+		time.advance(10000)
+		expect(value).toBe(100)
+		expect(await controls.finished).toBe('finished')
+		expect(time.count()).toBe(0)
+	})
+
+	it('matches upstream spring samples at irregular frame intervals', () => {
+		const time = fakeClock()
+		let value = 0
+		const options = { stiffness: 180, damping: 16, mass: 2, velocity: 90 }
+		const reference = spring({ ...options, keyframes: [0, 100] })
+		runAnimation(time.clock, 0, 100, { ...options, type: 'spring' }, (next) => {
+			value = next
+		})
+
+		let elapsed = 0
+		for (const dt of [8, 16, 34, 5, 100, 10000]) {
+			elapsed += dt
+			time.advance(dt)
+			const expected = reference.next(elapsed)
+			expect(value).toBeCloseTo(expected.done ? 100 : expected.value)
+		}
+
+		expect(value).toBe(100)
+	})
+
+	it('settles cancellation once and never calls completion', async () => {
+		const time = fakeClock()
+		let completes = 0
+		const controls = runAnimation(
+			time.clock,
+			0,
+			1,
+			{},
+			() => {},
+			() => {
+				completes++
+			},
+		)
+
+		controls.stop()
+		controls.stop()
+		time.advance(1000)
+		expect(await controls.finished).toBe('cancelled')
+		expect(completes).toBe(0)
+	})
+
+	it('preserves velocity on retarget and jump cancels/reset velocity', async () => {
+		const time = fakeClock()
+		const value = new MotionValue(0, time.clock)
+		const first = value.animate(100, { type: 'spring' })
+		time.advance(16)
+		time.advance(16)
+		expect(value.getVelocity()).toBeGreaterThan(0)
+		const second = value.animate(0, { type: 'spring' })
+		expect(await first.finished).toBe('replaced')
+		value.jump(25)
+		expect(value.get()).toBe(25)
+		expect(value.getVelocity()).toBe(0)
+		expect(await second.finished).toBe('cancelled')
+		expect(time.count()).toBe(0)
+	})
+
+	it('cleans every channel on controller disposal', async () => {
+		const time = fakeClock()
+		const controller = new Controller(time.clock)
+		const result = controller.animate({ x: 40, opacity: 0 }, { duration: 1 }, false)
+		controller.destroy()
+		time.advance(1000)
+		expect(await result).toBe('replaced')
+		expect(time.count()).toBe(0)
+	})
+})

package/src/engine.ts

@@ -0,0 +1,159 @@
+import { keyframes, spring } from 'motion-dom'
+import type { Clock } from './clock-types'
+import type { Transition } from './types'
+
+/** Terminal status; cancellation never masquerades as completion. */
+export type AnimationResult = 'finished' | 'cancelled' | 'replaced'
+/** A cancellable animation whose finished promise always settles. */
+export interface AnimationControls {
+	finished: Promise<AnimationResult>
+	stop(reason?: Exclude<AnimationResult, 'finished'>): void
+}
+
+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')
+    }
+
+    const allowed = [
+		'type',
+		'duration',
+		'delay',
+		'ease',
+		'stiffness',
+		'damping',
+		'mass',
+		'velocity',
+		'restSpeed',
+		'restDelta',
+	]
+
+	for (const key of Object.keys(t)) {
+		if (!allowed.includes(key)) {
+			throw new Error(`motion: unsupported transition ${key}`)
+		}
+	}
+
+	if (t.type !== undefined && t.type !== 'tween' && t.type !== 'spring') {
+		throw new Error('motion: unsupported transition type')
+	}
+
+	for (const key of [
+		'duration',
+		'delay',
+		'stiffness',
+		'damping',
+		'mass',
+		'velocity',
+		'restSpeed',
+		'restDelta',
+	] as const) {
+		const value = t[key]
+		if (value !== undefined && (!Number.isFinite(value) || (key !== 'velocity' && value < 0))) {
+			throw new Error(`motion: invalid ${key}`)
+		}
+	}
+
+	for (const key of ['mass', 'stiffness', 'damping', 'restSpeed', 'restDelta'] as const) {
+		if (t[key] === 0) {
+			throw new Error(`motion: ${key} must be positive`)
+		}
+	}
+
+	if (t.ease !== undefined) {
+		if (Array.isArray(t.ease)) {
+			if (
+				t.ease.length !== 4 ||
+				!t.ease.every(Number.isFinite) ||
+				t.ease[0] < 0 ||
+				t.ease[0] > 1 ||
+				t.ease[2] < 0 ||
+				t.ease[2] > 1
+			) {
+				throw new Error('motion: invalid cubic Bezier')
+			}
+		} else if (!['linear', 'easeIn', 'easeOut', 'easeInOut'].includes(t.ease)) {
+			throw new Error('motion: unsupported easing')
+		}
+	}
+}
+
+// Pure upstream generators share trajectories across platforms; host scheduling
+// stays outside Motion's browser-global frame loop.
+export function runAnimation(
+	clock: Clock,
+	from: number,
+	to: number,
+	transition: Transition,
+	update: (value: number) => void,
+	complete?: () => void,
+): AnimationControls {
+	validateTransition(transition)
+	let frame = 0
+	let settled = false
+	let resolve!: (result: AnimationResult) => void
+	const finished = new Promise<AnimationResult>((done) => {
+		resolve = done
+	})
+
+	const settle = (result: AnimationResult) => {
+		if (settled) {
+			return
+		}
+
+		settled = true
+		clock.cancel(frame)
+		resolve(result)
+		if (result === 'finished') {
+			complete?.()
+		}
+	}
+
+	const duration = transition.duration ?? 0.3
+	const generator =
+		transition.type === 'spring'
+			? spring({
+					keyframes: [from, to],
+					stiffness: transition.stiffness ?? 100,
+					damping: transition.damping ?? 10,
+					mass: transition.mass ?? 1,
+					velocity: transition.velocity ?? 0,
+					restSpeed: transition.restSpeed,
+					restDelta: transition.restDelta,
+				})
+			: keyframes({
+					keyframes: [from, to],
+					duration: duration * 1000,
+					ease: transition.ease ?? 'easeInOut',
+				})
+
+	const start = 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')
+				return
+			}
+		}
+
+		if (!settled) {
+			frame = clock.request(tick)
+		}
+	}
+
+	if (transition.type !== 'spring' && duration === 0 && !transition.delay) {
+		update(to)
+		settle('finished')
+	} else {
+		frame = clock.request(tick)
+	}
+
+	return { finished, stop: (reason = 'cancelled') => settle(reason) }
+}

package/src/hooks.tsrx

@@ -0,0 +1,56 @@
+import { useRef, useLayoutEffect } from 'octane'
+import { interpolate } from 'motion-dom'
+import { clock } from './clock'
+import { MotionValue, type MotionValueEvents } from './value'
+import type { Transition } from './types'
+
+/** Create an owned numeric value that writes to bound hosts without rendering. */
+export function useMotionValue(initial: number): MotionValue {
+	const ref = useRef<MotionValue | null>(null)
+	if (!ref.current) ref.current = new MotionValue(initial, clock)
+	const value = ref.current
+	useLayoutEffect(() => () => value.destroy(), [])
+	return value
+}
+
+/** Subscribe to a value event; subscriptions follow value/callback replacement. */
+export function useMotionValueEvent<K extends keyof MotionValueEvents>(value: MotionValue, event: K, callback: MotionValueEvents[K]): void {
+	useLayoutEffect(() => value.on(event, callback), [value, event, callback])
+}
+
+/** Derive a numeric value using a range map, unary transform, or multi-input transform. */
+export function useTransform(source: MotionValue, input: number[], output: number[], options?: { clamp?: boolean }): MotionValue
+export function useTransform(source: MotionValue, transform: (value: number) => number): MotionValue
+export function useTransform(source: MotionValue[], transform: (values: number[]) => number): MotionValue
+export function useTransform(source: MotionValue | MotionValue[], input: number[] | ((value: any) => number), output?: number[], options?: { clamp?: boolean }): MotionValue {
+	const sources = Array.isArray(source) ? source : [source]
+	if (Array.isArray(input) && (!output || input.length !== output.length || input.length < 2)) throw new Error('motion: transform ranges must have matching lengths >= 2')
+	const transform: (value: any) => number = typeof input === 'function' ? input : interpolate(input, output!, options)
+	const read = () => transform(Array.isArray(source) ? sources.map((value) => value.get()) : source.get())
+	const value = useMotionValue(read())
+	// A source array may be freshly allocated; compare its members, not its identity.
+	const previous = useRef<MotionValue[]>(sources)
+	if (previous.current.length !== sources.length || previous.current.some((value, i) => value !== sources[i])) previous.current = sources
+	useLayoutEffect(() => {
+		const update = () => value.set(read())
+		const off = sources.map((source) => source.on('change', update))
+		update()
+		return () => off.forEach((unsubscribe) => unsubscribe())
+	}, [previous.current, input, output, options?.clamp])
+
+	return value
+}
+
+/** A spring value: set animates; jump snaps. A source value is followed directly. */
+export function useSpring(source: number | MotionValue, options: Omit<Transition, 'type' | 'duration' | 'ease' | 'delay'> = {}): MotionValue {
+	const value = useMotionValue(source instanceof MotionValue ? source.get() : source)
+	useLayoutEffect(() => {
+		const follow = (target: number) => { value.animate(target, { ...options, type: 'spring' }) }
+		const detach = value.attach(follow)
+		const unsubscribe = source instanceof MotionValue ? source.on('change', follow) : undefined
+		if (source instanceof MotionValue && source.get() !== value.get()) follow(source.get())
+		return () => { unsubscribe?.(); detach() }
+	}, [source instanceof MotionValue ? source : null, JSON.stringify(options)])
+
+	return value
+}

package/src/host-types.ts

@@ -0,0 +1,6 @@
+import type { Target } from './types'
+export interface HostAdapter {
+	read(): Target
+	write(values: Target): void
+	restore(): void
+}

package/src/host.ts

@@ -0,0 +1,50 @@
+import type { HostAdapter } from './host-types'
+// The retained NativeScript View exposes direct transform channels in DIP.
+export function attachHost(node: any): HostAdapter {
+	const original = {
+		opacity: node.opacity ?? 1,
+		x: node.translateX ?? 0,
+		y: node.translateY ?? 0,
+		scaleX: node.scaleX ?? 1,
+		scaleY: node.scaleY ?? 1,
+		rotate: node.rotate ?? 0,
+	}
+
+	if (
+		original.x ||
+		original.y ||
+		original.rotate ||
+		original.scaleX !== 1 ||
+		original.scaleY !== 1
+	) {
+		throw new Error('motion: put existing transforms on an outer container')
+	}
+
+	const write = (values: any) => {
+		if (values.opacity !== undefined) {
+			node.opacity = Math.min(1, Math.max(0, values.opacity))
+		}
+
+		if (values.x !== undefined) {
+			node.translateX = values.x
+		}
+
+		if (values.y !== undefined) {
+			node.translateY = values.y
+		}
+
+		if (values.rotate !== undefined) {
+			node.rotate = values.rotate
+		}
+
+		if (values.scale !== undefined || values.scaleX !== undefined) {
+			node.scaleX = (values.scale ?? 1) * (values.scaleX ?? 1)
+		}
+
+		if (values.scale !== undefined || values.scaleY !== undefined) {
+			node.scaleY = (values.scale ?? 1) * (values.scaleY ?? 1)
+		}
+	}
+
+	return { read: () => ({ ...original, scale: 1 }), write, restore: () => write(original) }
+}

package/src/host.web.ts

@@ -0,0 +1,34 @@
+import type { HostAdapter } from './host-types'
+export function attachHost(node: HTMLElement): HostAdapter {
+	const transform = node.style.transform
+	const opacity = node.style.opacity
+	const computed = getComputedStyle(node)
+	if (computed.transform && computed.transform !== 'none') {
+		throw new Error('motion: put existing CSS transforms on an outer container')
+	}
+
+	return {
+		read: () => ({
+			opacity: Number(computed.opacity || 1),
+			x: 0,
+			y: 0,
+			scale: 1,
+			scaleX: 1,
+			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)`
+			}
+		},
+		restore() {
+			node.style.transform = transform
+			node.style.opacity = opacity
+		},
+	}
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { MotionView, MotionRow, MotionPressable } from './components.tsrx'
+/** Bounded motion hosts for shared xplat UI primitives. */
+export const motion = { View: MotionView, Row: MotionRow, Pressable: MotionPressable }
+export { MotionConfig, useReducedMotion } from './config.tsrx'
+export { useMotionValue, useTransform, useSpring, useMotionValueEvent } from './hooks.tsrx'
+export type { MotionValue, MotionValueEvents } from './value'
+export type { AnimationControls, AnimationResult } from './engine'
+export type * from './types'
+export { Presence } from './presence.tsrx'

package/src/index.web.ts

@@ -0,0 +1,9 @@
+import { MotionView, MotionRow, MotionPressable } from './components.tsrx'
+/** Bounded motion hosts for shared xplat UI primitives. */
+export const motion = { View: MotionView, Row: MotionRow, Pressable: MotionPressable }
+export { MotionConfig, useReducedMotion } from './config.tsrx'
+export { useMotionValue, useTransform, useSpring, useMotionValueEvent } from './hooks.tsrx'
+export type { MotionValue, MotionValueEvents } from './value'
+export type { AnimationControls, AnimationResult } from './engine'
+export type * from './types'
+export { Presence } from './presence.tsrx'

package/src/presence-input.ts

@@ -0,0 +1,26 @@
+export function blockInput(node: any): () => void {
+	const enabled = node.isUserInteractionEnabled
+	const iosHidden = node.ios?.accessibilityElementsHidden
+	const androidImportance = node.android?.getImportantForAccessibility?.()
+	node.ios?.endEditing?.(true)
+	const focused = node.android?.findFocus?.()
+	if (focused) {
+		const platform = globalThis as any
+		const context = focused.getContext()
+		context
+			.getSystemService(platform.android.content.Context.INPUT_METHOD_SERVICE)
+			?.hideSoftInputFromWindow(focused.getWindowToken(), 0)
+
+		focused.clearFocus()
+	}
+
+	node.isUserInteractionEnabled = false
+	if (node.ios) {node.ios.accessibilityElementsHidden = true}
+	node.android?.setImportantForAccessibility?.(4) // IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS
+	return () => {
+		node.isUserInteractionEnabled = enabled
+		if (node.ios) {node.ios.accessibilityElementsHidden = iosHidden}
+		if (androidImportance !== undefined)
+			{node.android?.setImportantForAccessibility?.(androidImportance)}
+	}
+}

package/src/presence-input.web.ts

@@ -0,0 +1,17 @@
+export function blockInput(node: HTMLElement): () => void {
+	const inert = node.hasAttribute('inert')
+	const hidden = node.getAttribute('aria-hidden')
+	const pointerEvents = node.style.pointerEvents
+	const focused = node.ownerDocument.activeElement as HTMLElement | null
+	if (focused && node.contains(focused)) {focused.blur()}
+	node.setAttribute('inert', '')
+	node.setAttribute('aria-hidden', 'true')
+	node.style.pointerEvents = 'none'
+	return () => {
+		if (!inert) {node.removeAttribute('inert')}
+		if (hidden === null) {node.removeAttribute('aria-hidden')}
+		else {node.setAttribute('aria-hidden', hidden)}
+
+		node.style.pointerEvents = pointerEvents
+	}
+}

package/src/presence-state.test.ts

@@ -0,0 +1,64 @@
+import { expect, it, vi } from 'vitest'
+import { PresenceState } from './presence-state'
+import type { AnimationResult } from './engine'
+const deferred = () => {
+	let resolve!: (result: AnimationResult) => void
+	const promise = new Promise<AnimationResult>((done) => {
+		resolve = done
+	})
+
+	return { promise, resolve }
+}
+
+const drain = async () => {
+	await Promise.resolve()
+	await Promise.resolve()
+}
+
+it('waits for every registered child and ignores replaced exit completions', async () => {
+	const done = vi.fn(),
+		state = new PresenceState(true, done)
+
+	const a = deferred(),
+		b = deferred(),
+		replacement = deferred()
+
+	const memberA = { exit: vi.fn(() => a.promise), enter: vi.fn() }
+	state.register(memberA)
+	state.register({ exit: () => b.promise, enter() {} })
+	state.setPresent(false)
+	memberA.exit.mockReturnValue(replacement.promise)
+	state.restart(memberA)
+	a.resolve('finished')
+	b.resolve('finished')
+	await drain()
+	expect(done).not.toHaveBeenCalled()
+	replacement.resolve('finished')
+	await drain()
+	expect(done).toHaveBeenCalledTimes(1)
+})
+
+it('unregisters removed children and completes an empty boundary once', async () => {
+	const done = vi.fn(),
+		state = new PresenceState(true, done)
+
+	const pending = deferred()
+	const off = state.register({ exit: () => pending.promise, enter() {} })
+	state.setPresent(false)
+	off()
+	await drain()
+	expect(done).toHaveBeenCalledTimes(1)
+	pending.resolve('finished')
+	await drain()
+	expect(done).toHaveBeenCalledTimes(1)
+})
+
+it('a destroyed boundary never invokes completion', async () => {
+	const done = vi.fn(),
+		state = new PresenceState(true, done)
+
+	state.setPresent(false)
+	state.destroy()
+	await drain()
+	expect(done).not.toHaveBeenCalled()
+})

package/src/presence-state.ts

@@ -0,0 +1,76 @@
+import type { AnimationResult } from './engine'
+
+export interface PresenceMember {
+	exit(): Promise<AnimationResult>
+	enter(): void
+}
+
+// Membership is explicit: replacing an exit invalidates its completion token.
+// Microtask completion lets every child register before an empty/instant exit ends.
+export class PresenceState {
+	private members = new Set<PresenceMember>()
+	private pending = new Map<PresenceMember, number>()
+	private sequence = 0
+	private generation = 0
+	private disposed = false
+	private removed = false
+	constructor(
+		public present: boolean,
+		private complete: () => void,
+	) {}
+	register(member: PresenceMember): () => void {
+		this.members.add(member)
+		if (!this.present) {this.restart(member)}
+		return () => {
+			this.members.delete(member)
+			this.pending.delete(member)
+			this.check()
+		}
+	}
+	setPresent(present: boolean) {
+		if (this.disposed || present === this.present) {return}
+		this.present = present
+		++this.generation
+		this.removed = false
+		this.pending.clear()
+		if (present) {
+			for (const member of this.members) {member.enter()}
+		} else {
+			for (const member of this.members) {this.restart(member)}
+			this.check()
+		}
+	}
+	restart(member: PresenceMember) {
+		if (this.disposed || this.present || !this.members.has(member)) {return}
+		const token = ++this.sequence
+		this.pending.set(member, token)
+		void member.exit().then((result) => {
+			if (this.disposed || this.present || this.pending.get(member) !== token) {return}
+			// Replacement is owned by the next restart. Cancellation cannot remove a live subtree.
+			if (result !== 'finished') {return}
+			this.pending.delete(member)
+			this.check()
+		})
+	}
+	private check() {
+		const generation = this.generation
+		queueMicrotask(() => {
+			if (
+				!this.disposed &&
+				!this.present &&
+				!this.removed &&
+				!this.pending.size &&
+				generation === this.generation
+			) {
+				this.removed = true
+				this.complete()
+			}
+		})
+	}
+	destroy() {
+		this.disposed = true
+		++this.generation
+		this.members.clear()
+		this.pending.clear()
+	}
+}

package/src/presence.tsrx

@@ -0,0 +1,52 @@
+import { createContext, useRef, useLayoutEffect, useState } from 'octane'
+import { View } from '@octane-xplat/ui'
+import type { PresenceProps } from './types'
+import { PresenceState } from './presence-state'
+import { blockInput } from './presence-input'
+
+export const PresenceContext = createContext<PresenceState | null>(null)
+
+/** Retain live children until their exits finish. Keep this boundary mounted. */
+export function Presence(props: PresenceProps) @{
+	const [retained, setRetained] = useState(props.present)
+	const latest = useRef(props)
+	latest.current = props
+	const ref = useRef<PresenceState | null>(null)
+	if (!ref.current) ref.current = new PresenceState(props.present, () => {
+		setRetained(false)
+		latest.current.onExitComplete?.()
+	})
+
+	const state = ref.current
+	const host = useRef<any>(null)
+	const restoreInput = useRef<(() => void) | null>(null)
+	const syncInput = () => {
+		if (!props.present && host.current && !restoreInput.current) restoreInput.current = blockInput(host.current)
+		if (props.present && restoreInput.current) { restoreInput.current(); restoreInput.current = null }
+	}
+
+	useLayoutEffect(() => {
+		if (props.present) setRetained(true)
+		syncInput()
+		state.setPresent(props.present)
+	}, [props.present])
+
+	useLayoutEffect(() => () => {
+		state.destroy()
+		restoreInput.current?.()
+		restoreInput.current = null
+		host.current = null
+	}, [])
+
+	const { present, onExitComplete, children, bind, ...viewProps } = props
+
+	@if (props.present || retained) {
+		<View {...viewProps} bind={(node: any) => {
+			if (host.current !== node) { restoreInput.current?.(); restoreInput.current = null; host.current = node }
+			syncInput()
+			bind?.(node)
+		}}>
+			<PresenceContext value={state}>{children}</PresenceContext>
+		</View>
+	}
+}