vevet 3.20.0 → 4.0.0-beta.1

package/src/components/ScrollBar/index.ts

@@ -1,6 +1,6 @@
 import { selectOne } from 'vevet-dom';
-import type { SmoothScroll } from '../SmoothScroll';
-import Bar from './Bar';
+import type { CustomScroll } from '../CustomScroll';
+import { Bar } from './Bar';
 import { NScrollBar } from './types';
 import { Component as ComponentClass } from '@/base/Component';
 import { IBarProps } from './Bar/types';
@@ -10,7 +10,11 @@ import { getApp } from '@/utils/internal/getApp';
 export type { NScrollBar };
 
 /**
- * Create custom scroll bar
+ * A custom scroll bar component that can be added to custom or native scroll containers.
+ * It supports both horizontal and vertical scroll bars, auto-hide functionality,
+ * and drag-to-scroll.
+ *
+ * @requires Requires styles: `@import '~vevet/lib/styles/components/ScrollBar';`
  */
 export class ScrollBar<
   StaticProps extends NScrollBar.IStaticProps = NScrollBar.IStaticProps,
@@ -38,30 +42,17 @@ export class ScrollBar<
   }
 
   /** Scroll container */
-  protected _container: Element | Window | SmoothScroll;
+  protected _container: Element | Window | CustomScroll;
 
-  /** Scroll container */
+  /**
+   * The container element or window where the scroll is applied.
+   */
   get container() {
     return this._container;
   }
 
-  /** Scrollable element */
-  get scrollableElement() {
-    const { container } = this;
-
-    if (container instanceof Window) {
-      return getApp().body;
-    }
-
-    if (container instanceof Element) {
-      return container;
-    }
-
-    return container.container;
-  }
-
   /**
-   * The element where scrollbars will be appended
+   * Returns the DOM element where the scroll bars will be appended.
    */
   get domParent() {
     const { domParent } = this.props;
@@ -83,12 +74,34 @@ export class ScrollBar<
     return container.container;
   }
 
-  /** Horizontal scrollbar */
+  /**
+   * Horizontal scrollbar instance
+   * @ignore
+   */
   protected _xBar: Bar;
 
-  /** Vertical scrollbar */
+  /**
+   * Returns the horizontal scroll bar instance.
+   * @ignore
+   */
+  get xBar() {
+    return this._xBar;
+  }
+
+  /**
+   * Vertical scrollbar instance
+   * @ignore
+   */
   protected _yBar: Bar;
 
+  /**
+   * Returns the vertical scroll bar instance.
+   * @ignore
+   */
+  get yBar() {
+    return this._yBar;
+  }
+
   constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
     super(initialProps, false);
 
@@ -100,7 +113,7 @@ export class ScrollBar<
       if (element) {
         this._container = element;
       } else {
-        throw new Error('No scroll container');
+        throw new Error('No scroll container found');
       }
     } else {
       this._container = container as any;
@@ -113,21 +126,30 @@ export class ScrollBar<
       domParent: this.domParent,
       prefix: this.prefix,
     };
+
     this._xBar = new Bar({
       ...barProps,
       direction: 'x',
     });
+
     this._yBar = new Bar({
       ...barProps,
       direction: 'y',
     });
 
     // add classnames
-    this.toggleClassName(
-      this.scrollableElement,
-      this.className('-parent'),
-      true,
-    );
+    if (this.container instanceof Window) {
+      this.toggleClassName(getApp().html, this.className('-parent'), true);
+      this.toggleClassName(getApp().body, this.className('-parent'), true);
+    } else if (this.container instanceof Element) {
+      this.toggleClassName(this.container, this.className('-parent'), true);
+    } else {
+      this.toggleClassName(
+        this.container.container,
+        this.className('-parent'),
+        true,
+      );
+    }
 
     // initialize the class
     if (canInit) {
@@ -135,28 +157,33 @@ export class ScrollBar<
     }
   }
 
+  /**
+   * Initializes the ScrollBar component.
+   */
   protected _init() {
     super._init();
 
     this._setEvents();
   }
 
-  // Set Module Events
+  /**
+   * Sets event listeners for the component.
+   */
   protected _setEvents() {
     const { container, props } = this;
 
     // default resize handler
     const resizeHandler = onResize({
       onResize: () => this.resize(),
-      element: [this._xBar.outer, this._yBar.outer],
+      element: [this.xBar.outer, this.yBar.outer],
       viewportTarget: 'any',
       hasBothEvents: true,
       resizeDebounce: props.resizeDebounce,
     });
 
-    // resize for smoothscroll
-    const smoothScrollResize =
-      'isSmoothScroll' in container
+    // resize for custom scroll
+    const scrollResize =
+      'isCustomScroll' in container
         ? container.addCallback(
             'resize',
             () => resizeHandler.debounceResize(),
@@ -166,25 +193,33 @@ export class ScrollBar<
 
     this.addDestroyableAction(() => {
       resizeHandler.remove();
-      smoothScrollResize?.remove();
+      scrollResize?.remove();
     });
 
     // initial resize
     resizeHandler.resize();
   }
 
+  /**
+   * Handles the mutation of the properties and updates the component accordingly.
+   */
   protected _onPropsMutate() {
     super._onPropsMutate();
+
     this.resize();
   }
 
-  /** Resize the scene */
+  /**
+   * Resizes the scene and updates the scroll bars.
+   */
   public resize() {
-    this._xBar.resize();
-    this._yBar.resize();
+    this.xBar.resize();
+    this.yBar.resize();
   }
 
-  /** Destroy the module */
+  /**
+   * Destroys the scroll bar component and cleans up.
+   */
   protected _destroy() {
     super._destroy();
 

package/src/components/ScrollBar/stories/{WithSmoothScrollComponent.tsx → WithCustomScrollComponent.tsx}

@@ -1,9 +1,9 @@
 import React, { FC, useEffect, useRef } from 'react';
 import { times } from '@/utils/common';
-import { SmoothScroll } from '@/components/SmoothScroll';
+import { CustomScroll } from '@/components/CustomScroll';
 import { ScrollBar } from '..';
 
-export const WithSmoothScrollComponent: FC = () => {
+export const WithCustomScrollComponent: FC = () => {
   const containerRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -11,7 +11,7 @@ export const WithSmoothScrollComponent: FC = () => {
       return undefined;
     }
 
-    const scroll = new SmoothScroll({
+    const scroll = new CustomScroll({
       container: containerRef.current,
     });
 
@@ -28,10 +28,10 @@ export const WithSmoothScrollComponent: FC = () => {
   return (
     <div
       ref={containerRef}
-      className="v-smooth-scroll"
+      className="v-custom-scroll"
       style={{ height: 500, maxWidth: 500, backgroundColor: '#eee' }}
     >
-      <div className="v-smooth-scroll__wrapper">
+      <div className="v-custom-scroll__wrapper">
         {times(
           (index) => (
             <div key={index}>

package/src/components/ScrollBar/stories/index.stories.tsx

@@ -1,6 +1,6 @@
 import type { Meta, StoryFn } from '@storybook/react';
 import React from 'react';
-import { WithSmoothScrollComponent } from './WithSmoothScrollComponent';
+import { WithCustomScrollComponent } from './WithCustomScrollComponent';
 import { WithInnerScrollComponent } from './WithInnerScroll';
 import { WithDefaultComponent } from './Default';
 
@@ -14,9 +14,9 @@ export const Default: StoryFn<typeof WithDefaultComponent> = (props) => (
   <WithDefaultComponent {...props} />
 );
 
-export const WithSmoothScroll: StoryFn<typeof WithSmoothScrollComponent> = (
+export const WithCustomScroll: StoryFn<typeof WithCustomScrollComponent> = (
   props,
-) => <WithSmoothScrollComponent {...props} />;
+) => <WithCustomScrollComponent {...props} />;
 
 export const WithInnerScroll: StoryFn<typeof WithInnerScrollComponent> = (
   props,

package/src/components/ScrollBar/types.ts

@@ -1,5 +1,5 @@
 import { NComponent } from '@/base/Component/types';
-import type { SmoothScroll } from '../SmoothScroll';
+import type { CustomScroll } from '../CustomScroll';
 import { IBarProps } from './Bar/types';
 
 type TPickedProps =
@@ -14,18 +14,22 @@ export namespace NScrollBar {
     extends NComponent.IStaticProps,
       Partial<Pick<IBarProps, TPickedProps>> {
     /**
-     * The scrollable element
+     * The scrollable element to which the scroll bar will be applied.
+     * Can be the window, a custom scroll instance, or an HTML element.
      * @default window
      */
-    container?: Window | SmoothScroll | Element | string;
+    container?: Window | CustomScroll | Element | string;
+
     /**
-     * The element that will contain the scrollbar.
-     * If false, the property 'container' will be taken.
+     * The element where the scroll bars will be rendered.
+     * If `false`, the scroll bar will be appended to the `container`.
      * @default false
      */
     domParent?: false | Element;
+
     /**
-     * Timeout of resize event
+     * Timeout value (in milliseconds) to debounce the resize event.
+     * This helps avoid multiple rapid invocations of resize handling.
      * @default 16
      */
     resizeDebounce?: number;

package/src/components/ScrollView/index.ts

@@ -9,7 +9,9 @@ import { getApp } from '@/utils/internal/getApp';
 export type { NScrollView };
 
 /**
- * Detect when elements enter or leave the viewport
+ * `ScrollView` detects when elements enter or leave the viewport.
+ * It uses the `IntersectionObserver` API for efficient detection and triggers events when elements are visible or hidden.
+ * Supports adding custom delay and class toggling when elements are in view.
  */
 export class ScrollView<
   StaticProps extends NScrollView.IStaticProps = NScrollView.IStaticProps,
@@ -34,31 +36,45 @@ export class ScrollView<
     };
   }
 
-  /** Intersection observer - type IN */
+  /**
+   * Intersection observer for detecting when elements come into view.
+   */
   protected _intersectionObserverIn?: IntersectionObserver;
 
-  /** Intersection observer - type OUT */
+  /**
+   * Intersection observer for detecting when elements leave the view.
+   */
   protected _intersectionObserverOut?: IntersectionObserver;
 
-  /** If first start */
+  /**
+   * Tracks if this is the first time the elements are being observed.
+   */
   protected _isFirstStart: boolean;
 
-  /** If first start */
+  /**
+   * Returns whether this is the first start of observing elements.
+   */
   get isFirstStart() {
     return this._isFirstStart;
   }
 
-  /** Elements */
+  /**
+   * Stores the elements being observed for entering and leaving the viewport.
+   */
   protected _elements: NScrollView.IElement[];
 
-  /** If intersection observer is supported */
-  protected _isIntersectionObserverSupported: boolean;
-
-  /** Elements */
+  /**
+   * Returns the elements being observed by the `ScrollView`.
+   */
   get elements() {
     return this._elements;
   }
 
+  /**
+   * Indicates whether the `IntersectionObserver` API is supported in the current environment.
+   */
+  protected _isIntersectionObserverSupported: boolean;
+
   constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
     super(initialProps, false);
 
@@ -66,7 +82,7 @@ export class ScrollView<
     this._elements = [];
     this._isIntersectionObserverSupported = isIntersectionObserverSupported();
 
-    // initialize the class
+    // initialize the class if requested
     if (canInit) {
       this.init();
     }
@@ -84,18 +100,23 @@ export class ScrollView<
     this.resize();
   }
 
-  /** Set class events */
+  /**
+   * Sets up the events needed for viewport resizing and element observation.
+   */
   protected _setEvents() {
     const { viewportTarget, resizeDebounce } = this.props;
 
     this.resize();
 
+    // Set up a viewport callback to trigger the resize method
     this.addViewportCallback(viewportTarget, () => this.resize(), {
       timeout: resizeDebounce,
     });
   }
 
-  /** Resize the scene */
+  /**
+   * Triggers a resize event to update the `ScrollView` tracking of elements.
+   */
   public resize() {
     this._removeViewEvents();
 
@@ -104,7 +125,9 @@ export class ScrollView<
     }
   }
 
-  /** Root bounding rect */
+  /**
+   * Returns the bounding rectangle for the root element or the viewport.
+   */
   protected get rootBounding() {
     const { props } = this;
 
@@ -129,7 +152,9 @@ export class ScrollView<
     };
   }
 
-  /** Set view events */
+  /**
+   * Sets up the `IntersectionObserver` to detect when elements come into view.
+   */
   protected _setViewEvents() {
     if (!this._isIntersectionObserverSupported) {
       return;
@@ -137,6 +162,7 @@ export class ScrollView<
 
     const { rootBounding, isFirstStart, props } = this;
 
+    // Calculate margins for intersection detection
     const xMargin = isFirstStart
       ? 0
       : rootBounding.width * props.rootMargin * -1;
@@ -174,7 +200,9 @@ export class ScrollView<
     }
   }
 
-  /** Remove View events */
+  /**
+   * Removes the view observation events by disconnecting the `IntersectionObserver`.
+   */
   protected _removeViewEvents() {
     this._intersectionObserverIn?.disconnect();
     this._intersectionObserverIn = undefined;
@@ -183,7 +211,11 @@ export class ScrollView<
     this._intersectionObserverOut = undefined;
   }
 
-  /** Event on IntersectionObserver In */
+  /**
+   * Handles when elements come into the viewport.
+   *
+   * @param data - The intersection data for the observed elements.
+   */
   protected _handleIntersectionIn(data: IntersectionObserverEntry[]) {
     data.forEach((entry) => {
       if (!entry.isIntersecting) {
@@ -200,7 +232,7 @@ export class ScrollView<
       }
     });
 
-    // change states
+    // Mark first start complete and trigger resize
     if (this.isFirstStart) {
       this._isFirstStart = false;
       this.resize();
@@ -228,7 +260,11 @@ export class ScrollView<
     return progress * props.maxDelay;
   }
 
-  /** Event on IntersectionObserver Out */
+  /**
+   * Handles when elements leave the viewport.
+   *
+   * @param data - The intersection data for the observed elements.
+   */
   protected _handleIntersectionOut(data: IntersectionObserverEntry[]) {
     data.forEach((entry) => {
       if (entry.isIntersecting) {
@@ -241,7 +277,7 @@ export class ScrollView<
   }
 
   /**
-   * Event that is triggered when an element appears or disappears
+   * Toggles classes and triggers callbacks when elements enter or leave the viewport.
    */
   protected _handleInOut(
     elementProp: NScrollView.IElement,
@@ -258,17 +294,17 @@ export class ScrollView<
       return;
     }
 
-    // update props
+    // Update element's viewport state
     element.isScrollViewIn = isInViewport;
 
-    // toggle classes
+    // Toggle class for the element
     if (classToToggle) {
       normalizedTimeoutCallback(() => {
         element.classList.toggle(classToToggle, isInViewport);
       }, delay);
     }
 
-    // process callbacks
+    // Trigger appropriate callback
     if (isInViewport) {
       normalizedTimeoutCallback(() => {
         this.callbacks.tbt('in', { element });
@@ -280,7 +316,9 @@ export class ScrollView<
     }
   }
 
-  /** Add an element */
+  /**
+   * Adds an element to the observer list and starts tracking its visibility in the viewport.
+   */
   public addElement(elementProp: Element): IRemovable {
     const element = elementProp as NScrollView.IElement;
 
@@ -300,7 +338,11 @@ export class ScrollView<
     };
   }
 
-  /** Remove an element */
+  /**
+   * Stops observing an element and removes it from the observer list.
+   *
+   * @param {Element} elementProp - The element to stop observing.
+   */
   public removeElement(elementProp: Element) {
     const element = elementProp as NScrollView.IElement;
 
@@ -311,13 +353,17 @@ export class ScrollView<
     this._elements = this._elements.filter((el) => el !== element);
   }
 
-  /** Remove all elements */
+  /**
+   * Stops observing all elements and clears the observer list.
+   */
   public removeElements() {
     this._elements.forEach((element) => this.removeElement(element));
     this._elements = [];
   }
 
-  /** Destroy the module */
+  /**
+   * Destroys the `ScrollView` and disconnects all observers and listeners.
+   */
   protected _destroy() {
     super._destroy();
 

package/src/components/ScrollView/stories/index.tsx

@@ -11,7 +11,7 @@ export const Component: FC = () => {
       return undefined;
     }
 
-    const instance = new ScrollView();
+    const instance = new ScrollView({ states: 'inout' });
 
     const elements = containerRef.current.querySelectorAll('*');
     elements.forEach((element) => instance.addElement(element));
@@ -35,7 +35,10 @@ export const Component: FC = () => {
     <div ref={containerRef}>
       {times(
         (index) => (
-          <div key={index} style={{ opacity: 0, transition: 'opacity 0.35s' }}>
+          <div
+            key={index}
+            style={{ marginTop: 10, opacity: 0, transition: 'opacity 0.35s' }}
+          >
             {index} Lorem ipsum dolor sit amet consectetur adipisicing elit.
           </div>
         ),