npm package: @stellix-agency/motion
Description: An intuitive GSAP wrapper for creating stunning animations with ease.
Author: Stellix Agency
Latest version: 1.0.6

# Magic Motion 🎬

An intuitive and powerful GSAP wrapper for creating stunning animations with ease. Built for Solid.js and Astro projects.

**Transform JSON into beautiful animations** - The simplest way to animate your web applications.

## Features

✨ **JSON-First API** - Define animations with simple JSON objects  
🎯 **TypeScript First** - Full type safety with comprehensive intellisense  
📜 **Scroll Animations** - Easy ScrollTrigger integration  
🎨 **Rich Animations** - Fade, slide, scale, rotate, blur, skew, and more  
🔧 **Utility Functions** - Stagger, batch, parallax, and more  
⚡ **Lightweight** - Minimal wrapper over GSAP's powerful engine  
🔄 **Backward Compatible** - Supports both JSON and function APIs  
🔥 **Auto Types** - No manual type declarations needed

## Installation

```bash
npm install @stellix-agency/motion gsap
```

## Quick Setup for TypeScript

To use directives (`use:animate`, `use:hover`) with full TypeScript support, create `src/global.d.ts`:

```typescript
/// <reference types="@stellix-agency/motion/global" />
```

That's it! Restart your TypeScript server and you're good to go.

For more setup options and troubleshooting, see [SETUP.md](./SETUP.md).

## Quick Start

### JSON API (Recommended) 🎯

The simplest way to create animations - just pass JSON configuration:

```tsx
import { animate } from '@stellix-agency/motion';

function MyComponent() {
  return (
    <div
      use:animate={{
        fadeIn: true,
        slideUp: 50,
        scale: 1.2,
        scroll: true,
      }}
    >
      Animated content appears on scroll!
    </div>
  );
}
```

### Simple JSON Syntax

```tsx
<div
  use:animate={{
    fadeIn: true,              // Boolean for defaults
    slideUp: 50,               // Number for distance/value
    scale: 1.2,                // Direct values
    rotate: 360,               // Rotation in degrees
    duration: 0.8,             // Default duration
    ease: 'power4.out',        // Default easing
    scroll: true,              // Enable scroll trigger
  }}
>
  Content
</div>
```

### Structured JSON Syntax (Advanced)

For more control, use the structured format:

```tsx
<div
  use:animate={{
    animations: [
      { type: 'fadeIn', duration: 0.6 },
      { type: 'slideUp', distance: 40, ease: 'power2.out' },
      { type: 'wait', duration: 0.2 },
      { type: 'scale', value: 1.1, ease: 'back.out(1.7)' },
      { type: 'rotate', degrees: 360, duration: 1 },
    ],
    scroll: {
      start: 'top 85%',
      toggleActions: 'play none none reverse',
    },
  }}
>
  Precisely controlled animation
</div>
```

## Animation Types

### Fade Animations

```tsx
// Fade in
<div use:animate={{ fadeIn: true }} />

// Fade out
<div use:animate={{ fadeOut: true }} />

// Fade to specific opacity
<div use:animate={{ fade: 0.5 }} />

// With options
<div use:animate={{ 
  fadeIn: { duration: 1, ease: 'power2.out' } 
}} />
```

### Slide Animations

```tsx
// Slide up (default: 50px)
<div use:animate={{ slideUp: true }} />

// Slide with custom distance
<div use:animate={{ slideUp: 100 }} />

// Slide in any direction
<div use:animate={{ slideDown: 50 }} />
<div use:animate={{ slideLeft: 50 }} />
<div use:animate={{ slideRight: 50 }} />

// With options
<div use:animate={{ 
  slideUp: { distance: 80, duration: 0.6, ease: 'power3.out' } 
}} />
```

### Scale Animations

```tsx
// Simple scale
<div use:animate={{ scale: 1.2 }} />

// With custom easing
<div use:animate={{ 
  scale: { value: 1.5, ease: 'back.out(1.7)', duration: 0.8 } 
}} />

// Structured format for scaleX/scaleY
<div use:animate={{
  animations: [
    { type: 'scale', value: 1.2, scaleX: 1.5, scaleY: 0.9 }
  ]
}} />
```

### Rotate Animations

```tsx
// Simple rotation
<div use:animate={{ rotate: 360 }} />

// With options
<div use:animate={{ 
  rotate: { degrees: 180, duration: 1, ease: 'elastic.out' } 
}} />
```

### Move Animations

```tsx
// Move to position
<div use:animate={{ 
  move: { x: 100, y: 50 } 
}} />

// With options
<div use:animate={{ 
  move: { x: 0, y: -20, duration: 0.5, ease: 'power2.out' } 
}} />
```

### Blur Animations

```tsx
// Blur effect (useful for focus/unfocus)
<div 
  use:animate={{ blur: 0 }} 
  style={{ filter: 'blur(10px)' }}
/>

// With options
<div use:animate={{ 
  blur: { amount: 0, duration: 0.8 } 
}} />
```

### Skew Animations

```tsx
// Skew transformation
<div use:animate={{ 
  skew: { x: -5, y: 0 } 
}} />

// With options
<div use:animate={{ 
  skew: { x: 10, y: 5, duration: 0.4, ease: 'power1.out' } 
}} />
```

### Custom Animations

```tsx
// Any GSAP-compatible properties
<div use:animate={{
  custom: {
    backgroundColor: '#ff6b6b',
    borderRadius: '50%',
    color: '#ffffff',
    boxShadow: '0 10px 30px rgba(0,0,0,0.2)',
  },
  duration: 1,
}} />
```

## Scroll Animations

### Simple Scroll Trigger

```tsx
<div use:animate={{
  fadeIn: true,
  slideUp: 50,
  scroll: true,  // Use defaults
}} />
```

### Advanced Scroll Configuration

```tsx
<div use:animate={{
  fadeIn: true,
  slideUp: 50,
  scroll: {
    enabled: true,
    start: 'top 80%',          // When to start
    end: 'bottom 20%',         // When to end
    toggleActions: 'play none none reverse',
    scrub: true,               // Link to scrollbar
    pin: false,                // Pin element
    markers: false,            // Debug markers
  },
}} />
```

### Parallax Effect

```tsx
<div use:animate={{
  animations: [
    { type: 'custom', properties: { y: 200 } }
  ],
  scroll: {
    start: 'top bottom',
    end: 'bottom top',
    scrub: true,
  },
}} />
```

## Hover Animations

### Simple Hover

```tsx
<button use:hover={{
  scale: 1.1,
  rotate: 5,
}}>
  Hover me!
</button>
```

### Advanced Hover

```tsx
<button use:hover={{
  scale: 1.1,
  move: { x: 0, y: -10 },
  custom: {
    boxShadow: '0 10px 30px rgba(0,0,0,0.2)',
  },
  duration: 0.3,
  ease: 'back.out(1.7)',
}}>
  Advanced hover
</button>
```

### Card Hover Effect

```tsx
<div use:hover={{
  animations: [
    { type: 'scale', value: 1.05, duration: 0.3 },
    { type: 'move', x: 0, y: -10, duration: 0.3 },
    {
      type: 'custom',
      properties: {
        boxShadow: '0 15px 40px rgba(0,0,0,0.15)',
      },
    },
  ],
}}>
  Hover for lift effect
</div>
```

## Animation Sequences

### With Wait/Pause

```tsx
<div use:animate={{
  animations: [
    { type: 'fadeIn', duration: 0.5 },
    { type: 'wait', duration: 0.3 },       // Pause
    { type: 'slideUp', distance: 50 },
    { type: 'wait', duration: 0.2 },
    { type: 'scale', value: 1.2 },
  ],
}} />
```

### Staggered Animations

```tsx
const items = ['Item 1', 'Item 2', 'Item 3'];

{items.map((item, index) => (
  <div
    use:animate={{
      fadeIn: { delay: index * 0.1 },
      slideUp: 30,
      scroll: true,
    }}
  >
    {item}
  </div>
))}
```

## Legacy Function API

The library still supports the original function-based API for backward compatibility:

```tsx
import { animate, easings } from '@stellix-agency/motion';

<div
  use:animate={(m) =>
    m.fadeIn({ ease: easings.smoothOut })
     .wait(0.5)
     .rotate(360, { ease: easings.elasticOut })
  }
>
  Content
</div>
```

## Available Easings

```typescript
import { easings } from '@stellix-agency/motion';

// Standard
easings.linear
easings.easeIn, easings.easeOut, easings.easeInOut

// Smooth
easings.smoothIn, easings.smoothOut, easings.smoothInOut

// Bounce
easings.bounceIn, easings.bounceOut, easings.bounceInOut

// Elastic
easings.elasticIn, easings.elasticOut

// Back
easings.backIn, easings.backOut

// Circular
easings.circIn, easings.circOut

// Exponential
easings.expoIn, easings.expoOut
```

## TypeScript Support

Full TypeScript support with comprehensive types:

```typescript
import type {
  AnimationInput,
  AnimationJSON,
  SimpleAnimationJSON,
  AnimationConfig,
  ScrollConfig,
} from '@stellix-agency/motion';
```

## Examples

See the [examples](./examples) directory for more:

- `json-animations.tsx` - JSON API examples
- `solid-directives.tsx` - Legacy function API examples
- `hover-examples.tsx` - Hover animation examples

## Documentation

- [Usage Guide](./USAGE.md) - Comprehensive usage guide
- [Setup Guide](./SETUP.md) - TypeScript setup and troubleshooting
- [Quick Fix](./QUICK_FIX.md) - 30-second TypeScript fix

## License

MIT © [Stellix Agency](https://stellix.agency)

## Credits

Built with ❤️ by [Stellix Agency](https://stellix.agency)  
Powered by [GSAP](https://greensock.com/gsap/)