# UI Animations

A comprehensive CSS animation library with Angular services and directives for programmatic control.

## Features

- **Pure CSS animations** - Framework agnostic, works everywhere
- **Angular integration** - Services and directives for programmatic control
- **Comprehensive collection** - Entrance, exit, emphasis, and transition animations
- **Design system integration** - Uses semantic motion tokens for consistent timing and easing
- **Utility classes** - Animation timing, delays, and control utilities
- **SCSS mixins** - Create custom animations easily

## Installation

```bash
npm install ui-animations
```

## Usage

### Import Styles

Add to your global styles or component styles:

```scss
// Complete animation library
@use 'ui-animations/src/styles' as animations;

// Or import specific modules
@use 'ui-animations/src/styles/animations/entrances';
@use 'ui-animations/src/styles/animations/emphasis';
@use 'ui-animations/src/styles/utilities/animation-utilities';
```

### CSS Classes

Simply add animation classes to your HTML elements:

```html
<!-- Entrance animations -->
<div class="animate-fade-in">Fade in animation</div>
<div class="animate-slide-in-up animation-delay-200">Delayed slide up</div>

<!-- Emphasis animations -->
<button class="animate-bounce">Bouncing button</button>
<div class="animate-pulse animation-infinite">Pulsing element</div>

<!-- Exit animations -->
<div class="animate-fade-out">Fade out animation</div>
```

### Angular Service

```typescript
import { UiAnimationsService } from 'ui-animations';

constructor(private animationService: UiAnimationsService) {}

// Animate an element
animateElement() {
  const element = document.getElementById('my-element');
  this.animationService.animateOnce(element, 'animate-bounce');
}

// Animate with callback
animateWithCallback() {
  const element = document.getElementById('my-element');
  this.animationService.animate(element, 'animate-fade-out', () => {
    console.log('Animation completed!');
  });
}
```

### Angular Directive

```typescript
import { AnimateDirective } from 'ui-animations';

@Component({
  imports: [AnimateDirective]
})
```

```html
<!-- Immediate animation -->
<div uiAnimate="animate-fade-in-up">Auto animates on load</div>

<!-- Hover trigger -->
<div uiAnimate="animate-bounce" [animationTrigger]="'hover'">
  Hover to animate
</div>

<!-- Click trigger with single use -->
<button uiAnimate="animate-tada" [animationTrigger]="'click'" [animationOnce]="true">
  Click me!
</button>
```

## Animation Categories

### Entrances
- `animate-fade-in` - Basic fade in
- `animate-fade-in-up/down/left/right` - Fade with direction
- `animate-slide-in-up/down` - Slide animations
- `animate-zoom-in` - Scale up animation
- `animate-rotate-in` - Rotate entrance

### Exits
- `animate-fade-out` - Basic fade out
- `animate-fade-out-up/down/left/right` - Fade with direction
- `animate-slide-out-up/down` - Slide animations
- `animate-zoom-out` - Scale down animation
- `animate-rotate-out` - Rotate exit

### Emphasis
- `animate-bounce` - Bouncing effect
- `animate-shake` - Horizontal shake
- `animate-pulse` - Scaling pulse
- `animate-wobble` - Wobble motion
- `animate-tada` - Celebration animation
- `animate-heartbeat` - Heart beat effect

### Utilities
- `animation-delay-100/200/300/500/1000` - Animation delays
- `animation-duration-fast/normal/slow/slower` - Duration control
- `animation-infinite/once/twice` - Iteration control
- `animation-paused/running` - Playback control

## SCSS Mixins

Create custom animations using provided mixins with semantic tokens:

```scss
@use 'ui-animations/src/styles/mixins/animation-mixins' as mixins;
@use 'ui-design-system/src/styles/semantic/motion' as motion;

.my-custom-animation {
  @include mixins.animate(myKeyframes, motion.$semantic-motion-duration-normal, motion.$semantic-motion-easing-ease-out);
}

.hover-effect {
  @include mixins.hover-animation(transform, scale(1.1), motion.$semantic-motion-duration-fast);
}

.loading-spinner {
  @include mixins.loading-animation(40px, #007bff);
}
```

## Design System Integration

All animations now use semantic motion tokens from the design system:

- **Durations**: `$semantic-motion-duration-fast`, `$semantic-motion-duration-normal`, `$semantic-motion-duration-slow`, etc.
- **Easing**: `$semantic-motion-easing-ease-out`, `$semantic-motion-easing-spring`, `$semantic-motion-easing-bounce`, etc.
- **Spacing**: Animation distances use semantic spacing tokens for consistency
- **Timing**: Delays use semantic transition timing tokens

This ensures animations are consistent with your design system's motion principles.

## Demo

Visit the demo application to see all animations in action and experiment with different options.