@octane-xplat/motion 0.7.3 → 0.10.0

package/types/index.d.ts

@@ -1,18 +1,29 @@
 import type { UniversalComponent } from 'octane/universal'
 import type {
+	MotionProps,
 	MotionViewProps,
 	MotionRowProps,
 	MotionPressableProps,
 	MotionConfigProps,
+	Target,
 	Transition,
-} from './types'
-import type { MotionValue, MotionValueEvents } from './value'
-/** Bounded motion hosts for shared xplat UI primitives. */
+	TransitionInput,
+} from './types.js'
+
+import type { MotionValue, MotionValueEvents } from './value.js'
+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. */
 export declare const MotionConfig: UniversalComponent<MotionConfigProps>
 /** Observe the live system reduced-motion preference. */
@@ -25,6 +36,7 @@ export declare function useMotionValueEvent<K extends keyof MotionValueEvents>(
 	event: K,
 	callback: MotionValueEvents[K],
 ): void
+
 /** Derive a numeric value by mapping ranges or transforming source samples. */
 export declare function useTransform(
 	source: MotionValue,
@@ -32,22 +44,38 @@ export declare function useTransform(
 	output: number[],
 	options?: { clamp?: boolean },
 ): MotionValue
+
 export declare function useTransform(
 	source: MotionValue,
 	transform: (value: number) => number,
 ): MotionValue
+
 export declare function useTransform(
 	source: MotionValue[],
 	transform: (values: number[]) => number,
 ): MotionValue
+
 /** Spring toward set targets or a source MotionValue; jump snaps. */
 export declare function useSpring(
 	source: number | MotionValue,
 	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'
-export type * from './types'
+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. */
-export declare const Presence: UniversalComponent<import('./types').PresenceProps>
+export declare const Presence: UniversalComponent<import('./types.js').PresenceProps>

package/types/types.d.ts

@@ -1,20 +1,36 @@
-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. */
 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

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