🎨 Flash Animations Library

Complete Angular animation system with automatic Flash Persistence integration

Beautiful, modern animations that can be applied anywhere - from simple HTML elements to complex route transitions.

✨ Features

• 🎭 13 Animation Presets - fade, slide, scale, bounce, glassmorphism, shimmer, liquid, pulse, shake, glow
• ⚡ 5 Speed Settings - instant, fast, normal, slow, elegant
• 🔧 Zero Configuration - Works out of the box with Flash Persistence
• 🎨 7 Color Themes - Ocean Blue, Sunset Orange, Forest Green, Purple Dream, Golden Hour, Cherry Blossom, Arctic Ice
• 📱 Fully Responsive - Adapts to all screen sizes
• 🌓 Theme Support - Light, dark, and auto modes
• ♿ Accessible - Respects prefers-reduced-motion
• 🚀 Performant - GPU-accelerated animations

🎯 NEW: Multiple Ways to Apply Animations

1. 🎭 HTML Directives - Apply to Any Element

<!-- Basic animation -->
<div flashAnim="fade-in" faSpeed="fast">Content</div>

<!-- Click animation -->
<button flashAnimClick="bounce-in">Click me!</button>

<!-- Hover with exit animation -->
<div flashAnimHover="glow" flashAnimExit="fade-out">Hover me</div>

<!-- Viewport animation (scroll-triggered) -->
<div flashAnimViewport="slide-up" [flashAnimThreshold]="0.5">
  Appears when scrolled into view
</div>

<!-- Multiple interactions -->
<div flashAnimClick="shake" flashAnimHover="pulse" flashAnimFocus="scale-in">
  Interactive element
</div>

2. 🎮 TypeScript Dynamic Control - Programmatic Animations

import { FlashAnimationController, flashAnimate, flashPulse } from '@widgets-editor/flash-animations';

export class MyComponent {
  private animController = inject(FlashAnimationController);
  @ViewChild('myElement') element!: ElementRef;

  async triggerAnimation() {
    // Simple helper function
    await flashAnimate(this.element, 'bounce-in', 'fast');

    // Advanced controller
    await this.animController.animate(this.element, 'slide-up', {
      speed: 'elegant',
      delay: 300,
      onComplete: () => console.log('Done!')
    });

    // Sequence of animations
    await this.animController.sequence(this.element, [
      { preset: 'fade-in', speed: 'fast' },
      { preset: 'glow', speed: 'slow', delay: 500 }
    ]);
  }

  // Quick feedback animations
  showSuccess() { flashSuccess(this.element); }
  showError() { flashError(this.element); }
  startLoading() { return flashStartLoading(this.element); }
}

3. 🛣️ Route-Level Animations - Entire Component Transitions

// In your main app component
import { flashRouteAnimations, FlashRouteAnimationService } from '@widgets-editor/flash-animations';

@Component({
  animations: [flashRouteAnimations],
  template: `
    <div [@flashRouteTransition]="getRouteAnimationData()"
         [@.params]="getAnimationParams()">
      <router-outlet></router-outlet>
    </div>
  `
})
export class AppComponent {
  constructor(private routeAnimations: FlashRouteAnimationService) {}

  ngOnInit() {
    this.routeAnimations.initialize();
  }

  getRouteAnimationData() {
    return this.routeAnimations.getCurrentAnimationState();
  }

  getAnimationParams() {
    return this.routeAnimations.getCurrentAnimationParams();
  }
}

// In your routes configuration
const routes: Routes = [
  {
    path: 'dashboard',
    component: DashboardComponent,
    data: {
      animation: 'slideLeft',        // Animation type
      animationSpeed: 'fast',        // Speed override
      staggerChildren: true          // Stagger child elements
    }
  },
  {
    path: 'profile',
    component: ProfileComponent,
    data: {
      animation: 'elegant',          // Uses Flash Persistence user preferences
      animationDuration: 400         // Custom duration in ms
    }
  }
];

🚀 Quick Start

1. Installation

The library is already available in your monorepo at @widgets-editor/flash-animations.

2. Import What You Need

// For HTML directives
import {
  FlashAnimateDirective,
  FlashAnimateViewportDirective,
  FlashAnimateInteractionDirective
} from '@widgets-editor/flash-animations';

// For TypeScript control
import {
  FlashAnimationController,
  flashAnimate,
  flashPulse,
  createAnimationChain
} from '@widgets-editor/flash-animations';

// For route animations
import {
  flashRouteAnimations,
  FlashRouteAnimationService
} from '@widgets-editor/flash-animations';

// For the demo component
import { FlashAnimationsComponent } from '@widgets-editor/flash-animations';

🎭 Animation Presets

🚀 Advanced Examples

Animation Chains

// Create complex animation sequences
const chain = createAnimationChain(this.element)
  .fadeIn('fast')
  .wait(300)
  .pulse(2)
  .glow('#22c55e', 1000)
  .bounceIn('elegant');

await chain.play();

Staggered Animations

// Animate multiple elements with delays
await this.animController.stagger(
  [this.card1, this.card2, this.card3],
  'slide-up',
  {
    speed: 'fast',
    staggerDelay: 150
  }
);

Conditional Animations

<!-- Animation based on conditions -->
<div [flashAnim]="isSuccess ? 'bounce-in' : 'shake'"
     [faSpeed]="isUrgent ? 'fast' : 'normal'"
     [faEnabled]="animationsEnabled">
  {{ message }}
</div>

Responsive Route Animations

// Service automatically adapts animations for mobile/slow devices
this.routeAnimations.getResponsiveAnimation(); // Returns optimized animation

⚡ Performance Features

• GPU Acceleration - All animations use transform and opacity
• Adaptive Performance - Automatically reduces complexity on slow devices
• Intersection Observer - Efficient viewport-based animations
• Memory Management - Automatic cleanup and resource management
• Bundle Optimization - Tree-shakeable components and utilities

♿ Accessibility

• 🎯 Respects prefers-reduced-motion settings
• 🔍 Full keyboard navigation support
• 📖 ARIA labels and descriptions
• 🎨 High contrast mode support
• 📱 Touch-friendly controls
• ⚡ Automatic duration reduction for accessibility

🔧 Integration Examples

With Angular Material

// Combine with Material components
@Component({
  template: `
    <mat-card flashAnimViewport="slide-up">
      <mat-card-content flashAnimClick="pulse">
        <button mat-raised-button (click)="triggerSuccess()">
          Action
        </button>
      </mat-card-content>
    </mat-card>
  `
})
export class MyComponent {
  triggerSuccess() {
    flashSuccess(this.cardElement);
  }
}

With Forms

<!-- Form validation feedback -->
<input [class.error]="hasError"
       #input
       (blur)="validateField(input)">

<div *ngIf="hasError"
     flashAnim="shake"
     flashAnimExit="fade-out">
  Error message
</div>

With Loading States

async loadData() {
  const stopLoading = flashStartLoading(this.container, 'Loading data');

  try {
    await this.dataService.fetchData();
    flashSuccess(this.container);
  } catch (error) {
    flashError(this.container);
  } finally {
    stopLoading();
  }
}

📊 API Reference

Directives

• flashAnim - Basic animation with trigger control
• flashAnimClick - Click-triggered animations
• flashAnimHover - Hover animations with exit support
• flashAnimFocus - Focus/blur animations for accessibility
• flashAnimViewport - Intersection Observer based animations

Helper Functions

• flashAnimate() - Simple animation application
• flashPulse() - Quick attention animation
• flashShake() - Error indication animation
• flashGlow() - Highlight animation with custom colors
• flashSuccess() - Success feedback (green glow)
• flashError() - Error feedback (shake + red glow)
• flashRipple() - Material Design ripple effect

Controllers

• FlashAnimationController - Advanced programmatic control
• FlashRouteAnimationService - Route-level animation management

🎯 Live Demo

Experience all animations in action:

👉 Visit: /flash-animations-demo

The demo showcases all 13 animation presets, speed controls, and theme integration with automatic Flash Persistence - your preferences are remembered across page refreshes!

🚀 Browser Support

• ✅ Chrome 90+
• ✅ Firefox 88+
• ✅ Safari 14+
• ✅ Edge 90+

💡 Tips & Best Practices

1. Use flashAnimViewport for content that should appear on scroll
2. Combine hover and click animations for rich interactions
3. Use stagger delays for list items and card grids
4. Leverage route animations for smooth page transitions
5. Test on mobile devices - animations auto-optimize
6. Respect accessibility - library handles prefers-reduced-motion
7. Chain animations for complex sequences
8. Use feedback animations for user actions (success/error)

The Flash Animations library provides everything you need for beautiful, performant animations across your entire Angular application! 🎉