npm package: @foundrykit/animation
Description: A collection of reusable animation components and utilities built with Framer Motion. Provides consistent, performant animations for React applications.
Latest version: 1.0.9

# @foundrykit/animation

A collection of reusable animation components and utilities built with Framer
Motion. Provides consistent, performant animations for React applications.

## Features

- **Framer Motion powered** - Built on industry-standard animation library
- **Pre-built animations** - Ready-to-use animation components
- **Customizable** - Easy to adjust timing, easing, and variants
- **Performance optimized** - Uses Framer Motion's optimized rendering
- **TypeScript support** - Full type safety for animation props
- **Accessible** - Respects user motion preferences

## Installation

```bash
pnpm add @foundrykit/animation
```

## Available Animations

### Fade Animations

- **FadeIn** - Smooth fade-in animation with configurable delays
- **FadeOut** - Fade-out animation for removing elements

### Scale Animations

- **Scale** - Scale in/out animations with spring physics
- **ScaleIn** - Scale from 0 to 1 with bounce effect

### Slide Animations

- **SlideUp** - Slide elements up from below
- **SlideDown** - Slide elements down from above
- **SlideIn** - Slide in from any direction

### Stagger Animations

- **Stagger** - Animate multiple children with staggered delays
- **StaggerContainer** - Container for staggered child animations

## Usage

### Basic Example

```tsx
import { FadeIn, Scale, SlideUp } from '@foundrykit/animation';

function MyComponent() {
  return (
    <div>
      <FadeIn delay={0.2}>
        <h1>Welcome</h1>
      </FadeIn>

      <Scale>
        <button>Click me</button>
      </Scale>

      <SlideUp>
        <p>This content slides up</p>
      </SlideUp>
    </div>
  );
}
```

### Staggered Animations

```tsx
import { StaggerContainer, FadeIn } from '@foundrykit/animation';

function ListWithStagger() {
  return (
    <StaggerContainer staggerDelay={0.1}>
      {items.map((item, index) => (
        <FadeIn key={item.id}>
          <ListItem item={item} />
        </FadeIn>
      ))}
    </StaggerContainer>
  );
}
```

### Custom Animation Variants

```tsx
import { FadeIn } from '@foundrykit/animation';

function CustomAnimation() {
  return (
    <FadeIn
      duration={0.8}
      ease='easeOut'
      initial={{ opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
    >
      <div>Custom animated content</div>
    </FadeIn>
  );
}
```

### Conditional Animations

```tsx
import { Scale } from '@foundrykit/animation';

function ConditionalAnimation({ isVisible }) {
  return (
    <Scale
      animate={isVisible ? 'visible' : 'hidden'}
      variants={{
        visible: { scale: 1, opacity: 1 },
        hidden: { scale: 0.8, opacity: 0 },
      }}
    >
      <div>Conditionally animated</div>
    </Scale>
  );
}
```

## Animation Components

### FadeIn

Smooth fade-in animation with configurable timing.

```tsx
import { FadeIn } from '@foundrykit/animation';

<FadeIn delay={0.2} duration={0.6}>
  <div>Fades in after 0.2s</div>
</FadeIn>;
```

**Props:**

- `delay` - Delay before animation starts (default: 0)
- `duration` - Animation duration in seconds (default: 0.5)
- `ease` - Easing function (default: "easeOut")

### Scale

Scale animation with spring physics.

```tsx
import { Scale } from '@foundrykit/animation';

<Scale>
  <button>Scales in on mount</button>
</Scale>;
```

**Props:**

- `scale` - Target scale value (default: 1)
- `spring` - Spring configuration object
- `delay` - Delay before animation starts

### SlideUp

Slide animation from bottom to top.

```tsx
import { SlideUp } from '@foundrykit/animation';

<SlideUp distance={50}>
  <div>Slides up 50px</div>
</SlideUp>;
```

**Props:**

- `distance` - Distance to slide in pixels (default: 20)
- `duration` - Animation duration (default: 0.5)
- `ease` - Easing function (default: "easeOut")

### StaggerContainer

Container for creating staggered animations.

```tsx
import { StaggerContainer, FadeIn } from '@foundrykit/animation';

<StaggerContainer staggerDelay={0.1}>
  <FadeIn>Item 1</FadeIn>
  <FadeIn>Item 2</FadeIn>
  <FadeIn>Item 3</FadeIn>
</StaggerContainer>;
```

**Props:**

- `staggerDelay` - Delay between child animations (default: 0.1)
- `staggerChildren` - Whether to stagger children (default: true)

## Performance Considerations

### Reduce Motion

All animations respect the user's motion preferences:

```tsx
import { FadeIn } from '@foundrykit/animation';

// Automatically respects prefers-reduced-motion
<FadeIn>
  <div>Accessible animation</div>
</FadeIn>;
```

### Optimized Rendering

- Uses Framer Motion's optimized rendering
- Supports `layout` prop for automatic layout animations
- Implements `AnimatePresence` for exit animations

## Customization

### Custom Variants

```tsx
import { FadeIn } from '@foundrykit/animation'

const customVariants = {
  hidden: { opacity: 0, x: -100 },
  visible: { opacity: 1, x: 0 }
}

<FadeIn variants={customVariants}>
  <div>Custom animation</div>
</FadeIn>
```

### Animation Hooks

```tsx
import { useAnimation } from '@foundrykit/animation';

function CustomComponent() {
  const controls = useAnimation();

  const handleClick = () => {
    controls.start({ scale: 1.1 });
  };

  return (
    <motion.div animate={controls} onClick={handleClick}>
      Click to animate
    </motion.div>
  );
}
```

## Dependencies

- **Framer Motion** - Animation library
- **React** - UI framework
- **@foundrykit/types** - TypeScript definitions

## Contributing

When adding new animations:

1. Follow Framer Motion best practices
2. Ensure accessibility compliance
3. Add TypeScript definitions
4. Include usage examples
5. Test with reduced motion preferences
6. Update this README

## License

MIT