feat: merge new features from 'feat' branch

Author: igorMSoares

js-css-animations/animate.js

@@ -19,6 +19,62 @@ import {
 
 import { setParentMaxMeasures } from './measurements.js';
 
+/**
+ * Contains the default value for each custom option.
+ * Those values can be overwritten by the user by calling jsCssAnimations.config()
+ * and passing new default values for all the animations.
+ * @type {Object.<string,any>}
+ */
+const configurations = {
+  default: Object.freeze({
+    trigger: `.${CLASS_NAMES.trigger}`,
+    targetSelector: undefined,
+    staggerDelay: undefined,
+    start: undefined,
+    complete: undefined,
+    keepSpace: false,
+    dimensionsTransition: true,
+    widthTransition: undefined,
+    heightTransition: undefined,
+    overflowHidden: true,
+  }),
+};
+
+/**
+ * ProxyHandler passed to the 'CONFIG' object to ensure that
+ * if an option is not customized by the user, the default value set
+ * in 'configurations.default' will be returned instead.
+ * @see {@link CONFIG}
+ * @see {@link configurations}
+ */
+const configHandler = {
+  /**
+   * @param {Object.<string, Function>} configurations - Contains the configuration options
+   * @param {string} option - Key name of the configuration option
+   */
+  get(configurations, option) {
+    if (!(option in configurations)) return configurations.default[option];
+    else return configurations[option];
+  },
+  /**
+   * @param {Object.<string, Function>} configurations - Contains the configuration options
+   * @param {string} option - Key name of the configuration option
+   * @param {any} value - Configuration option value
+   */
+  set(configurations, option, value) {
+    configurations[option] = value;
+    return true;
+  },
+};
+
+/**
+ * Object that handles configurations, either customized by the user
+ * or default values defined in 'configurations.default' object
+ * @type {Object.<string,any>}
+ * @see {@link configurations}
+ */
+const CONFIG = new Proxy(configurations, configHandler);
+
 /** Matches duration or delay CSS properties values */
 const DURATION_REGEX = Object.freeze(new RegExp(/(\d?\.\d+|\d+)(ms|s)?/));
 
@@ -40,14 +96,14 @@ const CALLBACK_TRACKER = Object.freeze({
    * Initiates the tracker
    * @param {string} trigger - A CSS selector representing the element which triggered the animation
    */
-  init: function(trigger) {
+  init: function (trigger) {
     CALLBACK_TRACKER.executing[trigger] = {};
   },
   /**
    * Removes 'trigger' from the tracker
    * @param {string} trigger - A CSS selector representing the element which triggered the animation
    */
-  remove: function(trigger) {
+  remove: function (trigger) {
     delete this.executing[trigger];
   },
 });
@@ -64,15 +120,15 @@ const TARGETS_STACK = {
    * @param {HTMLElement} elem - Element being animated
    * @param {string} trigger - CSS selector for the element that triggered the animation
    */
-  add: function(elem, trigger) {
+  add: function (elem, trigger) {
     if (!(trigger in this.stack)) this.stack[trigger] = [];
     this.stack[trigger].push(elem);
   },
   /**
    * Removes from the stack all the elements animated by the same trigger button
    * @param {string} trigger - CSS selector for the element that triggered the animation
    */
-  remove: function(trigger) {
+  remove: function (trigger) {
     if (!(trigger in this.stack)) return;
     delete this.stack[trigger];
   },
@@ -81,7 +137,7 @@ const TARGETS_STACK = {
    * @param {string} trigger - CSS selector for the element that triggered the animation
    * @returns An array of elements that have been animated by the same trigger button
    */
-  get: function(trigger) {
+  get: function (trigger) {
     if (!(trigger in this.stack)) return;
     return this.stack[trigger];
   },
@@ -98,6 +154,31 @@ export const removeCustomCssProperties = element => {
   });
 };
 
+/**
+ * Customize the default animations configurations by overwriting
+ * the 'CONFIG' values
+ * @param {Object} opts - All the options customized by the user
+ * @see {@link CONFIG}
+ */
+const updateDefaultConfig = opts => {
+  for (let option in CONFIG.default) {
+    if (opts[option] !== undefined) {
+      CONFIG[option] = opts[option];
+    }
+  }
+};
+
+/**
+ * Reset the configurations to its default values
+ * by removing from 'CONFIG' all options customized by the user
+ * @see {@link CONFIG}
+ */
+const resetDefaultConfig = () => {
+  for (let option in CONFIG.default) {
+    delete CONFIG[option];
+  }
+};
+
 /**
  * Sets an inline CSS property
  * @param {HTMLElement} element - The DOM element which will receive the property
@@ -116,7 +197,7 @@ export const setCssProperty = (element, property, value) => {
  */
 const updateCssProperties = (element, opts) => {
   removeCustomCssProperties(element);
-  removeInlineTransition(element);
+  if (element !== document.documentElement) removeInlineTransition(element);
   CUSTOM_CSS_PROPERTIES.forEach(prop => {
     if (typeof opts[prop] === 'string' || typeof opts[prop] === 'number') {
       if (typeof opts[prop] === 'number') {
@@ -328,13 +409,15 @@ const animate = (element, action, id, opts = {}) => {
   const {
     animType,
     trigger,
-    start,
-    complete,
-    keepSpace,
-    dimensionsTransition = keepSpace || isMotion(animType) ? false : true,
-    widthTransition = dimensionsTransition,
-    heightTransition = dimensionsTransition,
-    overflowHidden = true,
+    start = CONFIG.start,
+    complete = CONFIG.complete,
+    keepSpace = CONFIG.keepSpace,
+    dimensionsTransition = keepSpace || isMotion(animType)
+      ? false
+      : CONFIG.dimensionsTransition,
+    widthTransition = CONFIG.widthTransition ?? dimensionsTransition,
+    heightTransition = CONFIG.heightTransition ?? dimensionsTransition,
+    overflowHidden = CONFIG.overflowHidden,
   } = opts;
   const { duration, delay } = getTotalAnimTime(element);
   const OPPOSITE_ACTION = Object.freeze({
@@ -487,7 +570,9 @@ const preset = (el, args) => {
  */
 const eventHandler = (el, animationId, opts) => {
   return (/** @type {Event} */ e) => {
-    e.stopPropagation();
+    const { stopPropagation = true, preventDefault = true } = opts;
+    if (stopPropagation) e.stopPropagation();
+    if (preventDefault) e.preventDefault();
 
     const action = getAction(el, opts.animType);
     if (!action)
@@ -513,7 +598,11 @@ const eventHandler = (el, animationId, opts) => {
  * @see {@link module:globals.MOTION_ANIMS_ID}
  */
 const init = (animationId, opts = {}, eventType = 'click') => {
-  const { trigger = `.${CLASS_NAMES.trigger}`, targetSelector, cursor } = opts;
+  const {
+    trigger = CONFIG.trigger,
+    targetSelector = CONFIG.targetSelector,
+    cursor,
+  } = opts;
 
   document.querySelectorAll(trigger).forEach(btn => {
     btn.classList.add(CLASS_NAMES.btnCursor);
@@ -540,4 +629,12 @@ const init = (animationId, opts = {}, eventType = 'click') => {
   });
 };
 
-export { init, animate, preset, isEnabled };
+export {
+  init,
+  animate,
+  preset,
+  isEnabled,
+  updateCssProperties,
+  updateDefaultConfig,
+  resetDefaultConfig,
+};

js-css-animations/js-animations.css

@@ -158,13 +158,17 @@
 }
 
 :root {
+  --js-css-animation--cursor: pointer;
   --js-css-animation--duration: 800ms;
   --js-css-animation--timing-function: cubic-bezier(0.455, 0.03, 0.515, 0.955);
   --js-css-animation--delay: 0ms;
   --js-css-animation--fill-mode: both;
   --js-css-animation--blur: 0.5px;
   --js-css-animation--direction: normal;
   --js-css-animation--iteration: 1;
+  --js-css-animation--transf-origin: 'center';
+  --js-css-animation--initial-scale: 1;
+  --js-css-animation--final-scale: 1;
 }
 
 .js-anim--dimensions-transitions {
@@ -216,7 +220,6 @@
 .js-anim--rotate-left,
 .js-anim--rotate-left__ccw,
 .js-anim--rotate {
-  --js-css-animation--transf-origin: 'center';
   transform: rotate(var(--js-css-animation--rotation-angle));
   transform-origin: var(--js-css-animation--transf-origin);
   transition-property: transform;
@@ -272,15 +275,11 @@
   --js-css-animation--rotation-angle: 0deg;
   --js-css-animation--iteration: infinite;
   --js-css-animation--direction: alternate;
-  --js-css-animation--transf-origin: 'center';
   animation-name: js-anim--rotation-loop;
 }
 
 .js-anim--scale,
 .js-anim--scale__back {
-  --js-css-animation--transf-origin: 'center';
-  --js-css-animation--initial-scale: 1;
-  --js-css-animation--final-scale: 1;
   transform-origin: var(--js-css-animation--transf-origin);
 }
 
@@ -354,7 +353,6 @@
 }
 
 .js-anim--btn-cursor {
-  --js-css-animation--cursor: pointer;
   cursor: var(--js-css-animation--cursor);
 }
 

js-css-animations/js-css-animations.js

@@ -2,7 +2,17 @@
  * Builds the animation API that will be exported to the final user
  * @module js-css-animations
  */
-import { init, animate, preset, isEnabled } from './animate.js';
+import {
+  init,
+  animate,
+  preset,
+  isEnabled,
+  updateCssProperties,
+  setCssProperty,
+  updateDefaultConfig,
+  resetDefaultConfig,
+} from './animate.js';
+
 import { VISIBILITY_ANIMS_ID, MOTION_ANIMS_ID } from './globals.js';
 
 /**
@@ -51,6 +61,29 @@ const getTargets = selector => {
     : selectAllElements(selector);
 };
 
+/**
+ * Default values used by all animations are set by the user by
+ * overriding default animations properties and options
+ * @param {Object} opts - All custom animation properties and options.
+ * @see {@link module:globals.PROPERTY_NAMES}
+ * @see {@link module:animate.configurations.default}
+ */
+const config = opts => {
+  updateDefaultConfig(opts);
+  updateCssProperties(document.documentElement, opts);
+  if (opts.cursor)
+    setCssProperty(document.documentElement, 'cursor', opts.cursor);
+};
+
+/**
+ * Resets default animations values by
+ * removing default values customized by the user
+ */
+const reset = () => {
+  config({});
+  resetDefaultConfig();
+};
+
 /**
  * Toggles between two animations.
  *
@@ -134,7 +167,7 @@ const toggle = (selector, animA, animB, opts = {}) => {
  * @see {@link module:globals.MOTION_ANIMS_ID}
  * @type {Object}
  */
-const animationFunctions = (function() {
+const animationFunctions = (function () {
   const handlers = {};
   ['show', 'hide', 'move'].forEach(action => {
     const { animIds, animType } =
@@ -176,6 +209,23 @@ const animationFunctions = (function() {
       }
     }
   });
+  const blink = (target, opts = {}) => {
+    jsCssAnimations.show.fade(target, {
+      iteration: 'infinite',
+      direction: 'alternate',
+      ...opts,
+    });
+  };
+  const pulsate = (target, opts = {}) => {
+    jsCssAnimations.scale(target, {
+      finalScale: '1.2',
+      iteration: 'infinite',
+      direction: 'alternate',
+      ...opts,
+    });
+  };
+  handlers.blink = blink;
+  handlers.pulsate = pulsate;
   return handlers;
 })();
 
@@ -212,7 +262,7 @@ const eventBoundAnimations = (() => {
  * @param {HTMLElement|string} selector - An element or a valid CSS selector corresponding to the element
  * @returns True if the element was rotated from its original orientation. False if it maintains the original orientation.
  */
-const checkTransform = selector => {
+const isTransformed = selector => {
   const el = selectElement(selector);
   const transform = getComputedStyle(el).transform;
   return transform !== 'none' && transform !== 'matrix(1, 0, 0, 1, 0, 0)';
@@ -259,7 +309,7 @@ const verifyAnimationName = {
  * isTransformed(), isVisible() and isHidden()
  * @type {Object.<string, Function|Object>}
  */
-const jsCssAnimations = (function() {
+const jsCssAnimations = (function () {
   /**
    * Encapsulates eventBoundAnimations(), adding animation name validation
    * @see eventBoundAnimations
@@ -285,29 +335,14 @@ const jsCssAnimations = (function() {
     verifyAnimationName
   );
   const animationsHandler = Object.freeze({
+    config,
+    reset,
     init: eventAnimations,
     ...animationFunctions,
     show: showVisibilityAnim,
     hide: hideVisibilityAnim,
-    toggle: toggle,
-    blink: (target, opts = {}) => {
-      jsCssAnimations.show.fade(target, {
-        duration: '1s',
-        iteration: 'infinite',
-        direction: 'alternate',
-        ...opts,
-      });
-    },
-    pulsate: (target, opts = {}) => {
-      jsCssAnimations.scale(target, {
-        finalScale: '1.5',
-        duration: '1s',
-        iteration: 'infinite',
-        direction: 'reverse',
-        ...opts,
-      });
-    },
-    isTransformed: checkTransform,
+    toggle,
+    isTransformed,
     /**
      * @param {Element|string} selector - Dom element or a valid CSS selector
      * @returns True if the element is visible, False otherwise