tessl/npm-rc-motion

React lifecycle controlled motion library for smooth enter/leave transitions and list animations

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Single Element Animation

Name: tessl/npm-rc-motion
Author: tessl

Core functionality for animating individual React elements with enter/leave/appear transitions. CSSMotion provides comprehensive lifecycle control over element animations with both CSS-based and JavaScript callback support.

Capabilities

CSSMotion Component

Main component for single element animations with full control over motion timing, CSS classes, and animation states.

/**
 * Core motion component for single element animations
 * @param props - Configuration for motion behavior and callbacks
 * @returns React component that renders animated children
 */
export default function CSSMotion(props: CSSMotionProps): React.ReactElement;

interface CSSMotionProps {
  /** CSS class name prefix or object with phase-specific names */
  motionName?: MotionName;
  /** Controls element visibility and triggers transitions */
  visible?: boolean;
  /** Enable appear animation when component mounts */
  motionAppear?: boolean;
  /** Enable enter animation when visible changes to true */
  motionEnter?: boolean;
  /** Enable leave animation when visible changes to false */
  motionLeave?: boolean;
  /** Leave animation immediately without waiting for enter to finish */
  motionLeaveImmediately?: boolean;
  /** Maximum time in milliseconds for motion to complete */
  motionDeadline?: number;
  /** Create element in view even when invisible (display: none) */
  forceRender?: boolean;
  /** Remove element from DOM after leave animation completes */
  removeOnLeave?: boolean;
  /** CSS class applied to element after leave animation */
  leavedClassName?: string;
  /** Private props used by CSSMotionList */
  eventProps?: object;
  
  // Motion phase event handlers
  onAppearPrepare?: MotionPrepareEventHandler;
  onEnterPrepare?: MotionPrepareEventHandler;
  onLeavePrepare?: MotionPrepareEventHandler;
  
  onAppearStart?: MotionEventHandler;
  onEnterStart?: MotionEventHandler;
  onLeaveStart?: MotionEventHandler;
  
  onAppearActive?: MotionEventHandler;
  onEnterActive?: MotionEventHandler;
  onLeaveActive?: MotionEventHandler;
  
  onAppearEnd?: MotionEndEventHandler;
  onEnterEnd?: MotionEndEventHandler;
  onLeaveEnd?: MotionEndEventHandler;
  
  /** Called when final visible state changes */
  onVisibleChanged?: (visible: boolean) => void;
  
  /** Internal ref for advanced use cases */
  internalRef?: React.Ref<any>;
  
  /** Render function receiving props and ref */
  children?: (
    props: {
      visible?: boolean;
      className?: string;
      style?: React.CSSProperties;
      [key: string]: any;
    },
    ref: (node: any) => void,
  ) => React.ReactElement;
}

Usage Examples:

import CSSMotion from "rc-motion";

// Basic fade animation
function FadeExample() {
  const [visible, setVisible] = useState(true);
  
  return (
    <CSSMotion
      visible={visible}
      motionName="fade"
      motionAppear
      motionEnter
      motionLeave
    >
      {({ style, className }) => (
        <div style={style} className={className}>
          Content that fades in/out
        </div>
      )}
    </CSSMotion>
  );
}

// Complex animation with callbacks
function ComplexAnimation() {
  return (
    <CSSMotion
      visible={true}
      motionName={{
        appear: 'slide-up',
        appearActive: 'slide-up-active',
        enter: 'slide-down',
        enterActive: 'slide-down-active',
        leave: 'slide-out',
        leaveActive: 'slide-out-active'
      }}
      motionDeadline={1000}
      onAppearStart={(element) => {
        console.log('Appear animation started');
        return { opacity: 0, transform: 'translateY(20px)' };
      }}
      onAppearActive={(element) => {
        console.log('Appear animation active');
        return { opacity: 1, transform: 'translateY(0)' };
      }}
      onAppearEnd={(element, event) => {
        console.log('Appear animation completed');
        return false; // Don't prevent other animations
      }}
    >
      {({ style, className, visible }) => (
        <div style={style} className={className}>
          {visible && "Animated content with callbacks"}
        </div>
      )}
    </CSSMotion>
  );
}

Motion Name Configuration

Flexible system for defining CSS class names during different animation phases.

type MotionName = string | {
  appear?: string;
  enter?: string;
  leave?: string;
  appearActive?: string;
  enterActive?: string;
  leaveActive?: string;
};

String format: Class names are generated as ${motionName}-${phase} and ${motionName}-${phase}-active.

Object format: Explicit class names for each phase and active state.

Motion Event Handlers

Callback functions for different phases of animation lifecycle.

/**
 * Prepare phase handler - called before animation starts
 * Used for measuring element dimensions or setting up initial state
 */
type MotionPrepareEventHandler = (
  element: HTMLElement,
) => Promise<any> | void;

/**
 * Motion event handler - called during animation phases
 * Can return CSS properties to apply during the phase
 */
type MotionEventHandler = (
  element: HTMLElement,
  event: MotionEvent,
) => React.CSSProperties | void;

/**
 * End event handler - called when animation phase completes
 * Return true to prevent default behavior
 */
type MotionEndEventHandler = (
  element: HTMLElement,
  event: MotionEvent,
) => boolean | void;

/**
 * Motion event extends browser events with deadline flag
 */
type MotionEvent = (TransitionEvent | AnimationEvent) & {
  deadline?: boolean;
};

Motion Configuration

Advanced configuration options for fine-tuning motion behavior.

type CSSMotionConfig = boolean | {
  transitionSupport?: boolean;
  forwardRef?: boolean; // Deprecated
};

/**
 * Generate CSSMotion component with custom configuration
 * @param config - Motion configuration or boolean for transition support
 * @returns Configured CSSMotion component
 */
function genCSSMotion(config: CSSMotionConfig): React.ComponentType<CSSMotionProps>;

Internal State Interface

Internal state structure used by CSSMotion component.

interface CSSMotionState {
  status?: MotionStatus;
  statusActive?: boolean;
  newStatus?: boolean;
  statusStyle?: React.CSSProperties;
  prevProps?: CSSMotionProps;
}

type MotionStatus = 'none' | 'appear' | 'enter' | 'leave';

Install with Tessl CLI