@veritree/ui 0.66.1 → 0.67.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veritree/ui",
-  "version": "0.66.1",
+  "version": "0.67.0",
   "description": "veritree ui library",
   "type": "module",
   "main": "index.js",

package/src/components/Carousel/VTCarousel.vue

@@ -5,19 +5,56 @@
 </template>
 
 <script>
-let windowResizeTimeout = null;
-
 export default {
   name: 'VTCarousel',
 
+  /**
+   * Provides a Vue provide function that exposes a carousel API to child components.
+   * The API includes properties related to tracking and observing the carousel state,
+   * as well as methods for registering elements and handling observation events.
+   *
+   * @function
+   * @memberof YourComponent
+   * @name provide
+   * @returns {Object} The carousel API object containing properties and methods for child components.
+   */
   provide() {
+    /**
+     * Registers the provided element tracker with the component.
+     *
+     * @function
+     * @memberof CarouselAPI
+     * @name registerElTracker
+     * @param {Object} elTracker - The element tracker object containing dimensions and scroll properties.
+     * @returns {void}
+     * @private
+     */
+
+    /**
+     * Vue provide function that exposes the carousel API.
+     *
+     * @function
+     * @name apiCarousel
+     * @memberof YourComponent
+     * @returns {Object} The carousel API object.
+     */
     return {
       apiCarousel: () => {
+        /**
+         * Registers the provided element tracker with the component.
+         *
+         * @function
+         * @memberof CarouselAPI
+         * @name registerElTracker
+         * @param {Object} elTracker - The element tracker object containing dimensions and scroll properties.
+         * @returns {void}
+         */
         const registerElTracker = (elTracker) => {
           if (!elTracker) return;
           this.elTracker = elTracker;
         };
 
+        // Expose properties and methods for child components through the carousel API
         return {
           elTracker: this.elTracker,
           hasContentOverflow: this.hasContentOverflow,
@@ -25,7 +62,7 @@ export default {
           hasScrolledToLeftStart: this.hasScrolledToLeftStart,
           isLeftEndReached: this.isLeftEndReached,
           isLeftStartReached: this.isLeftStartReached,
-          onMutateTracker: this.onMutateTracker,
+          onObserveTracker: this.onObserveTracker,
           registerElTracker,
         };
       },
@@ -42,34 +79,59 @@ export default {
   },
 
   mounted() {
-    this.addEvents();
     this.hasContentOverflow = this.isContentOverflowing();
   },
 
   methods: {
-    addEvents() {
-      window.addEventListener('resize', this.onResizeWindow);
-    },
-
-    onResizeWindow() {
-      clearTimeout(windowResizeTimeout);
-
-      windowResizeTimeout = setTimeout(() => {
-        this.hasContentOverflow = this.isContentOverflowing();
-      }, 250);
-    },
-
-    onMutateTracker() {
+    /**
+     * Updates the state or performs actions based on observation events.
+     * This method is typically provided globally via Vue provide and is meant to be called
+     * in response to observation events (e.g., Resize Observer or Mutation Observer).
+     *
+     * Note: Ensure that the necessary state or methods (e.g., isContentOverflowing) are accessible
+     * in the context where this method is used.
+     *
+     * @function
+     * @memberof VTCarousel
+     * @name onObserveTracker
+     * @returns {void}
+     */
+    onObserveTracker() {
       this.hasContentOverflow = this.isContentOverflowing();
     },
 
     /**
-     * Checks if the scroll position is close to the left end of an element within a small margin.
+     * Determines whether the scroll position has reached the leftmost end of the container.
+     * Calculates the distance from the current scroll position to the left end and updates
+     * the 'hasScrolledToLeftEnd' property based on the calculated distance.
      *
-     * @returns {boolean} True if the scroll position is near the left end, otherwise false.
+     * @function
+     * @memberof VTCarousel
+     * @name isLeftEndReached
+     * @returns {void}
      */
     isLeftEndReached() {
+      /**
+       * Represents the tracking element's dimensions and scroll properties.
+       *
+       * @typedef {Object} ElTracker
+       * @property {number} offsetWidth - Width of the container element.
+       * @property {number} scrollLeft - Current scroll position from the left.
+       * @property {number} scrollWidth - Total width of the content within the container.
+       */
+
+      /**
+       * Object containing dimensions and scroll properties of the tracking element.
+       *
+       * @type {ElTracker}
+       */
       const { offsetWidth, scrollLeft, scrollWidth } = this.elTracker;
+
+      /**
+       * Calculated distance from the current scroll position to the left end.
+       *
+       * @type {number}
+       */
       const distanceToLeftEnd = Math.abs(
         scrollWidth - offsetWidth - scrollLeft
       );
@@ -79,20 +141,37 @@ export default {
     },
 
     /**
-     * Checks if the scroll position is at the leftmost starting point of an element.
+     * Determines whether the scroll position has reached the leftmost starting point of the container.
+     * Updates the 'hasScrolledToLeftStart' property based on whether the scroll position is at the beginning.
      *
-     * @returns {boolean} True if the scroll position is at the leftmost starting point, otherwise false.
+     * @function
+     * @memberof VTCarousel
+     * @name isLeftStartReached
+     * @returns {void}
      */
     isLeftStartReached() {
-      this.hasScrolledToLeftStart = this.elTracker.scrollLeft === 0;
+      /**
+       * Represents the tracking element's scroll position from the left.
+       *
+       * @type {scrollLeft}
+       */
+      const { scrollLeft } = this.elTracker;
+
+      // Update 'hasScrolledToLeftStart' based on whether the scroll position is at the beginning (0)
+      this.hasScrolledToLeftStart = scrollLeft === 0;
     },
 
     /**
-     * Checks if the content inside the carousel overflows horizontally.
+     * Determines whether the content within the tracked element is overflowing horizontally.
+     * It compares the offset width of the element with its scroll width.
      *
-     * @returns {boolean} True if the content overflows, false otherwise.
+     * @function
+     * @memberof VTCarousel
+     * @name isContentOverflowing
+     * @returns {boolean} True if the content is overflowing horizontally, otherwise false.
      */
     isContentOverflowing() {
+      // Compare the offset width with the scroll width to check for horizontal overflow
       return this.elTracker.offsetWidth !== this.elTracker.scrollWidth;
     },
   },

package/src/components/Carousel/VTCarouselTracker.vue

@@ -13,21 +13,37 @@ export default {
   data() {
     return {
       mutationObserver: null,
+      resizeObserver: null,
     };
   },
 
+  /**
+   * Lifecycle hook called before the component is destroyed.
+   * Removes event listeners and disconnects observers to prevent memory leaks.
+   *
+   * @function
+   * @memberof VTCarouselTracker
+   * @name beforeDestroy
+   * @returns {void}
+   */
   beforeDestroy() {
+    // Check if the component's root element exists
     if (!this.$el) {
       return;
     }
 
+    // Remove the 'scrollend' event listener
     this.$el.removeEventListener('scrollend', this.onScroll);
+
+    // Disconnect the Mutation Observer and Resize Observer to prevent memory leaks
     this.mutationObserver.disconnect(this.$el);
+    this.resizeObserver.disconnect(this.$el);
   },
 
   mounted() {
     this.registerElTracker();
     this.registerMutationObserver();
+    this.registerResizeObserver();
     this.addEventListeners();
   },
 
@@ -40,28 +56,91 @@ export default {
     },
 
     /**
-     * Sets up a MutationObserver to monitor changes within the current element
-     * and triggers the appropriate action in the parent carousel API when mutations occur.
+     * Initializes and registers a Resize Observer to monitor changes in the size of the current element.
+     * When a resize event is detected, it triggers the `onObserveTracker` method of the associated carousel API.
+     *
+     * @function
+     * @name registerResizeObserver
+     * @returns {void}
+     */
+    registerResizeObserver() {
+      /**
+       * Resize Observer callback function.
+       *
+       * @callback ResizeObserverCallback
+       * @param {Array<ResizeObserverEntry>} entries - An array of resize observer entries.
+       */
+
+      /**
+       * Resize Observer instance.
+       *
+       * @type {ResizeObserver}
+       */
+      this.resizeObserver = new ResizeObserver(() => {
+        this.apiCarousel().onObserveTracker();
+      });
+
+      // Start observing the current element's size changes
+      this.resizeObserver.observe(this.$el);
+    },
+
+    /**
+     * Initializes and registers a Mutation Observer to monitor changes in the child list of the current element.
+     * When a mutation event is detected, it triggers the `onObserveTracker` method of the associated carousel API.
+     *
+     * @function
+     * @name registerMutationObserver
+     * @returns {void}
      */
     registerMutationObserver() {
+      /**
+       * Mutation Observer callback function.
+       *
+       * @callback MutationObserverCallback
+       * @param {Array<MutationRecord>} mutationsList - An array of mutation records.
+       * @param {MutationObserver} observer - The Mutation Observer instance.
+       */
+
+      /**
+       * Mutation Observer instance.
+       *
+       * @type {MutationObserver}
+       */
       this.mutationObserver = new MutationObserver(() => {
-        this.apiCarousel().onMutateTracker();
+        this.apiCarousel().onObserveTracker();
       });
 
+      // Start observing changes in the child list of the current element
       this.mutationObserver.observe(this.$el, {
         childList: true,
       });
     },
 
     /**
-     * Adds an event listener to the current element to listen for the 'scrollend' event
-     * and invokes the 'onScroll' method when the event is triggered.
+     * Adds the 'scroll' event listener to the component's root element.
+     * The 'scroll' event triggers the 'onScroll' method when the element is scrolled.
+     *
+     * @function
+     * @memberof VTCarouselTracker
+     * @name addEventListeners
+     * @returns {void}
      */
     addEventListeners() {
+      // Listen for 'scroll' events on the component's root element
       this.$el.addEventListener('scroll', this.onScroll);
     },
 
+    /**
+     * Handles the 'scroll' event by invoking methods related to left end and left start positions.
+     * Calls the 'isLeftEndReached' and 'isLeftStartReached' methods from the carousel API.
+     *
+     * @function
+     * @memberof VTCarouselTracker
+     * @name onScroll
+     * @returns {void}
+     */
     onScroll() {
+      // Check and update left end and left start positions based on the scroll event
       this.apiCarousel().isLeftEndReached();
       this.apiCarousel().isLeftStartReached();
     },