Core Platform - Animations

This document details the platform.animations library. The module provides a collection of reusable animation definitions (actions, entrances, and exits), directives to manage animation triggers, components to wrap animated content, and services to control animation behavior programmatically.

Overview
Directory Structure
Modules
Directives
Components
Animations
Services
Configuration and Testing
Building and Usage
Conclusion

Overview

The platform.animations package is designed to add dynamic, reusable animations in your Angular projects. It defines a comprehensive set of animation definitions—including actions such as flip, bounce, tada; entrances (e.g. fadeIn, rollIn) and exits (e.g. fadeOut, zoomOut)—and provides directives and components to easily integrate these animations in your templates. The module leverages Angular’s animations API along with configuration from the common package to ensure consistency and simplicity.

Directory Structure

A high-level overview of the project structure:

Root Files:
- Configuration files such as .eslintrc.json, jest.config.ts, ng-package.json, package.json, project.json, and TypeScript configuration files.
- README.md — Brief summary of the library.
src/
- index.ts: Re-exports the module’s features.
- lib/
  - zwp.animations.module.ts: Main Angular module that bundles the animations components and directives.
  - animations/
    - Contains subfolders for animation definitions:
      - actions/ (e.g. bounce.ts, flip.ts, tada.ts)
      - entrances/ (e.g. bounce-in.ts, fade-in.ts)
      - exits/ (e.g. fade-out.ts, zoom-out.ts)
  - components/
    - animation.component.ts — Wraps content to apply animations.
  - directives/
    - animation.container.directive.ts — Sets up elements as animation containers.
    - animation.item.directive.ts — Manages individual animated items.
  - model/
    - Contains type definitions and configuration interfaces (e.g. zwp.animations-module.config.ts) and animation speeds (zwp.animation.speed.ts).
  - services/
    - zwp.animation.service.ts — Provides methods for triggering animations, handling view changes, and integrating scroll/intersection events.
  - utils/
    - Helper functions and factories such as zwp.animation.trigger-mode.factory.

Modules

ZWPAnimationsModule

Purpose:
Bundles all animation-related components, directives, and (re)usable animation definitions.
Setup:
Import this module into your Angular application. It includes a static init() method to configure the trigger mode (e.g. using Intersection Observer or scrolling-based triggers).
See zwp.animations.module.ts for details.

Directives

ZWPAnimationContainerDirective

File: animation.container.directive.ts
Purpose:
Marks an element as an animation container. This directive sets up the view rectangle and passes configuration options (such as offsets) to the animation service.
Usage Notes:
It monitors changes (using ngOnChanges) and cleans up on destroy by deregistering options with the animation service.

ZWPAnimationItemDirective

File: animation.item.directive.ts
Purpose:
Controls individual animated items.
- Listens to input changes (e.g. animation progress).
- Utilizes lifecycle hooks (ngOnInit, ngOnChanges, ngOnDestroy) to initialize and reset the animation player.
Usage Notes:
Designed to be used with container directives to trigger animations based on scrolling or intersection events.

Components

ZWPAnimationComponent

File: animation.component.ts
Purpose:
A wrapper component that applies animations to its content.
- Accepts inputs controlling timing, delay, pause, replay, and animation type.
- Emits events when an animation starts and completes.
Key Features:
- Uses HostBindings to connect with Angular’s animation trigger.
- Relies on ZWPAnimationService to determine animation “idle” and “play” states.
- Optimized with OnPush change detection to enhance performance.

Animations

The animations library is composed of pre-defined animation definitions. These are grouped into three main categories:

Action Animations

What It Is:
Animations triggered by user or programmatic actions (e.g. clicks).
Examples:
- Bounce: bounce.ts defines keyframes that create a bouncing effect.
- Flip: flip.ts includes multiple variations such as flipXVisible, flipYFromHidden, etc.
- Tada: tada.ts applies a lively scale and rotation effect.

Entrance Animations

What It Is:
Animations used to animate elements as they enter the view.
Examples:
- Fade In: fade-in.ts smoothly transitions elements from transparent to visible.
- Bounce In: bounce-in.ts gives a bouncing entrance effect.
- Roll In / Flip In: Other entrance variations like rollIn and flipInX/flipInY provide dynamic reveals.

Exit Animations

What It Is:
Animations for gracefully removing elements from view.
Examples:
- Fade Out: fade-out.ts transitions elements to invisibility.
- Zoom Out: zoom-out.ts scales elements down while fading out.
- Bounce Out: bounce-out.ts creates a dramatic exit with a bounce effect.

All animation definitions are consolidated and re-exported via animations/index.ts.

Services

ZWPAnimationService

File: zwp.animation.service.ts
Purpose:
Centralizes animation control across the module.
Key Responsibilities:
- Configures animation options and initializes view rectangle parameters.
- Provides trigger functions that decide when an element should animate based on scroll or intersection.
- Manages animation players, resets, and cleans up on destroy.
How It Works:
Uses Angular CDK’s ScrollDispatcher and ViewportRuler to observe scroll events. It also supports using an Intersection Observer when configured via the module’s trigger mode.

Configuration and Testing

Linting and Formatting:
Managed using .eslintrc.json and Prettier files.
Unit Testing:
Jest is configured via jest.config.ts and tsconfig.spec.json. A dedicated test-setup.ts is used to initialize test environments.
Nx Targets:
The project.json file defines build, test, and lint targets:
- Build: nx build platform.animations
- Test: nx test platform.animations
- Lint: nx lint platform.animations

Building and Usage

Build the Package:
```
 nx build platform.animations
```
Run Tests:
```
 nx test platform.animations
```

Usage in an Angular Project: Import the module and configure it in your application module:

 import { ZWPAnimationsModule } from '@zwp/platform.animations';

 @NgModule({
   imports: [
     ZWPAnimationsModule.init('intersectionObserver'),
     // other imports...
   ]
 })
 export class AppModule {}

Conclusion

The platform.animations package provides a rich set of tools to add dynamic visual effects to your application. It combines pre-defined animations with customizable directives, components, and services to seamlessly integrate animated behavior—whether for simple entrance effects or complex action-driven sequences. This documentation aims to serve as a comprehensive guide to understanding, using, and extending the animations functionality in our projects.