@octane-xplat/motion 0.7.3 → 0.10.0

package/src/types.ts

@@ -1,8 +1,8 @@
-import type { View, Row, Pressable } from '@octane-xplat/ui'
-import type { MotionValue } from './value'
+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

@@ -1,6 +1,6 @@
-import type { Clock } from './clock-types'
-import type { Transition } from './types'
-import { runAnimation, validateTransition, type AnimationControls } from './engine'
+import type { Clock } from './clock-types.js'
+import type { Transition } from './types.js'
+import { runAnimation, validateTransition, type AnimationControls } from './engine.js'
 
 /** Events supported by numeric motion values. */
 export interface MotionValueEvents {
@@ -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()
+})

package/src/variants.ts

@@ -0,0 +1,226 @@
+import { validateTarget } from './controller'
+import { isOrchestrated, validateTransitionInput } from './engine'
+import type { AnimationResult } from './engine'
+import type {
+	AnimationDefinition,
+	MotionKey,
+	Target,
+	TransitionInput,
+	Variants,
+	VariantLabels,
+} from './types'
+
+export function isLabels(value: unknown): value is VariantLabels {
+	return (
+		typeof value === 'string' ||
+		(Array.isArray(value) && value.every((label) => typeof label === 'string'))
+	)
+}
+
+export function resolveVariant(
+	definition: AnimationDefinition | false | undefined,
+	variants?: Variants,
+	custom?: any,
+) {
+	const target: Target = {}
+	let transition: TransitionInput | undefined
+	if (definition === undefined || definition === false) {
+		return { target, transition }
+	}
+
+	const entries = isLabels(definition)
+		? (typeof definition === 'string' ? [definition] : definition).map((label) =>
+				Object.hasOwn(variants ?? {}, label) ? variants![label] : undefined,
+			)
+		: [definition]
+
+	for (const entry of entries) {
+		const resolved = typeof entry === 'function' ? entry(custom) : entry
+		if (!resolved) {
+			continue
+		}
+
+		const { transition: override, ...values } = resolved as Target & {
+			transition?: TransitionInput
+		}
+
+		validateTarget(values)
+		Object.assign(target, values)
+		if (override !== undefined) {
+			validateTransitionInput(override)
+			transition = override
+		}
+	}
+
+	return { target, transition }
+}
+
+/** Keep tree timing out of Controller and add inherited delay to every channel. */
+export function playbackTransition(input: TransitionInput, delay = 0): TransitionInput {
+	if (isOrchestrated(input)) {
+		const {
+			staggerChildren: _staggerChildren,
+			delayChildren: _delayChildren,
+			when: _when,
+			...timing
+		} = input
+
+		const result: TransitionInput = {
+			default: { ...timing.default, delay: (timing.default?.delay ?? 0) + delay },
+		}
+
+		for (const [key, value] of Object.entries(timing)) {
+			if (key !== 'default' && value) {
+				result[key as MotionKey] = {
+					...value,
+					delay: (value.delay ?? timing.default?.delay ?? 0) + delay,
+				}
+			}
+		}
+
+		return result
+	}
+
+	const {
+		staggerChildren: _staggerChildren,
+		delayChildren: _delayChildren,
+		when: _when,
+		...timing
+	} = input
+
+	return { ...timing, delay: (timing.delay ?? 0) + delay }
+}
+
+/** Root-local tree of inherited runs. Generations prevent queued work after replacement/disposal. */
+export class VariantNode {
+	readonly children = new Set<VariantNode>()
+	private generation = 0
+	private active?: {
+		definition: AnimationDefinition
+		finished: Promise<AnimationResult>
+		generation: number
+	}
+	initial?: VariantLabels | false
+	animate?: VariantLabels
+	resolve!: (definition: AnimationDefinition) => { target: Target; transition: TransitionInput }
+	play!: (
+		definition: AnimationDefinition,
+		target: Target,
+		transition: TransitionInput,
+	) => Promise<AnimationResult>
+	stopOwn!: () => void
+
+	register(child: VariantNode) {
+		this.children.add(child)
+		const active = this.active
+		if (active && isLabels(active.definition)) {
+			void active.finished.then((result) => {
+				if (
+					result !== 'finished' ||
+					active.generation !== this.generation ||
+					!this.children.has(child)
+				) {
+					return
+				}
+
+				const { transition } = this.resolve(active.definition)
+				void child.run(
+					active.definition,
+					(transition.delayChildren ?? 0) +
+						[...this.children].indexOf(child) * (transition.staggerChildren ?? 0),
+				)
+			})
+		}
+
+		return () => {
+			this.children.delete(child)
+			child.stop()
+		}
+	}
+
+	/** Invalidate queued phases without stopping independently registered Presence exits. */
+	cancelPending() {
+		this.generation++
+		for (const child of this.children) {
+			child.cancelPending()
+		}
+	}
+
+	stop() {
+		this.generation++
+		this.stopOwn?.()
+		for (const child of this.children) {
+			child.stop()
+		}
+	}
+
+	run(definition: AnimationDefinition, delay = 0): Promise<AnimationResult> {
+		this.animate = isLabels(definition) ? definition : undefined
+		this.stop()
+		const generation = this.generation
+		const finished = this.runTree(definition, delay, generation)
+		this.active = { definition, finished, generation }
+		return finished
+	}
+
+	private async runTree(
+		definition: AnimationDefinition,
+		delay: number,
+		generation: number,
+	): Promise<AnimationResult> {
+		const { target, transition } = this.resolve(definition)
+		const participants = [...this.children]
+		const own = () =>
+			this.play(
+				definition,
+				target,
+				playbackTransition(
+					transition,
+					transition.when === 'afterChildren' && participants.length && isLabels(definition)
+						? 0
+						: delay,
+				),
+			)
+
+		const children = () =>
+			Promise.all(
+				isLabels(definition)
+					? participants
+							.filter((child) => this.children.has(child))
+							.map((child, index) =>
+								child.run(
+									definition,
+									(transition.when === 'beforeChildren' ? 0 : delay) +
+										(transition.delayChildren ?? 0) +
+										index * (transition.staggerChildren ?? 0),
+								),
+							)
+					: [],
+			)
+
+		let results: AnimationResult[]
+		if (transition.when === 'beforeChildren') {
+			const result = await own()
+			if (generation !== this.generation || result !== 'finished') {
+				return 'cancelled'
+			}
+
+			results = [result, ...(await children())]
+		} else if (transition.when === 'afterChildren') {
+			results = await children()
+			if (generation !== this.generation || results.some((result) => result !== 'finished')) {
+				return 'cancelled'
+			}
+
+			results.push(await own())
+		} else {
+			const parent = own()
+			const descendants = children()
+			results = [await parent, ...(await descendants)]
+		}
+
+		return generation === this.generation && results.every((result) => result === 'finished')
+			? 'finished'
+			: 'cancelled'
+	}
+}

package/types/engine.d.ts

@@ -1,5 +1,5 @@
-import type { Clock } from './clock-types';
-import type { Transition } from './types';
+import type { Clock } from './clock-types.js';
+import type { Transition, TransitionInput, TransitionOrchestration, MotionKey } from './types.js';
 /** Terminal status; cancellation never masquerades as completion. */
 export type AnimationResult = 'finished' | 'cancelled' | 'replaced';
 /** A cancellable animation whose finished promise always settles. */
@@ -7,5 +7,11 @@ export interface AnimationControls {
     finished: Promise<AnimationResult>;
     stop(reason?: Exclude<AnimationResult, 'finished'>): void;
 }
+export declare function isBezierEase(ease: Transition['ease']): boolean;
+/** CSS cubic-bezier control points for a delegatable ease; tuples pass through. */
+export declare function bezierPoints(ease: Transition['ease']): [number, number, number, number];
+export declare function isOrchestrated(t: TransitionInput | undefined): t is TransitionOrchestration;
+export declare function resolveTransition(t: TransitionInput, key: MotionKey): Transition;
 export declare function validateTransition(t: Transition): void;
+export declare function validateTransitionInput(t: TransitionInput): void;
 export declare function runAnimation(clock: Clock, from: number, to: number, transition: Transition, update: (value: number) => void, complete?: () => void): AnimationControls;