From 260b5e820f78c64d092446245a64e12a2f2ca932 Mon Sep 17 00:00:00 2001
From: "Jose A. Cabaneros" <joseacabaneros@gmail.com>
Date: Thu, 8 Aug 2024 12:18:35 +0200
Subject: [PATCH] fix(staggered-fade-and-slide): add element index in base-grid
 to retrieve in animation to animate reliably

---
 .../animations/staggered-fade-and-slide.vue   | 106 +++++++--------
 .../x-components/src/components/base-grid.vue | 127 +++++++-----------
 packages/x-components/src/views/home/Home.vue |   1 -
 3 files changed, 96 insertions(+), 138 deletions(-)

diff --git a/packages/x-components/src/components/animations/staggered-fade-and-slide.vue b/packages/x-components/src/components/animations/staggered-fade-and-slide.vue
index 17ba3c8743..ffed12e1f0 100644
--- a/packages/x-components/src/components/animations/staggered-fade-and-slide.vue
+++ b/packages/x-components/src/components/animations/staggered-fade-and-slide.vue
@@ -1,7 +1,8 @@
 <template>
   <TransitionGroup
-    @enter="enter"
-    @after-enter="afterEnter"
+    @enter="onEnter"
+    @afterEnter="onAfterEnter"
+    @leave="onLeave"
     :appear="appear"
     :name="name"
     :tag="tag"
@@ -13,6 +14,7 @@
 <script lang="ts">
   import { defineComponent, ref } from 'vue';
   import { useDisableAnimation } from './use-disable-animation';
+
   /**
    * Renders a transition group wrapping the elements passed in the default slot and animating
    * them with a staggered fade and slide animation.
@@ -22,94 +24,84 @@
   export default defineComponent({
     name: 'StaggeredFadeAndSlide',
     props: {
-      /**
-       * Indicates if the transition must be applied on the initial render of the node.
-       */
+      /** Indicates if the transition must be applied on the initial render of the node. */
       appear: {
         type: Boolean,
         default: true
       },
-      /**
-       * The tag of the node to render to the DOM.
-       */
+      /** The tag of the node to render to the DOM. */
       tag: {
         type: String,
         default: 'div'
       },
-      /**
-       * The time in ms to stagger each item.
-       */
+      /** The time in ms to stagger each item. */
       stagger: {
         type: Number,
         default: 25
       }
     },
     setup(props) {
-      /**
-       * The duration of the transition in ms.
-       */
+      /** The duration of the transition in ms. */
       const transitionDuration = 250;
-      /**
-       * The counter to keep track of the staggered delay.
-       */
+
+      /** The counter to keep track of the staggered delay. */
       const staggerCounter = ref(0);
+      /** The name of the animation. */
+      const { name } = useDisableAnimation('x-staggered-fade-and-slide');
+
       /**
-       * The counter to keep track of the animations.
-       */
-      const animationList = ref<HTMLElement[]>([]);
-      /**
-       * The name of the animation.
-       */
-      const animationName = ref('x-staggered-fade-and-slide');
-      /**
-       * The name of the animation.
-       */
-      const { name } = useDisableAnimation(animationName.value);
-      /**
-       * Calculate the delay for the next element.
+       * Listener called when one frame the element is inserted.
+       * This calculates the stagger delay to be used as `transitionDelay` and finally resolve
+       * the transition end after the CSS transition duration plus stagger delay.
        *
-       * @returns The delay in ms.
+       * @param el - Element inserted.
+       * @param done - Callback to indicate the transition end.
        */
-      function getNextTransitionDelay(): number {
-        return staggerCounter.value++ * props.stagger;
+      function onEnter(el: Element, done: () => void) {
+        const elIndex = +((el as HTMLElement).dataset.index ?? 0);
+        const staggerIndex = elIndex - staggerCounter.value;
+        const staggerDelay = staggerIndex * props.stagger;
+
+        (el as HTMLElement).style.transitionDelay = `${staggerDelay}ms`;
+        setTimeout(done, transitionDuration + staggerDelay);
       }
+
       /**
-       * The enter transition.
+       * Listener called when the enter transition has finished.
+       * This resets the `transitionDelay` and add one to the stagger counter.
        *
-       * @param el
-       * @param done
+       * @param el - Element inserted.
        */
-      function enter(el: HTMLElement, done: () => void) {
-        animationList.value.push(el);
-        const delay = getNextTransitionDelay();
-        el.style.transitionDelay = `${delay}ms`;
-        setTimeout(() => {
-          el.style.transitionDelay = '0ms';
-          done();
-        }, transitionDuration + delay);
+      function onAfterEnter(el: Element) {
+        (el as HTMLElement).style.transitionDelay = '0ms';
+        staggerCounter.value++;
       }
+
       /**
-       * The after enter transition.
+       * Listener called when the leave transition starts.
+       * This resets the stagger counter to 0 to init the staggered animation.
        *
-       * @param el
+       * @param _ - Element inserted.
+       * @param done - Callback to indicate the transition end.
        */
-      function afterEnter(el: HTMLElement) {
-        animationList.value = animationList.value.filter(item => item !== el);
-        if (animationList.value.length === 0) {
-          staggerCounter.value = 0;
-        }
+      function onLeave(_: Element, done: () => void) {
+        staggerCounter.value = 0;
+        done();
       }
+
       return {
         name,
-        enter,
-        afterEnter
+        onEnter,
+        onAfterEnter,
+        onLeave
       };
     }
   });
 </script>
 
 <style lang="scss">
-  $transition-duration: 0.25s;
+  $transition-duration: 250ms;
+
   /* 1. Declare transitions */
   .x-staggered-fade-and-slide-enter-active,
   .x-staggered-fade-and-slide-leave-active {
@@ -121,7 +113,7 @@
     transition: transform $transition-duration ease-out;
   }
 
-  /* 2. declare enter from and leave to state */
+  /* 2. Declare enter, from and leave to state */
   .x-staggered-fade-and-slide-enter,
   .x-staggered-fade-and-slide-enter-from,
   .x-staggered-fade-and-slide-leave-to {
@@ -129,8 +121,8 @@
     transform: translate3d(0, 50%, 0);
   }
 
-  /* 3. ensure leaving items are taken out of layout flow so that moving
-      animations can be calculated correctly. */
+  /* 3. Ensure leaving items are taken out of layout flow so that moving animations can be
+        calculated correctly. */
   .x-staggered-fade-and-slide-leave-active {
     position: absolute;
   }
diff --git a/packages/x-components/src/components/base-grid.vue b/packages/x-components/src/components/base-grid.vue
index c89abc01ea..7bc621710f 100644
--- a/packages/x-components/src/components/base-grid.vue
+++ b/packages/x-components/src/components/base-grid.vue
@@ -1,6 +1,7 @@
 <template>
   <component
     :is="animation"
+    ref="gridEl"
     :style="style"
     class="x-base-grid"
     :class="cssClasses"
@@ -8,8 +9,9 @@
     data-test="grid"
   >
     <li
-      v-for="{ slotName, item, cssClass } in gridItems"
+      v-for="({ item, cssClass, slotName }, index) in gridItems"
       :key="item.id"
+      :data-index="index"
       :class="cssClass"
       class="x-base-grid__item"
     >
@@ -33,7 +35,6 @@
   import {
     computed,
     defineComponent,
-    getCurrentInstance,
     inject,
     onBeforeUnmount,
     onMounted,
@@ -42,7 +43,11 @@
     ref,
     watch
   } from 'vue';
-  import { MaybeComputedElementRef, useResizeObserver } from '@vueuse/core';
+  import {
+    MaybeComputedElementRef,
+    useResizeObserver,
+    UseResizeObserverReturn
+  } from '@vueuse/core';
   import { toKebabCase } from '../utils/string';
   import { ListItem, VueCSSClasses } from '../utils/types';
   import { AnimationProp } from '../types/animation-prop';
@@ -52,8 +57,6 @@
   /**
    * The type returned by the gridItems function. Basically it's a list of items with its CSS
    * classes and a slotName.
-   *
-   * @internal
    */
   interface GridItem {
     slotName: string;
@@ -74,11 +77,7 @@
   export default defineComponent({
     name: 'BaseGrid',
     props: {
-      /**
-       * Animation component that will be used to animate the base grid.
-       *
-       * @public
-       */
+      /** Animation component that will be used to animate the base grid. */
       animation: {
         type: AnimationProp,
         default: 'ul'
@@ -86,8 +85,6 @@
       /**
        * Number of columns the grid is divided into. By default, its value is 0, setting the grid
        * columns mode to auto-fill.
-       *
-       * @public
        */
       columns: {
         type: Number,
@@ -96,45 +93,27 @@
       /**
        * The list of items to be rendered.
        *
-       * @remarks The items must have an id property.
-       *
-       * @public
+       * @remarks The items must have an ID property.
        */
       items: {
         type: Array as PropType<ListItem[]>
       }
     },
     setup(props, { slots }) {
+      type ElementRef = {
+        $el: HTMLElement;
+      };
+
       const xBus = useXBus();
 
-      /**
-       * Number of columns rendered inside the grid.
-       */
-      const renderedColumnsNumber = ref(0);
-      /**
-       * Reference to the root element of the grid.
-       */
-      const rootEl = ref<HTMLElement | undefined>();
-      /**
-       * ResizeObserver instance to keep track of the number of columns rendered inside the grid.
-       */
-      let resizeObserver: { stop: () => void };
-
-      /**
-       * It injects {@link ListItem} provided by an ancestor.
-       *
-       * @internal
-       */
-      const injectedListItems = inject<Ref<ListItem[]> | undefined>(
-        LIST_ITEMS_KEY as string,
-        undefined
-      );
+      /** It injects {@link ListItem} provided by an ancestor. */
+      const injectedListItems = inject<Ref<ListItem[]>>(LIST_ITEMS_KEY as string);
+      const gridEl = ref<ElementRef | HTMLElement>();
+      let renderedColumnsNumber = ref(0);
 
       /**
        * Emits the {@link XEventsTypes.RenderedColumnsNumberChanged}
        * event whenever the number of columns rendered inside the grid changes.
-       *
-       * @internal
        */
       watch(
         renderedColumnsNumber,
@@ -146,10 +125,8 @@
        * It returns the items passed as props or the injected ones.
        *
        * @returns List of grid items.
-       *
-       * @public
        */
-      const computedItems = computed((): ListItem[] | void => {
+      const computedItems = computed<ListItem[] | void>(() => {
         return (
           props.items ??
           injectedListItems?.value ??
@@ -164,38 +141,27 @@
        * amount of columns or rows based on how many columns the grid is divided into.
        *
        * @returns CSS class with the column property value.
-       *
-       * @internal
        */
-      const cssClasses = computed(
-        (): VueCSSClasses =>
-          props.columns ? `x-base-grid--cols-${props.columns}` : 'x-base-grid--cols-auto'
-      );
+      const cssClasses = computed(() => `x-base-grid--cols-${props.columns || 'auto'}`);
 
       /**
        * CSSStyleDeclaration object specifying the number of columns the grid is divided into based on
        * the column property value.
        *
        * @returns A CSSStyleDeclaration to use as the style attribute.
-       *
-       * @internal
        */
-      const style = computed((): Partial<CSSStyleDeclaration> => {
-        return {
-          gridTemplateColumns: props.columns
-            ? `repeat(${props.columns}, minmax(0, 1fr))`
-            : 'repeat(auto-fill, minmax(var(--x-size-min-width-grid-item, 150px), 1fr))'
-        };
-      });
+      const style = computed<Partial<CSSStyleDeclaration>>(() => ({
+        gridTemplateColumns: props.columns
+          ? `repeat(${props.columns}, minmax(0, 1fr))`
+          : 'repeat(auto-fill, minmax(var(--x-size-min-width-grid-item, 150px), 1fr))'
+      }));
 
       /**
        * Maps the item to an object containing: the `item`, its `CSS class` and its slot name.
        *
        * @returns An array of objects containing the item and its CSS class.
-       *
-       * @internal
        */
-      const gridItems = computed((): GridItem[] =>
+      const gridItems = computed<GridItem[]>(() =>
         (computedItems.value as ListItem[]).map(item => {
           const slotName = toKebabCase(item.modelName);
           return {
@@ -207,37 +173,38 @@
       );
 
       /**
-       * Updates the number of columns rendered inside the grid.
+       * Checks if a given value is an `ElementRef` object.
+       *
+       * @param value - The value to check.
+       * @returns `true` if the value is an `ElementRef` object, `false` otherwise.
        */
-      const updateRenderedColumnsNumber = (): void => {
-        if (rootEl.value) {
-          const { gridTemplateColumns } = getComputedStyle(rootEl.value);
-          renderedColumnsNumber.value = gridTemplateColumns.split(' ').length;
-        }
+      const isElementRef = (value: any): value is ElementRef => {
+        return value && value.$el instanceof HTMLElement;
       };
 
-      /**
-       * Initialises the rendered columns number and sets a ResizeObserver to keep it updated.
-       */
+      /** Updates the number of columns rendered inside the grid. */
+      function updateRenderedColumnsNumber() {
+        const { gridTemplateColumns } = getComputedStyle(
+          isElementRef(gridEl.value) ? gridEl.value.$el : (gridEl.value as Element)
+        );
+        renderedColumnsNumber.value = gridTemplateColumns.split(' ').length;
+      }
+
+      /** Initialises the rendered columns number and sets a ResizeObserver to keep it updated. */
+      let resizeObserver: UseResizeObserverReturn;
       onMounted(() => {
-        rootEl.value = getCurrentInstance()?.proxy?.$el as HTMLElement | undefined;
-        if (rootEl.value) {
-          resizeObserver = useResizeObserver(
-            rootEl as MaybeComputedElementRef,
-            updateRenderedColumnsNumber
-          );
-        }
+        resizeObserver = useResizeObserver(
+          gridEl as MaybeComputedElementRef,
+          updateRenderedColumnsNumber
+        );
       });
-
-      /**
-       * Stops the ResizeObserver when the component is unmounted.
-       */
       onBeforeUnmount(() => resizeObserver?.stop());
 
       return {
         gridItems,
         cssClasses,
         style,
+        gridEl,
         slots
       };
     }
diff --git a/packages/x-components/src/views/home/Home.vue b/packages/x-components/src/views/home/Home.vue
index d0b31b0ff0..5e97b3c6e9 100644
--- a/packages/x-components/src/views/home/Home.vue
+++ b/packages/x-components/src/views/home/Home.vue
@@ -590,7 +590,6 @@
       SortPickerList,
       Spellcheck,
       SpellcheckButton,
-      StaggeredFadeAndSlide,
       Tagging,
       UrlHandler
     },