Ember Animated

In Ember Animated, a sprite is an HTML element packaged with additional metadata such as width, height, CSS styles, and historical bounds. Sprites allow developers to animate HTML elements and respond to state changes (like elements entering or leaving the DOM) without manual bookkeeping of element positions.

By using sprites, you can animate elements from a starting point to a final location, or from a current location to an exit point, as well as smoothly transition elements that remain in the DOM during a state change.

When elements are moved from one list or component to another (e.g., moving an item from a 'Going' list to a 'Not Going' list), they can be treated as receivedSprites and sentSprites.

Ember Animated tracks the initial and final bounds of a sprite. If these bounds are interchanged, the library identifies the sprite as traveling between two specific lists. This allows for smooth transitions even when an element is being removed from one container and simultaneously inserted into another.

• receivedSprites: A sprite is a receivedSprite on the destination list when its final bounds match its initial bounds (it is arriving at its new location).
• sentSprites: A sprite is a sentSprite on the source list when its initial bounds match its final bounds (it is leaving its old location).

When animating the size of a sprite, you have two primary options:

1. resize: Animates the height and width properties. It supports length values (like px or cm) and percentages. This is the default motion used by animated-container.
2. scale: Applies CSS transforms to animate the size.

Recommendation: Use scale instead of resize whenever possible, as scale uses CSS transforms and avoids triggering browser reflow, leading to better performance.

The rules property allows you to select different animated transitions based on changes in data. When a component has both rules and a transition, the rules take precedence.

Rules work by comparing the previous state (oldList) to the new state (newList). You can define logic that evaluates these values to return a specific transition name or object.

Example Logic:

• If newList[0] > oldList[0], use the toUp transition.
• If newList[0] < oldList[0], use the toDown transition.

// Conceptual logic for a rules function
// rules(oldList, newList) -> transition

if (newList[0] > oldList[0]) {
  return 'toUp';
} else if (newList[0] < oldList[0]) {
  return 'toDown';
}

A motion animates the change in an attribute value of a single sprite. It is used to smoothly transition a sprite from one state to another (e.g., changing color, size, or position) rather than having the sprite jump abruptly between values.

Usage Pattern: Each motion takes a sprite as the first argument and an options object as the second argument. Motions can also accept from and to arguments to explicitly define the initial and final attribute values.

motion(sprite, options) or motion(sprite, { from: value, to: value })

A transition defines how sprite categories animate when moving from one state to another. You can assign specific motions to different sprite categories, such as insertedSprites, keptSprites, or removedSprites.

Key characteristics of transitions:

• Interruptible: If a sprite's state changes while a transition is already in progress, the animation can reverse or change direction immediately (e.g., an 'undo' action reversing a movement).
• State-driven: Transitions run every time the state of a sprite changes.
• Category-based: You can target specific lifecycle stages of a sprite (like when it is first added to a list) to apply specific animations.

To set up the test-app environment for development, ensure you have Git, Node.js, pnpm, Ember CLI, and Google Chrome installed. Follow these steps to clone the repository and install dependencies:

1. Clone the repository.
2. Navigate to the test-app directory.
3. Install dependencies using pnpm.
4. Start the development server.

git clone https://github.com/ember-animation/ember-animated.git
cd ember-animated/test-app
pnpm install
ember s

To ensure code quality, use the following linting commands:

• pnpm lint: Runs the linter to check for issues.
• pnpm lint:fix: Runs the linter and automatically attempts to fix fixable issues.

Build the application for different environments using pnpm build:

• Development build: pnpm build
• Production build: pnpm build --environment production