react-ui-animate 5.3.1 → 5.4.0-next.0

package/dist/index.d.ts

@@ -55,6 +55,10 @@ interface LoopOptions {
     iterations?: number;
     animation?: Descriptor;
 }
+interface StaggerOptions {
+    each?: number;
+    delay?: number;
+}
 type DriverType = 'spring' | 'timing' | 'decay' | 'delay' | 'sequence' | 'loop';
 interface Descriptor {
     type: DriverType;
@@ -100,6 +104,19 @@ interface UseInViewOptions extends IntersectionObserverInit {
 }
 declare function useInView(ref: RefObject<Element>, options?: UseInViewOptions): boolean;
 
+/**
+ * Transition config for `layout` / `layoutId`. Prefer the same descriptor
+ * helpers used everywhere else in the library — options-only form, since
+ * FLIP always settles at identity and there is no target value to declare:
+ *
+ *   layoutOptions={withSpring({ stiffness: 400, damping: 32 })}
+ *   layoutOptions={withTiming({ duration: 300 })}
+ *
+ * Raw `SpringOptions` remain supported for backwards compatibility and are
+ * treated as an implicit spring.
+ */
+type LayoutOptions = Descriptor | SpringOptions$1;
+
 type AnimateValueCompatible = AnimateValue<number> | AnimateValue<string> | AnimateValue<number | string>;
 type CSSPropertiesWithoutTransforms = Omit<CSSProperties, (typeof transformKeys)[number]>;
 type AnimateStyle = {
@@ -116,7 +133,7 @@ type AnimateSVGAttributes<T> = {
 type AnimateProp = {
     [K in keyof AnimateStyle]?: Descriptor | Primitive;
 };
-type AnimateAttributes<T extends EventTarget> = Omit<AnimateHTMLAttributes<T> & AnimateSVGAttributes<T>, 'style' | 'animate' | 'exit' | 'hover' | 'press' | 'focus' | 'view' | 'viewOptions'> & {
+type AnimateAttributes<T extends EventTarget> = Omit<AnimateHTMLAttributes<T> & AnimateSVGAttributes<T>, 'style' | 'animate' | 'exit' | 'hover' | 'press' | 'focus' | 'view' | 'viewOptions' | 'layout' | 'layoutOptions' | 'layoutId'> & {
     style?: AnimateStyle;
     /**
      * Declarative animations to run when the component mounts or updates.
@@ -146,9 +163,40 @@ type AnimateAttributes<T extends EventTarget> = Omit<AnimateHTMLAttributes<T> &
      * Options for the IntersectionObserver used by view animations.
      */
     viewOptions?: UseInViewOptions;
+    /**
+     * When true, automatically animates position and size changes caused by
+     * layout shifts (reordering, resizing, insertion/removal of siblings, etc.)
+     * using a FLIP-style transform animation. Composes with any other transform
+     * already applied to the element (via `style`, `animate`, `hover`, `press`,
+     * or `view`) instead of overwriting it.
+     */
+    layout?: boolean;
+    /**
+     * Transition used by `layout` / `layoutId`. Same descriptor helpers as
+     * `animate` / `hover` / etc., in options-only form (no target — FLIP
+     * always settles at identity):
+     *
+     *   layoutOptions={withSpring({ stiffness: 400, damping: 32 })}
+     *   layoutOptions={withTiming({ duration: 300 })}
+     *
+     * Raw spring option objects are still accepted for backwards compatibility.
+     */
+    layoutOptions?: LayoutOptions;
+    /**
+     * Identifies this element as part of a shared layout transition. When an
+     * element carrying a given `layoutId` unmounts (or moves elsewhere) and a
+     * different element mounts with the same `layoutId`, the new element
+     * automatically plays a FLIP-style transform animation from the previous
+     * element's last known position/size to its own — useful for tab
+     * indicators, expanding cards, and other "morph between elements"
+     * patterns. Uses `layoutOptions` for the transition (spring or timing).
+     * Note: `layoutId`s are tracked in a single global registry, so keep them
+     * unique per active transition group.
+     */
+    layoutId?: string;
 };
 
-declare function makeAnimated<Tag extends keyof JSX.IntrinsicElements>(tag: Tag): react.ForwardRefExoticComponent<Omit<AnimateHTMLAttributes<HTMLElement> & AnimateSVGAttributes<HTMLElement>, "style" | "animate" | "exit" | "hover" | "press" | "focus" | "view" | "viewOptions"> & {
+declare function makeAnimated<Tag extends keyof JSX.IntrinsicElements>(tag: Tag): react.ForwardRefExoticComponent<Omit<AnimateHTMLAttributes<HTMLElement> & AnimateSVGAttributes<HTMLElement>, "style" | "animate" | "exit" | "hover" | "press" | "focus" | "view" | "viewOptions" | "layout" | "layoutOptions" | "layoutId"> & {
     style?: AnimateStyle;
     animate?: AnimateProp;
     exit?: AnimateProp;
@@ -157,6 +205,9 @@ declare function makeAnimated<Tag extends keyof JSX.IntrinsicElements>(tag: Tag)
     focus?: AnimateProp;
     view?: AnimateProp;
     viewOptions?: UseInViewOptions;
+    layout?: boolean;
+    layoutOptions?: LayoutOptions;
+    layoutId?: string;
 } & react.RefAttributes<HTMLElement>>;
 
 declare const animate: { [K in keyof JSX.IntrinsicElements]: ReturnType<typeof makeAnimated<K>>; };
@@ -274,11 +325,14 @@ declare function combine<T extends any[], U>(inputs: {
 
 declare function to(input: number, inRange: number[], outRange: (number | string)[], config?: ExtrapolateConfig): number | string;
 
-declare const withSpring: (to: Descriptor["to"], opts?: SpringOptions$1 & Callbacks) => Descriptor;
-declare const withTiming: (to: Descriptor["to"], opts?: TimingOptions$1 & Callbacks) => Descriptor;
+declare function withSpring(opts: SpringOptions$1 & Callbacks): Descriptor;
+declare function withSpring(to: Descriptor['to'], opts?: SpringOptions$1 & Callbacks): Descriptor;
+declare function withTiming(opts: TimingOptions$1 & Callbacks): Descriptor;
+declare function withTiming(to: Descriptor['to'], opts?: TimingOptions$1 & Callbacks): Descriptor;
 declare const withDecay: (velocity: number, opts?: DecayOptions$1 & Callbacks) => Descriptor;
 declare const withDelay: (ms: number) => Descriptor;
 declare const withSequence: (animations: Descriptor[], opts?: Omit<Callbacks, "onChange">) => Descriptor;
+declare const withStagger: (index: number, descriptor: Descriptor, opts?: StaggerOptions) => Descriptor;
 declare const withLoop: (animation: Descriptor, iterations?: number, opts?: Omit<Callbacks, "onChange">) => Descriptor;
 
 type Widen<T> = T extends number ? number : T extends string ? string : T;
@@ -356,9 +410,6 @@ declare function useIsPresent(): boolean;
  */
 declare function Presence({ children, initial, onExitComplete, mode, }: PresenceProps): ReactElement;
 
-/**
- * Animation Recipes - Pre-built, tested animations for common use cases
- */
 declare const fadeIn: AnimateProp;
 declare const fadeOut: AnimateProp;
 declare const fadeInUp: AnimateProp;
@@ -584,5 +635,5 @@ declare function rubberClamp(value: number, lowerbound: number, upperbound: numb
 declare function snapTo(value: number, velocity: number, snapPoints: Array<number>): number;
 declare function move(array: Array<any>, moveIndex: number, toIndex: number): any[];
 
-export { AnimateValue, Easing, Presence, PresenceContext, animate, bounceIn, bounceOut, clamp, combine, decay, delay, exitFade, exitScale, exitSlideDown, exitSlideUp, fadeIn, fadeInDown, fadeInLeft, fadeInRight, fadeInUp, fadeOut, flipX, flipY, hoverGlow, hoverLift, hoverScale, isAnimateValue, loop, makeAnimated, move, parallel, pressDown, pressScale, recipes, rotateIn, rotateOut, rubberClamp, scaleDown, scaleFadeIn, scaleFadeOut, scaleIn, scaleOut, scaleUp, sequence, slideFadeIn, slideFadeOut, slideInDown, slideInLeft, slideInRight, slideInUp, slideOutDown, slideOutLeft, slideOutRight, slideOutUp, snapTo, spin, spring, timing, to, useDrag, useInView, useIsPresent, useMove, useOutsideClick, usePresence, useRecognizer, useScroll, useScrollProgress, useValue, useWheel, withDecay, withDelay, withLoop, withSequence, withSpring, withTiming, zoomIn, zoomOut };
-export type { AnimateAttributes, AnimateController, AnimateHTMLAttributes, AnimateHooks, AnimateProp, AnimateSVGAttributes, AnimateStyle, Callbacks, Controls, DecayOptions$1 as DecayOptions, DelayOptions, Descriptor, DragConfig, DragEvent, DriverType, ExtrapolateConfig, ExtrapolateType, LoopOptions, MoveEvent, PresenceContextValue, PresenceProps, Primitive, ScrollEvent, SequenceOptions, SpringOptions$1 as SpringOptions, TimingOptions$1 as TimingOptions, UseInViewOptions, UseScrollProgressOptions, WheelEvent };
+export { AnimateValue, Easing, Presence, PresenceContext, animate, bounceIn, bounceOut, clamp, combine, decay, delay, exitFade, exitScale, exitSlideDown, exitSlideUp, fadeIn, fadeInDown, fadeInLeft, fadeInRight, fadeInUp, fadeOut, flipX, flipY, hoverGlow, hoverLift, hoverScale, isAnimateValue, loop, makeAnimated, move, parallel, pressDown, pressScale, recipes, rotateIn, rotateOut, rubberClamp, scaleDown, scaleFadeIn, scaleFadeOut, scaleIn, scaleOut, scaleUp, sequence, slideFadeIn, slideFadeOut, slideInDown, slideInLeft, slideInRight, slideInUp, slideOutDown, slideOutLeft, slideOutRight, slideOutUp, snapTo, spin, spring, timing, to, useDrag, useInView, useIsPresent, useMove, useOutsideClick, usePresence, useRecognizer, useScroll, useScrollProgress, useValue, useWheel, withDecay, withDelay, withLoop, withSequence, withSpring, withStagger, withTiming, zoomIn, zoomOut };
+export type { AnimateAttributes, AnimateController, AnimateHTMLAttributes, AnimateHooks, AnimateProp, AnimateSVGAttributes, AnimateStyle, Callbacks, Controls, DecayOptions$1 as DecayOptions, DelayOptions, Descriptor, DragConfig, DragEvent, DriverType, ExtrapolateConfig, ExtrapolateType, LayoutOptions, LoopOptions, MoveEvent, PresenceContextValue, PresenceProps, Primitive, ScrollEvent, SequenceOptions, SpringOptions$1 as SpringOptions, StaggerOptions, TimingOptions$1 as TimingOptions, UseInViewOptions, UseScrollProgressOptions, WheelEvent };