@octane-xplat/motion 0.7.3 → 0.10.0

package/src/drag.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, it, vi } from 'vitest'
+import { attachDrag, validateDrag } from './drag'
+import { Controller } from './controller'
+import type { Clock } from './clock-types'
+import type { PanCallbacks, HostAdapter } from './host-types'
+import type { DragInfo, MotionProps } from './types'
+
+function fixture(props: MotionProps, reduced = false) {
+	let time = 0
+	let id = 0
+	const frames = new Map<number, () => void>()
+	const clock: Clock = {
+		now: () => time,
+		request: (fn) => {
+			frames.set(++id, fn)
+			return id
+		},
+		cancel: (key) => {
+			frames.delete(key)
+		},
+	}
+
+	const controller = new Controller(clock)
+	controller.seed({ x: 10, y: 20 })
+	let callbacks: PanCallbacks
+	const detach = vi.fn()
+	const delegate = vi.fn()
+	const writes: number[] = []
+	const adapter: HostAdapter = {
+		read: () => ({}),
+		write: (next) => {
+			writes.push(next.x ?? 0)
+		},
+		restore() {},
+		delegate,
+		pan(_axis, cb) {
+			callbacks = cb
+			return detach
+		},
+	}
+
+	controller.attach(adapter)
+	const off = attachDrag(
+		adapter,
+		controller,
+		props,
+		(axis) => controller.value(axis),
+		() => reduced,
+		() => props,
+	)
+
+	return {
+		controller,
+		off,
+		detach,
+		delegate,
+		writes,
+		emit(phase: keyof PanCallbacks, x: number, velocity = 0, cancelled = false) {
+			const info: DragInfo = {
+				point: { x, y: 0 },
+				offset: { x, y: x },
+				delta: { x, y: 0 },
+				velocity: { x: velocity, y: velocity },
+				cancelled,
+			}
+
+			callbacks[phase]({}, info)
+		},
+		advance(ms: number) {
+			time += ms
+			const pending = [...frames.values()]
+			frames.clear()
+			pending.forEach((fn) => fn())
+		},
+		count: () => frames.size,
+	}
+}
+
+describe('bounded drag', () => {
+	it('clamps live displacement, keeps the other axis, and emits callbacks once', () => {
+		const onDragStart = vi.fn(),
+			onDrag = vi.fn(),
+			onDragEnd = vi.fn()
+
+		const f = fixture({
+			drag: 'x',
+			dragConstraints: { left: -20, right: 30 },
+			dragElastic: 0,
+			dragMomentum: false,
+			onDragStart,
+			onDrag,
+			onDragEnd,
+		})
+
+		f.emit('start', 0)
+		f.emit('move', 100)
+		expect(f.controller.snapshot()).toEqual({ x: 30, y: 20 })
+		f.emit('end', 100, 500)
+		f.emit('end', 100)
+		expect(onDragStart).toHaveBeenCalledTimes(1)
+		expect(onDrag).toHaveBeenCalledTimes(1)
+		expect(onDragEnd).toHaveBeenCalledTimes(1)
+		expect(f.count()).toBe(0)
+		f.off()
+		expect(f.detach).toHaveBeenCalledOnce()
+	})
+
+	it('uses default elasticity and springs back inside constraints without momentum', () => {
+		const f = fixture({ drag: 'x', dragConstraints: { right: 30 }, dragMomentum: false })
+		f.emit('start', 0)
+		f.emit('move', 100)
+		expect(f.controller.value('x').get()).toBe(58)
+		f.emit('end', 100)
+		for (let i = 0; i < 200; i++) {
+			f.advance(16)
+		}
+
+		expect(f.controller.value('x').get()).toBe(30)
+		expect(f.delegate).not.toHaveBeenCalled()
+		f.off()
+	})
+
+	it('hands release velocity to a JS spring and bounds every hard-constraint sample', () => {
+		const f = fixture({ drag: 'x', dragConstraints: { left: -20, right: 50 }, dragElastic: false })
+		f.emit('start', 0)
+		f.emit('move', 10)
+		f.emit('end', 10, 500)
+		f.advance(16)
+		expect(f.controller.value('x').get()).toBeGreaterThan(20)
+		for (let i = 0; i < 200; i++) {
+			f.advance(16)
+		}
+
+		expect(f.controller.value('x').get()).toBe(50)
+		expect(Math.max(...f.writes)).toBeLessThanOrEqual(50)
+		expect(f.delegate).not.toHaveBeenCalled()
+		f.off()
+	})
+
+	it('cancellation drops momentum; reduced motion snaps; teardown cancels settlement', () => {
+		const cancel = fixture({ drag: true })
+		cancel.emit('start', 0)
+		cancel.emit('move', 20)
+		cancel.emit('end', 20, 500, true)
+		expect(cancel.count()).toBe(0)
+		cancel.off()
+		const reduced = fixture({ drag: 'x' }, true)
+		reduced.emit('start', 0)
+		reduced.emit('end', 10, 500)
+		expect(reduced.controller.value('x').get()).toBe(120)
+		expect(reduced.count()).toBe(0)
+		reduced.off()
+		const f = fixture({ drag: 'x' })
+		f.emit('start', 0)
+		f.emit('end', 10, 500)
+		expect(f.count()).toBe(1)
+		f.off()
+		expect(f.count()).toBe(0)
+	})
+
+	it('rejects refs, invalid bounds, elasticity and competing axis targets', () => {
+		expect(() => validateDrag({ dragConstraints: { current: null } } as any)).toThrow('refs')
+		expect(() => validateDrag({ dragConstraints: { left: 20, right: 10 } })).toThrow('reversed')
+		expect(() => validateDrag({ dragElastic: 2 })).toThrow('dragElastic')
+		expect(() => validateDrag({ drag: 'x', animate: { x: 20 } })).toThrow('both own x')
+	})
+})

package/src/drag.ts

@@ -0,0 +1,157 @@
+import type { Controller } from './controller'
+import type { HostAdapter } from './host-types'
+import type { DragInfo, MotionProps } from './types'
+import type { MotionValue } from './value'
+
+export function validateDrag(props: MotionProps) {
+	if (props.drag !== undefined && ![true, false, 'x', 'y'].includes(props.drag)) {
+		throw new Error('motion: drag must be boolean, x, or y')
+	}
+
+	const bounds = props.dragConstraints ?? {}
+	for (const [key, value] of Object.entries(bounds)) {
+		if (!['left', 'right', 'top', 'bottom'].includes(key) || !Number.isFinite(value)) {
+			throw new Error('motion: dragConstraints requires finite numeric edges; refs are deferred')
+		}
+	}
+
+	if (
+		(bounds.left ?? -Infinity) > (bounds.right ?? Infinity) ||
+		(bounds.top ?? -Infinity) > (bounds.bottom ?? Infinity)
+	) {
+		throw new Error('motion: dragConstraints edges are reversed')
+	}
+
+	if (
+		typeof props.dragElastic !== 'boolean' &&
+		props.dragElastic !== undefined &&
+		(!Number.isFinite(props.dragElastic) || props.dragElastic < 0 || props.dragElastic > 1)
+	) {
+		throw new Error('motion: dragElastic must be boolean or a number from 0 to 1')
+	}
+
+	if (props.drag) {
+		for (const axis of ['x', 'y'] as const) {
+			if (props.drag !== true && props.drag !== axis) {
+				continue
+			}
+
+			for (const target of [props.animate, props.whileTap, props.whileFocus]) {
+				if (
+					target &&
+					typeof target === 'object' &&
+					!Array.isArray(target) &&
+					target[axis] !== undefined
+				) {
+					throw new Error(`motion: drag and animation both own ${axis}`)
+				}
+			}
+		}
+	}
+}
+
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value))
+
+/** Gesture writes and release springs bypass host delegation. */
+export function attachDrag(
+	adapter: HostAdapter,
+	controller: Controller,
+	props: MotionProps,
+	valueFor: (axis: 'x' | 'y') => MotionValue,
+	reduced: () => boolean,
+	callbacks: () => MotionProps,
+) {
+	if (!props.drag) {
+		return () => {}
+	}
+
+	if (!adapter.pan) {
+		throw new Error('motion: this host does not support drag')
+	}
+
+	const axes = (['x', 'y'] as const).filter((axis) => props.drag === true || props.drag === axis)
+	const values = new Map(axes.map((axis) => [axis, valueFor(axis)]))
+	const value = (axis: 'x' | 'y') => values.get(axis)!
+	const bounds = props.dragConstraints ?? {}
+	const elastic =
+		typeof props.dragElastic === 'number'
+			? props.dragElastic
+			: props.dragElastic === false
+				? 0
+				: 0.35
+
+	const origin = { x: 0, y: 0 }
+	let active = false
+	const limits = (axis: 'x' | 'y') =>
+		axis === 'x'
+			? [bounds.left ?? -Infinity, bounds.right ?? Infinity]
+			: [bounds.top ?? -Infinity, bounds.bottom ?? Infinity]
+
+	const move = (info: DragInfo) => {
+		for (const axis of axes) {
+			const [min, max] = limits(axis)
+			const next = origin[axis] + info.offset[axis]
+			const bounded = clamp(next, min, max)
+			value(axis).jump(bounded + (next - bounded) * elastic)
+		}
+	}
+
+	const off = adapter.pan(props.drag, {
+		start(event, info) {
+			controller.stop()
+			active = true
+			for (const axis of axes) {
+				const channel = value(axis)
+				channel.stop()
+				origin[axis] = channel.get()
+			}
+
+			callbacks().onDragStart?.(event, info)
+		},
+		move(event, info) {
+			if (!active) {
+				return
+			}
+
+			move(info)
+			callbacks().onDrag?.(event, info)
+		},
+		end(event, info) {
+			if (!active) {
+				return
+			}
+
+			active = false
+			move(info)
+			for (const axis of axes) {
+				const channel = value(axis)
+				const velocity = info.cancelled || props.dragMomentum === false ? 0 : info.velocity[axis]
+				const [min, max] = limits(axis)
+				const target = clamp(channel.get() + velocity * 0.2, min, max)
+				if (elastic === 0) {
+					channel.jump(clamp(channel.get(), min, max))
+				}
+
+				if (reduced()) {
+					channel.jump(target)
+				} else if (target !== channel.get() || velocity !== 0) {
+					channel.animate(
+						target,
+						{ type: 'spring', stiffness: 200, damping: 30, velocity },
+						elastic === 0 ? (next) => clamp(next, min, max) : undefined,
+					)
+				}
+			}
+
+			callbacks().onDragEnd?.(event, info)
+		},
+	})
+
+	return () => {
+		active = false
+		off()
+		for (const channel of values.values()) {
+			channel.stop()
+		}
+	}
+}

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)
+}