@octane-xplat/motion 0.9.0 → 0.11.0

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.js';
-import type { Transition } from './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;

package/types/index.d.ts

@@ -1,18 +1,27 @@
 import type { UniversalComponent } from 'octane/universal'
 import type {
+	MotionProps,
 	MotionViewProps,
 	MotionRowProps,
 	MotionPressableProps,
 	MotionConfigProps,
+	Target,
 	Transition,
+	TransitionInput,
 } from './types.js'
 
 import type { MotionValue, MotionValueEvents } from './value.js'
-/** Bounded motion hosts for shared xplat UI primitives. */
+import type { AnimationControls, AnimationResult } from './engine.js'
+/** Bounded motion hosts for shared xplat UI primitives; `motion.create` wraps
+ *  any component that accepts `ref`/`style`/`children`. All hosts support
+ *  numeric variants and root-local initial/animate label inheritance. */
 export declare const motion: {
 	View: UniversalComponent<MotionViewProps>
 	Row: UniversalComponent<MotionRowProps>
 	Pressable: UniversalComponent<MotionPressableProps>
+	create: <P extends Record<string, unknown>>(
+		component: (props: P) => any,
+	) => UniversalComponent<P & MotionProps>
 }
 
 /** Inherit transition and reduced-motion defaults within this root. */
@@ -52,8 +61,20 @@ export declare function useSpring(
 	options?: Omit<Transition, 'type' | 'duration' | 'ease' | 'delay'>,
 ): MotionValue
 
+/** Scoped imperative animation: `const [scope, animate] = useAnimate()` then
+ *  `ref={scope}` on a motion host. */
+export declare function useAnimate(): [
+	{ current: any },
+	(
+		target: Target | MotionValue | object,
+		transitionOrTo?: TransitionInput | number,
+		transition?: Transition,
+	) => Promise<AnimationResult> | AnimationControls,
+]
+
 export type { MotionValue, MotionValueEvents }
 export type { AnimationControls, AnimationResult } from './engine.js'
+/** Includes bounded drag props and DragInfo callback payloads on both targets. */
 export type * from './types.js'
 
 /** Retain live children through exit; removing the boundary disposes immediately. */

package/types/types.d.ts

@@ -1,20 +1,36 @@
-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. */
 export type MotionKey = 'opacity' | 'x' | 'y' | 'scale' | 'scaleX' | 'scaleY' | 'rotate';
 /** 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;
@@ -22,27 +38,94 @@ export interface Transition {
     restSpeed?: number;
     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/types/value.d.ts

@@ -37,8 +37,11 @@ export declare class MotionValue {
     on<K extends keyof MotionValueEvents>(event: K, callback: MotionValueEvents[K]): () => void;
     private emit;
     private write;
+    /** Update position bookkeeping without emitting — platform-delegated runs
+     *  track presentation state so interruption reads fresh value/velocity. */
+    track(value: number): void;
     /** 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;
     /** Stop playback at its current value. */
     stop(reason?: 'cancelled' | 'replaced'): void;
     /** Release playback and listeners when the owning component unmounts. */