@angular-wave/angular.ts 0.0.14 → 0.0.16

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@angular-wave/angular.ts",
   "license": "MIT",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "main": "dist/angular-ts.esm.js",
   "browser": "dist/angular-ts.umd.js",

package/rollup.config.js

@@ -3,6 +3,10 @@ import commonjs from '@rollup/plugin-commonjs';
 import pkg from './package.json' assert { type: 'json' };
 import terser from '@rollup/plugin-terser';
 
+const terserConfig = terser({
+  mangle: true
+})
+
 export default [
   // browser-friendly UMD build
   {
@@ -12,7 +16,7 @@ export default [
       file: pkg.browser,
       format: 'umd',
     },
-    plugins: [resolve(), commonjs(), terser()],
+    plugins: [resolve(), commonjs(), terserConfig],
   },
 
   // ES module (for bundlers) build.
@@ -25,6 +29,6 @@ export default [
     input: 'src/index.js',
     external: ['ms'],
     output: { file: pkg.main, format: 'es' },
-    plugins: [terser()],
+    plugins: [terserConfig],
   },
 ];

package/src/animations/animate-css.js

@@ -32,220 +32,6 @@ import {
 
 const ANIMATE_TIMER_KEY = "$$animateCss";
 
-/**
- * @ngdoc service
- * @name $animateCss
- * @kind object
- *
- * @description
- * The `$animateCss` service is a useful utility to trigger customized CSS-based transitions/keyframes
- * from a JavaScript-based animation or directly from a directive. The purpose of `$animateCss` is NOT
- * to side-step how `$animate` and ngAnimate work, but the goal is to allow pre-existing animations or
- * directives to create more complex animations that can be purely driven using CSS code.
- *
- * Note that only browsers that support CSS transitions and/or keyframe animations are capable of
- * rendering animations triggered via `$animateCss` (bad news for IE9 and lower).
- *
- * ## General Use
- * Once again, `$animateCss` is designed to be used inside of a registered JavaScript animation that
- * is powered by ngAnimate. It is possible to use `$animateCss` directly inside of a directive, however,
- * any automatic control over cancelling animations and/or preventing animations from being run on
- * child elements will not be handled by AngularJS. For this to work as expected, please use `$animate` to
- * trigger the animation and then setup a JavaScript animation that injects `$animateCss` to trigger
- * the CSS animation.
- *
- * The example below shows how we can create a folding animation on an element using `ng-if`:
- *
- * ```html
- * <!-- notice the `fold-animation` CSS class -->
- * <div ng-if="onOff" class="fold-animation">
- *   This element will go BOOM
- * </div>
- * <button ng-click="onOff=true">Fold In</button>
- * ```
- *
- * Now we create the **JavaScript animation** that will trigger the CSS transition:
- *
- * ```js
- * ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
- *   return {
- *     enter: function(element, doneFn) {
- *       let height = element[0].offsetHeight;
- *       return $animateCss(element, {
- *         from: { height:'0px' },
- *         to: { height:height + 'px' },
- *         duration: 1 // one second
- *       });
- *     }
- *   }
- * }]);
- * ```
- *
- * ## More Advanced Uses
- *
- * `$animateCss` is the underlying code that ngAnimate uses to power **CSS-based animations** behind the scenes. Therefore CSS hooks
- * like `.ng-EVENT`, `.ng-EVENT-active`, `.ng-EVENT-stagger` are all features that can be triggered using `$animateCss` via JavaScript code.
- *
- * This also means that just about any combination of adding classes, removing classes, setting styles, dynamically setting a keyframe animation,
- * applying a hardcoded duration or delay value, changing the animation easing or applying a stagger animation are all options that work with
- * `$animateCss`. The service itself is smart enough to figure out the combination of options and examine the element styling properties in order
- * to provide a working animation that will run in CSS.
- *
- * The example below showcases a more advanced version of the `.fold-animation` from the example above:
- *
- * ```js
- * ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
- *   return {
- *     enter: function(element, doneFn) {
- *       let height = element[0].offsetHeight;
- *       return $animateCss(element, {
- *         addClass: 'red large-text pulse-twice',
- *         easing: 'ease-out',
- *         from: { height:'0px' },
- *         to: { height:height + 'px' },
- *         duration: 1 // one second
- *       });
- *     }
- *   }
- * }]);
- * ```
- *
- * Since we're adding/removing CSS classes then the CSS transition will also pick those up:
- *
- * ```css
- * /&#42; since a hardcoded duration value of 1 was provided in the JavaScript animation code,
- * the CSS classes below will be transitioned despite them being defined as regular CSS classes &#42;/
- * .red { background:red; }
- * .large-text { font-size:20px; }
- *
- * /&#42; we can also use a keyframe animation and $animateCss will make it work alongside the transition &#42;/
- * .pulse-twice {
- *   animation: 0.5s pulse linear 2;
- *   -webkit-animation: 0.5s pulse linear 2;
- * }
- *
- * @keyframes pulse {
- *   from { transform: scale(0.5); }
- *   to { transform: scale(1.5); }
- * }
- *
- * @-webkit-keyframes pulse {
- *   from { -webkit-transform: scale(0.5); }
- *   to { -webkit-transform: scale(1.5); }
- * }
- * ```
- *
- * Given this complex combination of CSS classes, styles and options, `$animateCss` will figure everything out and make the animation happen.
- *
- * ## How the Options are handled
- *
- * `$animateCss` is very versatile and intelligent when it comes to figuring out what configurations to apply to the element to ensure the animation
- * works with the options provided. Say for example we were adding a class that contained a keyframe value and we wanted to also animate some inline
- * styles using the `from` and `to` properties.
- *
- * ```js
- * let animator = $animateCss(element, {
- *   from: { background:'red' },
- *   to: { background:'blue' }
- * });
- * animator.start();
- * ```
- *
- * ```css
- * .rotating-animation {
- *   animation:0.5s rotate linear;
- *   -webkit-animation:0.5s rotate linear;
- * }
- *
- * @keyframes rotate {
- *   from { transform: rotate(0deg); }
- *   to { transform: rotate(360deg); }
- * }
- *
- * @-webkit-keyframes rotate {
- *   from { -webkit-transform: rotate(0deg); }
- *   to { -webkit-transform: rotate(360deg); }
- * }
- * ```
- *
- * The missing pieces here are that we do not have a transition set (within the CSS code nor within the `$animateCss` options) and the duration of the animation is
- * going to be detected from what the keyframe styles on the CSS class are. In this event, `$animateCss` will automatically create an inline transition
- * style matching the duration detected from the keyframe style (which is present in the CSS class that is being added) and then prepare both the transition
- * and keyframe animations to run in parallel on the element. Then when the animation is underway the provided `from` and `to` CSS styles will be applied
- * and spread across the transition and keyframe animation.
- *
- * ## What is returned
- *
- * `$animateCss` works in two stages: a preparation phase and an animation phase. Therefore when `$animateCss` is first called it will NOT actually
- * start the animation. All that is going on here is that the element is being prepared for the animation (which means that the generated CSS classes are
- * added and removed on the element). Once `$animateCss` is called it will return an object with the following properties:
- *
- * ```js
- * let animator = $animateCss(element, { ... });
- * ```
- *
- * Now what do the contents of our `animator` variable look like:
- *
- * ```js
- * {
- *   // starts the animation
- *   start: Function,
- *
- *   // ends (aborts) the animation
- *   end: Function
- * }
- * ```
- *
- * To actually start the animation we need to run `animation.start()` which will then return a promise that we can hook into to detect when the animation ends.
- * If we choose not to run the animation then we MUST run `animation.end()` to perform a cleanup on the element (since some CSS classes and styles may have been
- * applied to the element during the preparation phase). Note that all other properties such as duration, delay, transitions and keyframes are just properties
- * and that changing them will not reconfigure the parameters of the animation.
- *
- * ### runner.done() vs runner.then()
- * It is documented that `animation.start()` will return a promise object and this is true, however, there is also an additional method available on the
- * runner called `.done(callbackFn)`. The done method works the same as `.finally(callbackFn)`, however, it does **not trigger a digest to occur**.
- * Therefore, for performance reasons, it's always best to use `runner.done(callback)` instead of `runner.then()`, `runner.catch()` or `runner.finally()`
- * unless you really need a digest to kick off afterwards.
- *
- * Keep in mind that, to make this easier, ngAnimate has tweaked the JS animations API to recognize when a runner instance is returned from $animateCss
- * (so there is no need to call `runner.done(doneFn)` inside of your JavaScript animation code).
- * Check the {@link ngAnimate.$animateCss#usage animation code above} to see how this works.
- *
- * @param {Element} element the element that will be animated
- * @param {object} options the animation-related options that will be applied during the animation
- *
- * * `event` - The DOM event (e.g. enter, leave, move). When used, a generated CSS class of `ng-EVENT` and `ng-EVENT-active` will be applied
- * to the element during the animation. Multiple events can be provided when spaces are used as a separator. (Note that this will not perform any DOM operation.)
- * * `structural` - Indicates that the `ng-` prefix will be added to the event class. Setting to `false` or omitting will turn `ng-EVENT` and
- * `ng-EVENT-active` in `EVENT` and `EVENT-active`. Unused if `event` is omitted.
- * * `easing` - The CSS easing value that will be applied to the transition or keyframe animation (or both).
- * * `transitionStyle` - The raw CSS transition style that will be used (e.g. `1s linear all`).
- * * `keyframeStyle` - The raw CSS keyframe animation style that will be used (e.g. `1s my_animation linear`).
- * * `from` - The starting CSS styles (a key/value object) that will be applied at the start of the animation.
- * * `to` - The ending CSS styles (a key/value object) that will be applied across the animation via a CSS transition.
- * * `addClass` - A space separated list of CSS classes that will be added to the element and spread across the animation.
- * * `removeClass` - A space separated list of CSS classes that will be removed from the element and spread across the animation.
- * * `duration` - A number value representing the total duration of the transition and/or keyframe (note that a value of 1 is 1000ms). If a value of `0`
- * is provided then the animation will be skipped entirely.
- * * `delay` - A number value representing the total delay of the transition and/or keyframe (note that a value of 1 is 1000ms). If a value of `true` is
- * used then whatever delay value is detected from the CSS classes will be mirrored on the elements styles (e.g. by setting delay true then the style value
- * of the element will be `transition-delay: DETECTED_VALUE`). Using `true` is useful when you want the CSS classes and inline styles to all share the same
- * CSS delay value.
- * * `stagger` - A numeric time value representing the delay between successively animated elements
- * ({@link ngAnimate#css-staggering-animations Click here to learn how CSS-based staggering works in ngAnimate.})
- * * `staggerIndex` - The numeric index representing the stagger item (e.g. a value of 5 is equal to the sixth item in the stagger; therefore when a
- *   `stagger` option value of `0.1` is used then there will be a stagger delay of `600ms`)
- * * `applyClassesEarly` - Whether or not the classes being added or removed will be used when detecting the animation. This is set by `$animate` when enter/leave/move animations are fired to ensure that the CSS classes are resolved in time. (Note that this will prevent any transitions from occurring on the classes being added and removed.)
- * * `cleanupStyles` - Whether or not the provided `from` and `to` styles will be removed once
- *    the animation is closed. This is useful for when the styles are used purely for the sake of
- *    the animation and do not have a lasting visual effect on the element (e.g. a collapse and open animation).
- *    By default this value is set to `false`.
- *
- * @return {object} an object with start and end methods and details about the animation.
- *
- * * `start` - The method to start the animation. This will return a `Promise` when called.
- * * `end` - This method will cancel the animation and remove all applied CSS classes and styles.
- */
 const ONE_SECOND = 1000;
 
 const ELAPSED_TIME_MAX_DECIMAL_PLACES = 3;
@@ -654,7 +440,7 @@ export const $AnimateCssProvider = [
           // that if there is no transition defined then nothing will happen and this will also allow
           // other transitions to be stacked on top of each other without any chopping them out.
           if (isFirst && !options.skipBlocking) {
-            helpers.blockTransitions(node, SAFE_FAST_FORWARD_DURATION_VALUE);
+            blockTransitions(node, SAFE_FAST_FORWARD_DURATION_VALUE);
           }
 
           let timings = computeTimings(
@@ -765,7 +551,7 @@ export const $AnimateCssProvider = [
           if (flags.blockTransition || flags.blockKeyframeAnimation) {
             applyBlocking(maxDuration);
           } else if (!options.skipBlocking) {
-            helpers.blockTransitions(node, false);
+            blockTransitions(node, false);
           }
 
           // TODO(matsko): for 1.5 change this code to have an animator object for better debugging
@@ -823,7 +609,7 @@ export const $AnimateCssProvider = [
             }
 
             blockKeyframeAnimations(node, false);
-            helpers.blockTransitions(node, false);
+            blockTransitions(node, false);
 
             forEach(temporaryStyles, (entry) => {
               // There is only one way to remove inline style properties entirely from elements.
@@ -874,7 +660,7 @@ export const $AnimateCssProvider = [
 
           function applyBlocking(duration) {
             if (flags.blockTransition) {
-              helpers.blockTransitions(node, duration);
+              blockTransitions(node, duration);
             }
 
             if (flags.blockKeyframeAnimation) {
@@ -1136,3 +922,12 @@ export const $AnimateCssProvider = [
     ];
   },
 ];
+
+function blockTransitions(node, duration) {
+  // we use a negative delay value since it performs blocking
+  // yet it doesn't kill any existing transitions running on the
+  // same element which makes this safe for class-based animations
+  const value = duration ? `-${duration}s` : "";
+  applyInlineStyle(node, [TRANSITION_DELAY_PROP, value]);
+  return [TRANSITION_DELAY_PROP, value];
+}

package/src/animations/animate.css.md

@@ -0,0 +1,263 @@
+/\*\*
+
+- @ngdoc service
+- @name $animateCss
+- @kind object
+-
+- @description
+- The `$animateCss` service is a useful utility to trigger customized CSS-based transitions/keyframes
+- from a JavaScript-based animation or directly from a directive. The purpose of `$animateCss` is NOT
+- to side-step how `$animate` and ngAnimate work, but the goal is to allow pre-existing animations or
+- directives to create more complex animations that can be purely driven using CSS code.
+-
+- Note that only browsers that support CSS transitions and/or keyframe animations are capable of
+- rendering animations triggered via `$animateCss` (bad news for IE9 and lower).
+-
+- ## General Use
+- Once again, `$animateCss` is designed to be used inside of a registered JavaScript animation that
+- is powered by ngAnimate. It is possible to use `$animateCss` directly inside of a directive, however,
+- any automatic control over cancelling animations and/or preventing animations from being run on
+- child elements will not be handled by AngularJS. For this to work as expected, please use `$animate` to
+- trigger the animation and then setup a JavaScript animation that injects `$animateCss` to trigger
+- the CSS animation.
+-
+- The example below shows how we can create a folding animation on an element using `ng-if`:
+-
+- ```html
+
+  ```
+
+- <!-- notice the `fold-animation` CSS class -->
+- <div ng-if="onOff" class="fold-animation">
+- This element will go BOOM
+- </div>
+- <button ng-click="onOff=true">Fold In</button>
+- ```
+
+  ```
+
+-
+- Now we create the **JavaScript animation** that will trigger the CSS transition:
+-
+- ```js
+
+  ```
+
+- ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
+- return {
+-     enter: function(element, doneFn) {
+-       let height = element[0].offsetHeight;
+-       return $animateCss(element, {
+-         from: { height:'0px' },
+-         to: { height:height + 'px' },
+-         duration: 1 // one second
+-       });
+-     }
+- }
+- }]);
+- ```
+
+  ```
+
+-
+- ## More Advanced Uses
+-
+- `$animateCss` is the underlying code that ngAnimate uses to power **CSS-based animations** behind the scenes. Therefore CSS hooks
+- like `.ng-EVENT`, `.ng-EVENT-active`, `.ng-EVENT-stagger` are all features that can be triggered using `$animateCss` via JavaScript code.
+-
+- This also means that just about any combination of adding classes, removing classes, setting styles, dynamically setting a keyframe animation,
+- applying a hardcoded duration or delay value, changing the animation easing or applying a stagger animation are all options that work with
+- `$animateCss`. The service itself is smart enough to figure out the combination of options and examine the element styling properties in order
+- to provide a working animation that will run in CSS.
+-
+- The example below showcases a more advanced version of the `.fold-animation` from the example above:
+-
+- ```js
+
+  ```
+
+- ngModule.animation('.fold-animation', ['$animateCss', function($animateCss) {
+- return {
+-     enter: function(element, doneFn) {
+-       let height = element[0].offsetHeight;
+-       return $animateCss(element, {
+-         addClass: 'red large-text pulse-twice',
+-         easing: 'ease-out',
+-         from: { height:'0px' },
+-         to: { height:height + 'px' },
+-         duration: 1 // one second
+-       });
+-     }
+- }
+- }]);
+- ```
+
+  ```
+
+-
+- Since we're adding/removing CSS classes then the CSS transition will also pick those up:
+-
+- ```css
+
+  ```
+
+- /\* since a hardcoded duration value of 1 was provided in the JavaScript animation code,
+- the CSS classes below will be transitioned despite them being defined as regular CSS classes \*/
+- .red { background:red; }
+- .large-text { font-size:20px; }
+-
+- /\* we can also use a keyframe animation and $animateCss will make it work alongside the transition \*/
+- .pulse-twice {
+- animation: 0.5s pulse linear 2;
+- -webkit-animation: 0.5s pulse linear 2;
+- }
+-
+- @keyframes pulse {
+- from { transform: scale(0.5); }
+- to { transform: scale(1.5); }
+- }
+-
+- @-webkit-keyframes pulse {
+- from { -webkit-transform: scale(0.5); }
+- to { -webkit-transform: scale(1.5); }
+- }
+- ```
+
+  ```
+
+-
+- Given this complex combination of CSS classes, styles and options, `$animateCss` will figure everything out and make the animation happen.
+-
+- ## How the Options are handled
+-
+- `$animateCss` is very versatile and intelligent when it comes to figuring out what configurations to apply to the element to ensure the animation
+- works with the options provided. Say for example we were adding a class that contained a keyframe value and we wanted to also animate some inline
+- styles using the `from` and `to` properties.
+-
+- ```js
+
+  ```
+
+- let animator = $animateCss(element, {
+- from: { background:'red' },
+- to: { background:'blue' }
+- });
+- animator.start();
+- ```
+
+  ```
+
+-
+- ```css
+
+  ```
+
+- .rotating-animation {
+- animation:0.5s rotate linear;
+- -webkit-animation:0.5s rotate linear;
+- }
+-
+- @keyframes rotate {
+- from { transform: rotate(0deg); }
+- to { transform: rotate(360deg); }
+- }
+-
+- @-webkit-keyframes rotate {
+- from { -webkit-transform: rotate(0deg); }
+- to { -webkit-transform: rotate(360deg); }
+- }
+- ```
+
+  ```
+
+-
+- The missing pieces here are that we do not have a transition set (within the CSS code nor within the `$animateCss` options) and the duration of the animation is
+- going to be detected from what the keyframe styles on the CSS class are. In this event, `$animateCss` will automatically create an inline transition
+- style matching the duration detected from the keyframe style (which is present in the CSS class that is being added) and then prepare both the transition
+- and keyframe animations to run in parallel on the element. Then when the animation is underway the provided `from` and `to` CSS styles will be applied
+- and spread across the transition and keyframe animation.
+-
+- ## What is returned
+-
+- `$animateCss` works in two stages: a preparation phase and an animation phase. Therefore when `$animateCss` is first called it will NOT actually
+- start the animation. All that is going on here is that the element is being prepared for the animation (which means that the generated CSS classes are
+- added and removed on the element). Once `$animateCss` is called it will return an object with the following properties:
+-
+- ```js
+
+  ```
+
+- let animator = $animateCss(element, { ... });
+- ```
+
+  ```
+
+-
+- Now what do the contents of our `animator` variable look like:
+-
+- ```js
+
+  ```
+
+- {
+- // starts the animation
+- start: Function,
+-
+- // ends (aborts) the animation
+- end: Function
+- }
+- ```
+
+  ```
+
+-
+- To actually start the animation we need to run `animation.start()` which will then return a promise that we can hook into to detect when the animation ends.
+- If we choose not to run the animation then we MUST run `animation.end()` to perform a cleanup on the element (since some CSS classes and styles may have been
+- applied to the element during the preparation phase). Note that all other properties such as duration, delay, transitions and keyframes are just properties
+- and that changing them will not reconfigure the parameters of the animation.
+-
+- ### runner.done() vs runner.then()
+- It is documented that `animation.start()` will return a promise object and this is true, however, there is also an additional method available on the
+- runner called `.done(callbackFn)`. The done method works the same as `.finally(callbackFn)`, however, it does **not trigger a digest to occur**.
+- Therefore, for performance reasons, it's always best to use `runner.done(callback)` instead of `runner.then()`, `runner.catch()` or `runner.finally()`
+- unless you really need a digest to kick off afterwards.
+-
+- Keep in mind that, to make this easier, ngAnimate has tweaked the JS animations API to recognize when a runner instance is returned from $animateCss
+- (so there is no need to call `runner.done(doneFn)` inside of your JavaScript animation code).
+- Check the {@link ngAnimate.$animateCss#usage animation code above} to see how this works.
+-
+- @param {Element} element the element that will be animated
+- @param {object} options the animation-related options that will be applied during the animation
+-
+- - `event` - The DOM event (e.g. enter, leave, move). When used, a generated CSS class of `ng-EVENT` and `ng-EVENT-active` will be applied
+- to the element during the animation. Multiple events can be provided when spaces are used as a separator. (Note that this will not perform any DOM operation.)
+- - `structural` - Indicates that the `ng-` prefix will be added to the event class. Setting to `false` or omitting will turn `ng-EVENT` and
+- `ng-EVENT-active` in `EVENT` and `EVENT-active`. Unused if `event` is omitted.
+- - `easing` - The CSS easing value that will be applied to the transition or keyframe animation (or both).
+- - `transitionStyle` - The raw CSS transition style that will be used (e.g. `1s linear all`).
+- - `keyframeStyle` - The raw CSS keyframe animation style that will be used (e.g. `1s my_animation linear`).
+- - `from` - The starting CSS styles (a key/value object) that will be applied at the start of the animation.
+- - `to` - The ending CSS styles (a key/value object) that will be applied across the animation via a CSS transition.
+- - `addClass` - A space separated list of CSS classes that will be added to the element and spread across the animation.
+- - `removeClass` - A space separated list of CSS classes that will be removed from the element and spread across the animation.
+- - `duration` - A number value representing the total duration of the transition and/or keyframe (note that a value of 1 is 1000ms). If a value of `0`
+- is provided then the animation will be skipped entirely.
+- - `delay` - A number value representing the total delay of the transition and/or keyframe (note that a value of 1 is 1000ms). If a value of `true` is
+- used then whatever delay value is detected from the CSS classes will be mirrored on the elements styles (e.g. by setting delay true then the style value
+- of the element will be `transition-delay: DETECTED_VALUE`). Using `true` is useful when you want the CSS classes and inline styles to all share the same
+- CSS delay value.
+- - `stagger` - A numeric time value representing the delay between successively animated elements
+- ({@link ngAnimate#css-staggering-animations Click here to learn how CSS-based staggering works in ngAnimate.})
+- - `staggerIndex` - The numeric index representing the stagger item (e.g. a value of 5 is equal to the sixth item in the stagger; therefore when a
+- `stagger` option value of `0.1` is used then there will be a stagger delay of `600ms`)
+- - `applyClassesEarly` - Whether or not the classes being added or removed will be used when detecting the animation. This is set by `$animate` when enter/leave/move animations are fired to ensure that the CSS classes are resolved in time. (Note that this will prevent any transitions from occurring on the classes being added and removed.)
+- - `cleanupStyles` - Whether or not the provided `from` and `to` styles will be removed once
+- the animation is closed. This is useful for when the styles are used purely for the sake of
+- the animation and do not have a lasting visual effect on the element (e.g. a collapse and open animation).
+- By default this value is set to `false`.
+-
+- @return {object} an object with start and end methods and details about the animation.
+-
+- - `start` - The method to start the animation. This will return a `Promise` when called.
+- - `end` - This method will cancel the animation and remove all applied CSS classes and styles.
+    \*/