@octane-xplat/motion 0.9.0 → 0.10.0

package/src/pan.web.ts

@@ -0,0 +1,116 @@
+import type { PanCallbacks } from './host-types'
+import type { DragInfo } from './types'
+
+export function attachPan(node: HTMLElement, axis: true | 'x' | 'y', callbacks: PanCallbacks) {
+	const touchAction = node.style.touchAction
+	node.style.touchAction = axis === 'x' ? 'pan-y' : axis === 'y' ? 'pan-x' : 'none'
+	let pointer: number | undefined
+	let active = false
+	let start = { x: 0, y: 0 }
+	let last = start
+	let time = 0
+	let velocity = { x: 0, y: 0 }
+	let velocityTime = 0
+	const sample = (event: PointerEvent, cancelled = false): DragInfo => {
+		const point = cancelled ? last : { x: event.clientX, y: event.clientY }
+		const delta = { x: point.x - last.x, y: point.y - last.y }
+		const elapsed = event.timeStamp - time
+		if (elapsed > 0 && (delta.x || delta.y)) {
+			velocity = { x: (delta.x * 1000) / elapsed, y: (delta.y * 1000) / elapsed }
+			velocityTime = event.timeStamp
+		} else if (event.timeStamp - velocityTime > 100) {
+			velocity = { x: 0, y: 0 }
+		}
+
+		last = point
+		time = event.timeStamp
+		return {
+			point,
+			delta,
+			offset: { x: point.x - start.x, y: point.y - start.y },
+			velocity,
+			cancelled,
+		}
+	}
+
+	const down = (event: PointerEvent) => {
+		if (pointer !== undefined || event.button !== 0 || event.isPrimary === false) {
+			return
+		}
+
+		pointer = event.pointerId
+		start = last = { x: event.clientX, y: event.clientY }
+		time = velocityTime = event.timeStamp
+		velocity = { x: 0, y: 0 }
+		try {
+			node.setPointerCapture?.(event.pointerId)
+		} catch (error) {
+			// Synthetic pointer dispatch has no active browser pointer.
+			if (event.isTrusted || (error as Error).name !== 'NotFoundError') {
+				throw error
+			}
+		}
+	}
+
+	const move = (event: PointerEvent) => {
+		if (event.pointerId !== pointer) {
+			return
+		}
+
+		const info = sample(event)
+		if (!active) {
+			const primary = axis === 'y' ? info.offset.y : info.offset.x
+			const other = axis === 'y' ? info.offset.x : info.offset.y
+			if (axis !== true && Math.abs(other) > 8 && Math.abs(primary) <= 8) {
+				finish(event, true)
+				return
+			}
+
+			if ((axis === true ? Math.hypot(info.offset.x, info.offset.y) : Math.abs(primary)) <= 8) {
+				return
+			}
+
+			active = true
+			callbacks.start(event, info)
+		}
+
+		callbacks.move(event, info)
+	}
+
+	const finish = (event: PointerEvent, cancelled: boolean) => {
+		if (pointer === undefined || event.pointerId !== pointer) {
+			return
+		}
+
+		const id = pointer
+		pointer = undefined
+		if (active) {
+			active = false
+			callbacks.end(event, sample(event, cancelled))
+		}
+
+		if (node.hasPointerCapture?.(id)) {
+			node.releasePointerCapture(id)
+		}
+	}
+
+	const up = (event: PointerEvent) => finish(event, false)
+	const cancel = (event: PointerEvent) => finish(event, true)
+	node.addEventListener('pointerdown', down)
+	node.addEventListener('pointermove', move)
+	node.addEventListener('pointerup', up)
+	node.addEventListener('pointercancel', cancel)
+	node.addEventListener('lostpointercapture', cancel)
+	return () => {
+		node.removeEventListener('pointerdown', down)
+		node.removeEventListener('pointermove', move)
+		node.removeEventListener('pointerup', up)
+		node.removeEventListener('pointercancel', cancel)
+		node.removeEventListener('lostpointercapture', cancel)
+		if (pointer !== undefined && node.hasPointerCapture?.(pointer)) {
+			node.releasePointerCapture(pointer)
+		}
+
+		node.style.touchAction = touchAction
+	}
+}

package/src/presence.tsrx

@@ -11,13 +11,13 @@ 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, () => {
+	const stateRef = useRef<PresenceState | null>(null)
+	if (!stateRef.current) stateRef.current = new PresenceState(props.present, () => {
 		setRetained(false)
 		latest.current.onExitComplete?.()
 	})
 
-	const state = ref.current
+	const state = stateRef.current
 	const host = useRef<any>(null)
 	const restoreInput = useRef<(() => void) | null>(null)
 	const syncInput = () => {
@@ -38,14 +38,13 @@ export function Presence(props: PresenceProps) @{
 		host.current = null
 	}, [])
 
-	const { present, onExitComplete, children, bind, ...viewProps } = props
+	const { present, onExitComplete, children, ref, ...viewProps } = props
 
 	@if (props.present || retained) {
-		<View {...viewProps} bind={(node: any) => {
+		<View {...viewProps} ref={[(node: any) => {
 			if (host.current !== node) { restoreInput.current?.(); restoreInput.current = null; host.current = node }
 			syncInput()
-			bind?.(node)
-		}}>
+		}, ref]}>
 			<PresenceContext value={state}>{children}</PresenceContext>
 		</View>
 	}

package/src/reduced-motion.ts

@@ -1,4 +1,4 @@
-import { Application, Utils } from '@nativescript/core'
+import { Application, Device, Utils } from '@nativescript/core'
 
 export function readReducedMotion(): boolean {
 	const platform = globalThis as any
@@ -6,7 +6,19 @@ export function readReducedMotion(): boolean {
 		return Boolean(platform.UIAccessibilityIsReduceMotionEnabled?.())
 	}
 
-	const context = Utils.android.getApplicationContext()
+	if (!platform.android) {
+		return false
+	}
+
+	if (
+		Number(Device.sdkVersion) >= 26 &&
+		platform.android.animation?.ValueAnimator?.areAnimatorsEnabled?.() === false
+	) {
+		return true
+	}
+
+	// `Utils.android` is a {} stub in the pinned Windows core build.
+	const context = (Utils.android as any).getApplicationContext()
 	return (
 		platform.android.provider.Settings.Global.getFloat(
 			context.getContentResolver(),
@@ -16,9 +28,16 @@ export function readReducedMotion(): boolean {
 	)
 }
 
-// Poll only while subscribed; this also detects Android developer-setting changes
-// without owning a Java ContentObserver class. Resume refreshes immediately.
+// iOS posts a notification on preference change; Android has no event, so it
+// polls only while subscribed (also catches developer-setting changes) and
+// refreshes on resume.
 export function observeReducedMotion(notify: () => void): () => void {
+	if (Application.ios) {
+		const name = (globalThis as any).UIAccessibilityReduceMotionStatusDidChangeNotification
+		const observer = Application.ios.addNotificationObserver(name, notify)
+		return () => Application.ios.removeNotificationObserver(observer, name)
+	}
+
 	let previous = readReducedMotion()
 	const check = () => {
 		const next = readReducedMotion()

package/src/types.ts

@@ -1,8 +1,8 @@
-import type { View, Row, Pressable } from '@octane-xplat/ui'
+import type { View, HStack, Pressable } from '@octane-xplat/ui'
 import type { MotionValue } from './value.js'
 
 type ViewProps = Parameters<typeof View>[0]
-type RowProps = Parameters<typeof Row>[0]
+type HStackProps = Parameters<typeof HStack>[0]
 type PressableProps = Parameters<typeof Pressable>[0]
 
 /** Supported channels. Translation is CSS pixels/DIP; rotation is degrees. */
@@ -10,13 +10,43 @@ export type MotionKey = 'opacity' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' |
 /** Absolute numeric destinations; omitted channels retain their current values. */
 export type Target = Partial<Record<MotionKey, number>>
 /** Tween easing, including a CSS-compatible cubic Bezier tuple. */
-export type Ease = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | [number, number, number, number]
+export type Ease =
+	| 'linear'
+	| 'easeIn'
+	| 'easeOut'
+	| 'easeInOut'
+	| 'circIn'
+	| 'circOut'
+	| 'circInOut'
+	| 'backIn'
+	| 'backOut'
+	| 'backInOut'
+	| 'anticipate'
+	| [number, number, number, number]
+
+/** How repeated legs play: restart, alternate direction, or alternate
+ *  direction with inverted easing (identical to reverse for two keyframes). */
+export type RepeatType = 'loop' | 'reverse' | 'mirror'
+/** Numeric tree timing in seconds, applied to inherited animate labels. */
+export interface ChildOrchestration {
+	staggerChildren?: number
+	delayChildren?: number
+	when?: 'beforeChildren' | 'afterChildren'
+}
+
 /** Timing is seconds. Spring velocity is units per second. */
-export interface Transition {
+export interface Transition extends ChildOrchestration {
 	type?: 'tween' | 'spring'
+	/** Tween duration; on springs this is the visual duration (combine with bounce). */
 	duration?: number
 	delay?: number
 	ease?: Ease
+	/** Additional iterations after the first leg; Infinity loops forever. */
+	repeat?: number
+	repeatType?: RepeatType
+	repeatDelay?: number
+	/** Spring bounciness 0–1; pairs with duration instead of stiffness/damping. */
+	bounce?: number
 	stiffness?: number
 	damping?: number
 	mass?: number
@@ -25,28 +55,87 @@ export interface Transition {
 	restDelta?: number
 }
 
+/** Per-channel transition overrides, upstream form: `{x: {…}, default: {…}}`. */
+export type TransitionOrchestration = ChildOrchestration & {
+	default?: Transition
+} & Partial<Record<MotionKey, Transition>>
+
+/** A flat transition or per-channel overrides. */
+export type TransitionInput = Transition | TransitionOrchestration
+
+/** Labels resolve against this host's variants, in array order. */
+export type VariantLabels = string | string[]
+/** An inline numeric target or labels resolved by the host. */
+export type AnimationDefinition = Target | VariantLabels
+/** A numeric variant destination with an optional run transition override. */
+export type VariantTarget = Target & { transition?: TransitionInput }
+/** Host-local definitions; pure resolvers receive this host's custom value. */
+export type Variants = Record<string, VariantTarget | ((custom: any) => VariantTarget)>
+
 /** Static platform styles plus numeric motion-value bindings. */
 export type MotionStyle = Record<string, unknown> & Partial<Record<MotionKey, number | MotionValue>>
+/** Translation limits in CSS pixels/DIP. Omitted edges are unbounded. */
+export interface DragConstraints {
+	left?: number
+	right?: number
+	top?: number
+	bottom?: number
+}
+
+export interface DragInfo {
+	point: { x: number; y: number }
+	delta: { x: number; y: number }
+	offset: { x: number; y: number }
+	/** CSS pixels/DIP per second. */
+	velocity: { x: number; y: number }
+	cancelled: boolean
+}
+
+export type DragCallback = (event: any, info: DragInfo) => void
+
 /** Supported declarative motion controls. */
 export interface MotionProps {
-	initial?: Target | false
+	drag?: boolean | 'x' | 'y'
+	/** Numeric translation bounds; measured ref constraints are deferred. */
+	dragConstraints?: DragConstraints
+	/** Project release velocity into a spring destination (default true). */
+	dragMomentum?: boolean
+	/** Resistance beyond bounds, 0–1 (default 0.35); false = 0, true = 0.35. */
+	dragElastic?: boolean | number
+	onDragStart?: DragCallback
+	onDrag?: DragCallback
+	onDragEnd?: DragCallback
+	/** Named numeric targets; array labels merge left to right. */
+	variants?: Variants
+	/** Passed to this host's variant resolvers; not inherited. */
+	custom?: any
+	initial?: AnimationDefinition | false
 	/** Destination while the nearest Presence boundary retains this host for exit. */
-	exit?: Target
-	animate?: Target
-	transition?: Transition
+	exit?: AnimationDefinition
+	animate?: AnimationDefinition
+	transition?: TransitionInput
 	style?: MotionStyle
+	/** Target while the pointer is down (web: pointerdown; native: touch down). */
+	whileTap?: AnimationDefinition
+	whileTapTransition?: Transition
+	/** Target while the host holds focus. */
+	whileFocus?: AnimationDefinition
+	whileFocusTransition?: Transition
+	onAnimationStart?: (definition: AnimationDefinition) => void
 	onAnimationComplete?: () => void
+	/** Per-frame snapshot while any channel animates. */
+	onUpdate?: (latest: Target) => void
 }
 
 /** View layout and accessibility props with motion controls. */
 export type MotionViewProps = Omit<ViewProps, 'style'> & MotionProps
 /** Row layout and accessibility props with motion controls. */
-export type MotionRowProps = Omit<RowProps, 'style'> & MotionProps
+export type MotionRowProps = Omit<HStackProps, 'style'> & MotionProps
 /** Pressable interaction props with motion controls. */
 export type MotionPressableProps = Omit<PressableProps, 'style'> & MotionProps
 /** Inherited defaults; `user` observes the live system preference. */
 export interface MotionConfigProps {
-	transition?: Transition
+	transition?: TransitionInput
 	reducedMotion?: 'always' | 'never' | 'user'
 	children?: any
 }

package/src/value.ts

@@ -88,6 +88,15 @@ export class MotionValue {
 		}
 	}
 	private write(value: number) {
+		this.track(value)
+		if (!this.disposed && value !== this.previous) {
+			this.emit('change', value)
+		}
+	}
+	/** Update position bookkeeping without emitting — platform-delegated runs
+	 *  track presentation state so interruption reads fresh value/velocity. */
+	track(value: number) {
+		this.assert(value)
 		if (this.disposed) {
 			return
 		}
@@ -101,12 +110,13 @@ export class MotionValue {
 		this.previous = this.current
 		this.current = value
 		this.updated = now
-		if (value !== this.previous) {
-			this.emit('change', value)
-		}
 	}
 	/** Animate to a destination. New playback replaces old playback. */
-	animate(target: number, transition: Transition = {}): AnimationControls {
+	animate(
+		target: number,
+		transition: Transition = {},
+		clampSample?: (value: number) => number,
+	): AnimationControls {
 		this.assert(target)
 		validateTransition(transition)
 		if (this.disposed) {
@@ -122,7 +132,7 @@ export class MotionValue {
 			this.current,
 			target,
 			{ ...transition, velocity },
-			(value) => this.write(value),
+			(value) => this.write(clampSample ? clampSample(value) : value),
 		)
 
 		this.controls = controls

package/src/variants.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it, vi } from 'vitest'
+import { resolveVariant, playbackTransition, VariantNode } from './variants'
+import type { AnimationResult } from './engine'
+import type { TransitionInput } from './types'
+
+function node(timing: TransitionInput = {}) {
+	const value = new VariantNode()
+	value.resolve = () => ({ target: { x: 10 }, transition: timing })
+	value.play = vi.fn(async () => 'finished' as AnimationResult)
+	value.stopOwn = vi.fn()
+	return value
+}
+
+function pending() {
+	let resolve!: (result: AnimationResult) => void
+	const promise = new Promise<AnimationResult>((done) => {
+		resolve = done
+	})
+
+	return { promise, resolve }
+}
+
+describe('variant resolution', () => {
+	it('merges arrays left to right and keeps the last defined transition', () => {
+		expect(
+			resolveVariant(['missing', 'a', 'b', 'c'], {
+				a: { x: 10, opacity: 0, transition: { duration: 1 } },
+				b: { x: 20, transition: { duration: 2 } },
+				c: { y: 30 },
+			}),
+		).toEqual({ target: { x: 20, opacity: 0, y: 30 }, transition: { duration: 2 } })
+	})
+
+	it('passes custom to resolvers and validates the returned numeric target', () => {
+		expect(resolveVariant('a', { a: (custom) => ({ x: custom }) }, 7).target).toEqual({ x: 7 })
+		expect(() => resolveVariant('a', { a: () => ({ x: '10px' as any }) })).toThrow('finite numeric')
+		expect(() => resolveVariant('a', { a: { transition: { staggerChildren: -1 } } })).toThrow(
+			'staggerChildren',
+		)
+
+		expect(resolveVariant('toString', {}).target).toEqual({})
+	})
+
+	it('strips parent timing and adds delay to each per-key override', () => {
+		expect(
+			playbackTransition(
+				{
+					default: { duration: 1, delay: 0.1 },
+					x: { delay: 0.2 },
+					delayChildren: 1,
+					staggerChildren: 2,
+					when: 'afterChildren',
+				},
+				0.3,
+			),
+		).toEqual({ default: { duration: 1, delay: 0.4 }, x: { delay: 0.5 } })
+	})
+})
+
+describe('variant orchestration', () => {
+	it('starts parent and children concurrently with stable stagger offsets', async () => {
+		const parent = node({ delayChildren: 0.1, staggerChildren: 0.2 })
+		const a = node(),
+			b = node()
+
+		parent.register(a)
+		parent.register(b)
+		const job = pending()
+		parent.play = vi.fn(() => job.promise)
+		const result = parent.run('show')
+		expect(a.play).toHaveBeenCalledWith('show', { x: 10 }, { delay: 0.1 })
+		expect(b.play).toHaveBeenCalledWith('show', { x: 10 }, { delay: 0.30000000000000004 })
+		job.resolve('finished')
+		expect(await result).toBe('finished')
+	})
+
+	it('waits for actual parent completion before children', async () => {
+		const parent = node({ when: 'beforeChildren' }),
+			child = node()
+
+		parent.register(child)
+		const job = pending()
+		parent.play = vi.fn(() => job.promise)
+		const result = parent.run('show')
+		expect(child.play).not.toHaveBeenCalled()
+		job.resolve('finished')
+		expect(await result).toBe('finished')
+		expect(child.play).toHaveBeenCalledOnce()
+	})
+
+	it('waits for children and cancels queued parent work on disposal', async () => {
+		const parent = node({ when: 'afterChildren' }),
+			child = node()
+
+		parent.register(child)
+		const job = pending()
+		child.play = vi.fn(() => job.promise)
+		const result = parent.run('show')
+		expect(parent.play).not.toHaveBeenCalled()
+		parent.stop()
+		job.resolve('finished')
+		expect(await result).toBe('cancelled')
+		expect(parent.play).not.toHaveBeenCalled()
+	})
+
+	it('unregisters children and propagates cancellation through nested runs', async () => {
+		const parent = node(),
+			child = node(),
+			grandchild = node()
+
+		child.register(grandchild)
+		const off = parent.register(child)
+		await parent.run('show')
+		expect(grandchild.play).toHaveBeenCalledOnce()
+		off()
+		await parent.run('hide')
+		expect(child.play).toHaveBeenCalledOnce()
+		expect(child.stopOwn).toHaveBeenCalled()
+	})
+})
+
+it('starts the parent only after every child finishes successfully', async () => {
+	const parent = node({ when: 'afterChildren' })
+	const a = node(),
+		b = node()
+
+	parent.register(a)
+	parent.register(b)
+	const first = pending(),
+		second = pending()
+
+	a.play = vi.fn(() => first.promise)
+	b.play = vi.fn(() => second.promise)
+	const result = parent.run('show')
+	first.resolve('finished')
+	await Promise.resolve()
+	expect(parent.play).not.toHaveBeenCalled()
+	second.resolve('finished')
+	expect(await result).toBe('finished')
+	expect(parent.play).toHaveBeenCalledOnce()
+})
+
+it('does not launch an obsolete child phase after replacement', async () => {
+	const parent = node({ when: 'beforeChildren' }),
+		child = node()
+
+	parent.register(child)
+	const old = pending()
+	parent.play = vi.fn(() => old.promise)
+	const obsolete = parent.run('show')
+	parent.play = vi.fn(async () => 'finished')
+	await parent.run('hide')
+	old.resolve('finished')
+	expect(await obsolete).toBe('cancelled')
+	expect(child.play).toHaveBeenCalledTimes(1)
+	expect(child.play).toHaveBeenCalledWith('hide', { x: 10 }, { delay: 0 })
+})
+
+it('animates late children after the current parent run finishes', async () => {
+	const parent = node({ when: 'beforeChildren', delayChildren: 0.1 }),
+		child = node()
+
+	await parent.run('show')
+	parent.register(child)
+	await Promise.resolve()
+	expect(child.play).toHaveBeenCalledWith('show', { x: 10 }, { delay: 0.1 })
+})
+
+it('keeps independently started exits alive while invalidating queued tree work', async () => {
+	const parent = node({ when: 'beforeChildren' }),
+		child = node()
+
+	parent.register(child)
+	const job = pending()
+	parent.play = vi.fn(() => job.promise)
+	const run = parent.run('show')
+	const stops = (child.stopOwn as ReturnType<typeof vi.fn>).mock.calls.length
+	parent.cancelPending()
+	job.resolve('finished')
+	expect(await run).toBe('cancelled')
+	expect(child.stopOwn).toHaveBeenCalledTimes(stops)
+	expect(child.play).not.toHaveBeenCalled()
+})
+
+it('does not count a late child twice while waiting for the parent phase', async () => {
+	const parent = node({ when: 'beforeChildren' }),
+		child = node()
+
+	const job = pending()
+	parent.play = vi.fn(() => job.promise)
+	const run = parent.run('show')
+	parent.register(child)
+	job.resolve('finished')
+	await run
+	await Promise.resolve()
+	expect(child.play).toHaveBeenCalledOnce()
+})