vevet 3.19.2 → 4.0.0-beta.0

package/src/base/Module/index.ts

@@ -9,14 +9,46 @@ import { MutableProps, NMutableProps } from '../MutableProps';
 import { Callbacks, NCallbacks } from '../Callbacks';
 import { TRequiredModuleProp } from '@/types/utility';
 import { getApp } from '@/utils/internal/getApp';
-import { createViewport } from '@/src/Application/events/createViewport';
+import { createViewport } from '@/src/Vevet/events/createViewport';
 
 export type { NModule };
 
 type TViewportAdd = ReturnType<typeof createViewport>['callbacks']['add'];
 
 /**
- * Module base
+ * A base class for modules that handle responsive properties, event listeners, and custom callbacks.
+ * This class provides a structure for modules that can dynamically respond to viewport changes, property mutations, and various lifecycle events.
+ *
+ * @example
+ *
+ * interface IStaticProps extends NModule.IStaticProps {
+ *   staticName: 'My name';
+ * }
+ *
+ * interface IChangeableProps extends NModule.IChangeableProps {
+ *   weight: number;
+ *   height: number;
+ * }
+ *
+ * interface ICallbacks extends NModule.ICallbacksTypes {}
+ *
+ * const module = new Module<IStaticProps, IChangeableProps, ICallbacks>({
+ *   staticName: 'My name',
+ *   weight: 70,
+ *   height: 175,
+ * }, false);
+ *
+ * module.addResponsiveProps({
+ *   breakpoint: 'viewport_phone',
+ *   settings: {
+ *     weight: 80,
+ *   },
+ * });
+ *
+ * module.init();
+ *
+ * module.addCallback('propsMutate', () => console.log('mutate props'));
+ * module.addCallback('destroy', () => console.log('destroy'));
  */
 export class Module<
   StaticProps extends NModule.IStaticProps = NModule.IStaticProps,
@@ -24,118 +56,83 @@ export class Module<
   CallbacksTypes extends NModule.ICallbacksTypes = NModule.ICallbacksTypes,
 > {
   /**
-   * Get Default properties (should be extended)
+   * Retrieves the default properties for the module. This method is intended to be overridden in subclasses to provide default values for the module's properties.
    */
   protected _getDefaultProps() {
     return {};
   }
 
-  /** Current properties */
+  /**
+   * The current properties of the module, which include both static and changeable properties.
+   * These can be retrieved dynamically during the module's lifecycle.
+   */
   get props() {
     return this._mutableProps.props as TRequiredModuleProp<
       StaticProps & ChangeableProps
     >;
   }
 
-  /** Responsive properties */
+  /** Manages the module's mutable properties */
   private _mutableProps: MutableProps<StaticProps, ChangeableProps>;
 
-  /** Module Callbacks */
+  /** Manages the module's callbacks */
   private _callbacks: Callbacks<CallbacksTypes>;
 
-  /** Module Callbacks */
+  /**
+   * Retrieves the module's registered callbacks.
+   */
   get callbacks() {
     return this._callbacks;
   }
 
-  /** Module listeners */
+  /** Holds the list of event listeners added to the module */
   private _listeners: IAddEventListener[];
 
-  /**
-   * Destroyable actions
-   */
+  /** Stores actions that need to be executed when the module is destroyed */
   private _destroyableActions: (() => void)[];
 
-  /**
-   * Classnames to remove
-   */
+  /** Stores the class names to be removed when the module is destroyed */
   private _classNamesToRemove: NModule.IClassNamesToRemove[];
 
-  /** Module name */
+  /** The name of the module, derived from the class name */
   get name() {
     return this.constructor.name;
   }
 
-  /** Module prefix */
+  /** Optional prefix for class names used by the module */
   get prefix() {
     return '';
   }
 
-  /** The module is initialized */
+  /** Tracks whether the module has been initialized */
   private _isInitialized = false;
 
-  /** The module is initialized */
+  /**
+   * Checks if the module has been initialized.
+   */
   get isInitialized() {
     return this._isInitialized;
   }
 
-  /** The module is destroyed */
+  /** Tracks whether the module has been destroyed */
   private _isDestroyed = false;
 
-  /** The module is destroyed */
+  /**
+   * Checks if the module has been destroyed.
+   */
   get isDestroyed() {
     return this._isDestroyed;
   }
 
   /**
-   * @example
-   * 
-   * interface IStaticProps extends NModule.IStaticProps {
-   *   staticName: 'My name';
-   * }
-
-   * interface IChangeableProps extends NModule.IChangeableProps {
-   *   weight: number;
-   *   height: number;
-   * }
-
-   * interface ICallbacks extends NModule.ICallbacksTypes {}
-
-   * const module = new Module<IStaticProps, IChangeableProps, ICallbacks>(
-   *   {
-   *     staticName: 'My name',
-   *     weight: 70,
-   *     height: 175,
-   *   },
-   *   false
-   * );
-
-   * module.addResponsiveProps({
-   *   breakpoint: 'viewport_phone',
-   *   settings: {
-   *     weight: 80,
-   *   },
-   * });
-
-   * module.init();
-
-   * module.addCallback('propsMutate', () => console.log('mutate props'));
-
-   * module.addCallback('destroy', () => console.log('destroy'));
+   * Creates a new instance of the Module class.
+   *
+   * @param initialProps - The initial static and changeable properties to be used by the module.
+   * @param canInit - Whether to automatically initialize the module after construction. Set this to `false` if you want to add responsive properties before initializing.
    */
-  constructor(
-    /** Initial properties */
-    initialProps?: StaticProps & ChangeableProps,
-    /**
-     * Defines if you need to call {@linkcode Module.init} at the constructor's end.
-     * If you want to add responsive properties, set this parameter to `false`.
-     */
-    canInit = true,
-  ) {
+  constructor(initialProps?: StaticProps & ChangeableProps, canInit = true) {
     if (!getApp()) {
-      throw new Error(
-        'Vevet.Application does not exist yet. Call "new Vevet.Application()" before using all the stuff',
-      );
+      throw new Error('Vevet.Application does not exist yet');
     }
 
     this._callbacks = new Callbacks<CallbacksTypes>();
@@ -159,7 +156,11 @@ export class Module<
     }
   }
 
-  /** Add responsive rules */
+  /**
+   * Adds responsive property rules to the module. This must be done before initialization.
+   *
+   * @param rules - The responsive property rules to be added.
+   */
   public addResponsiveProps(rules: NMutableProps.IResponsive<ChangeableProps>) {
     if (this.isInitialized) {
       throw new Error(
@@ -170,7 +171,11 @@ export class Module<
     }
   }
 
-  /** Change module properties */
+  /**
+   * Updates the changeable properties of the module.
+   *
+   * @param props - The properties to be updated.
+   */
   public changeProps(props: Partial<ChangeableProps>) {
     if (this.isDestroyed) {
       return;
@@ -182,13 +187,15 @@ export class Module<
   }
 
   /**
-   * This method is called on properties change
+   * This method is called internally when the module's properties change.
    */
   protected _onPropsMutate() {
     this._callbacks.tbt('propsMutate', undefined);
   }
 
-  /** Initializes the class */
+  /**
+   * Initializes the module. Calls the internal `_init` method and marks the module as initialized.
+   */
   public init() {
     if (this.isInitialized) {
       return;
@@ -199,16 +206,26 @@ export class Module<
     this._init();
   }
 
-  /** Inner extra initialization */
+  /**
+   * Additional initialization logic that can be overridden in subclasses.
+   */
   protected _init() {}
 
-  /** Add destroyable actions */
+  /**
+   * Adds an action to the list of actions to be executed when the module is destroyed.
+   *
+   * @param action - The function to execute during destruction.
+   */
   protected addDestroyableAction(action: () => void) {
     this._destroyableActions.push(action);
   }
 
   /**
-   * Add a viewport callback that will be removed on class destroy
+   * Adds a viewport callback that will be automatically removed when the module is destroyed.
+   *
+   * @param target - The viewport target (e.g., width or height).
+   * @param action - The callback function to execute when the viewport target changes.
+   * @param data - Additional data for the callback.
    */
   public addViewportCallback(
     target: Parameters<TViewportAdd>[0],
@@ -223,7 +240,13 @@ export class Module<
     this.addDestroyableAction(() => callback.remove());
   }
 
-  /** Add a module callback */
+  /**
+   * Adds a custom callback to the module.
+   *
+   * @param target - The event type to listen for (e.g., 'propsChange', 'destroy').
+   * @param action - The function to execute when the event is triggered.
+   * @param settings - Additional settings for the callback.
+   */
   public addCallback<T extends keyof CallbacksTypes>(
     target: T,
     action: NCallbacks.TAction<CallbacksTypes[T]>,
@@ -232,7 +255,14 @@ export class Module<
     return this.callbacks.add(target, action, settings);
   }
 
-  /** Add a DOM event listener */
+  /**
+   * Adds a DOM event listener that will be automatically removed when the module is destroyed.
+   *
+   * @param el - The target element for the event listener.
+   * @param target - The event type to listen for (e.g., 'click', 'resize').
+   * @param callback - The callback function to execute when the event is triggered.
+   * @param options - Additional options for the event listener.
+   */
   public addEventListener<
     El extends ListenerElement,
     Target extends keyof HTMLElementEventMap,
@@ -258,11 +288,23 @@ export class Module<
     };
   }
 
+  /**
+   * Helper function to generate class names with the module's prefix.
+   *
+   * @param classNames - The class names to generate.
+   * @returns A string of class names with the module's prefix applied.
+   */
   protected className(...classNames: string[]) {
     return classNames.map((value) => `${this.prefix}${value}`).join(' ');
   }
 
-  /** Toggle classList */
+  /**
+   * Toggles a class name on an element, and keeps track of it for removal when the module is destroyed.
+   *
+   * @param element - The target DOM element.
+   * @param className - The class name to toggle.
+   * @param isActive - Whether the class should be added or removed.
+   */
   protected toggleClassName(
     element: Element,
     className: string,
@@ -277,7 +319,9 @@ export class Module<
     }
   }
 
-  /** Destroy the module */
+  /**
+   * Destroys the module, cleaning up resources, callbacks, and event listeners.
+   */
   public destroy() {
     if (this.isDestroyed) {
       return;
@@ -286,7 +330,10 @@ export class Module<
     this._destroy();
   }
 
-  /** Destroy the module */
+  /**
+   * Internal method to handle the destruction of the module.
+   * It removes all callbacks, destroys properties, and cleans up event listeners and class names.
+   */
   protected _destroy() {
     this._callbacks.tbt('destroy', undefined);
     this._callbacks.destroy();

package/src/base/Module/types.ts

@@ -2,26 +2,55 @@ import { NCallbacks } from '../Callbacks/types';
 
 export namespace NModule {
   /**
-   * Mutable Properties (may change on window resize or through {@linkcode Module.changeProps})
+   * Interface representing the properties that can change dynamically.
+   * These properties may be updated during window resize events or through
+   * the {@linkcode Module.changeProps} method.
    */
   export interface IChangeableProps {
     __fixHelperChangeableProps?: any;
   }
 
-  /** Static properties */
+  /**
+   * Interface representing static properties that remain constant and do not change
+   * after initialization.
+   */
   export interface IStaticProps {
     __fixHelperStaticProps?: any;
   }
 
-  /** Available callbacks */
+  /**
+   * Defines the available callback types for the module.
+   * These callbacks allow interaction with specific module events.
+   */
   export interface ICallbacksTypes extends NCallbacks.ITypes {
+    /**
+     * Triggered when the module is destroyed.
+     */
     destroy: undefined;
+
+    /**
+     * Triggered when module properties are manually changed.
+     */
     propsChange: undefined;
+
+    /**
+     * Triggered when module properties mutate due to responsive settings or other updates.
+     */
     propsMutate: undefined;
   }
 
+  /**
+   * Represents the class names to be removed from an element when the module is destroyed.
+   */
   export interface IClassNamesToRemove {
+    /**
+     * The DOM element from which the class name should be removed.
+     */
     element: Element;
+
+    /**
+     * The class name that should be removed from the element.
+     */
     className: string;
   }
 }

package/src/base/MutableProps/index.ts

@@ -5,133 +5,102 @@ import { NMutableProps } from './types';
 export type { NMutableProps };
 
 /**
- * A class for creating mutable properties that can change on window resize. <br><br>
- *
- * There are two ways to change properties:
- * - To set a resize-listener on window (or use {@linkcode Viewport}).
- * When the window is resized, change the properties with the help of
- * {@linkcode MutableProps.changeProps}
- * 
- * - The second way is to use the MutableProps and add responsive properties
- * with help of {@linkcode MutableProps.addResponsiveProps}.
+ * A class for managing mutable properties that can change based on window size (responsive design).
+ * This allows certain properties to update dynamically when the window is resized or in response to manual changes.
  *
  * @example
- * 
+ *
  * interface IStatic {
  *   static: string;
  * }
-
+ *
  * interface IChangeable {
  *   changeable: string;
  * }
-
+ *
  * const props = new MutableProps<IStatic, IChangeable>({
  *   static: '',
  *   changeable: 'something',
  * });
-
+ *
  * props.addResponsiveProps({
  *   breakpoint: 'viewport_phone',
  *   settings: {
  *     changeable: 'phone',
  *   },
  * });
-
+ *
  * props.changeProps({ changeable: 'changed' });
  */
 export class MutableProps<
-  /**
-   * Static Properties (they never change)
-   */
   StaticProps extends Record<string, any>,
-  /**
-   * Mutable Properties
-   * (may change on window resize or through {@linkcode MutableProps.changeProps})
-   */
   ChangeableProps extends Record<string, any>,
 > {
   /**
-   * Reference properties.
-   * These properties may change only through {@linkcode MutableProps.changeProps}.
+   * A reference to the original properties (both static and changeable).
+   * These properties are only updated manually via {@linkcode changeProps}.
    */
   private _refProps: StaticProps & ChangeableProps;
 
   /**
-   * Current properties.
-   * These properties may change both on {@linkcode MutableProps.changeProps} and resize.
+   * The current active properties. These can be updated through both window resizing
+   * (via responsive rules) and manual changes through {@linkcode changeProps}.
    */
   private _props: StaticProps & ChangeableProps;
 
   /**
-   * A set of responsive rules
+   * A set of responsive rules defining how properties should change based on viewport size or device type.
+   * Each rule is defined by a breakpoint and corresponding property settings.
    */
   private _responsiveRules: NMutableProps.IResponsive<ChangeableProps>[] = [];
 
   /**
-   * Get current properties
+   * The active breakpoints currently applied to the properties.
    */
-  get props() {
-    return this._props;
-  }
+  private _activeBreakpoints: (string | number)[];
 
   /**
-   * Viewport callback
+   * A callback used to update properties when the viewport size changes.
    */
   private _viewportCallback?: NCallbacks.IAddedCallback;
 
   /**
-   * Active breakpoints used to define if properties have changed
-   */
-  private _activeBreakpoints: (string | number)[];
-
-  /**
-   * @example
+   * Initializes the `MutableProps` instance with static and changeable properties,
+   * and sets up a mutation callback to be called when properties change.
    *
-   * const static = {
-   *   myProp: true,
-   * };
-   *
-   * const responsive = [
-   *   {
-   *     breakpoint: 'm',
-   *     settings: {
-   *       myProp: false
-   *     }
-   *   }
-   * ];
-   *
-   * const props = new MutableProps(static, responsive);
+   * @param initProps - Initial properties, including both static and changeable properties.
+   * @param _onMutate - Callback function triggered whenever the properties change.
+   * @param _name - The name used to identify the set of responsive properties.
    */
   constructor(
-    /**
-     * The properties that were set while initialization.
-     * These properties will nevet change.
-     */
-    private _initProps: StaticProps & ChangeableProps,
-    /**
-     * A callback that is launched when properties are changed
-     */
+    initProps: StaticProps & ChangeableProps,
     private _onMutate: () => void = () => {},
-    /**
-     * Name of the responsive properties.
-     */
     private _name = 'Responsive Props',
   ) {
-    this._refProps = { ..._initProps };
-    this._props = { ..._initProps };
-
+    this._refProps = { ...initProps };
+    this._props = { ...initProps };
     this._activeBreakpoints = [];
   }
 
   /**
-   * Add responsive rules
+   * Retrieves the current properties.
+   * These may change either due to responsive rules or through manual updates.
+   */
+  get props() {
+    return this._props;
+  }
+
+  /**
+   * Adds responsive rules that define how the properties should change based on viewport breakpoints.
+   *
+   * @param rules - Responsive rules specifying breakpoints and corresponding property settings.
    */
   public addResponsiveProps(rules: NMutableProps.IResponsive<ChangeableProps>) {
     this._responsiveRules.push(rules);
 
     this._responseProps();
 
-    if (typeof this._viewportCallback !== 'undefined') {
+    if (this._viewportCallback) {
       return;
     }
 
@@ -143,7 +112,8 @@ export class MutableProps<
   }
 
   /**
-   * Change properties according to the "responsive" settings
+   * Handles updating the properties based on the current viewport size.
+   * It checks all responsive rules and applies the appropriate settings for active breakpoints.
    */
   private _responseProps() {
     const app = getApp();
@@ -155,8 +125,7 @@ export class MutableProps<
     const prevActiveBreakpointsString = [...this._activeBreakpoints].join('_');
     this._activeBreakpoints = [];
 
-    // go through all breakpoints
-    // and check if a proper breakpoint exists
+    // Evaluate each responsive rule to see if it should be applied
     this._responsiveRules.forEach(({ settings, breakpoint }) => {
       if (typeof breakpoint === 'number') {
         if (viewport.width <= breakpoint) {
@@ -199,14 +168,16 @@ export class MutableProps<
       this._props = { ...this._props, ...(newProps as any) };
     }
 
-    // callback
+    // Call the mutation callback if properties have changed
     if (isPropsChanged) {
       this._onMutate();
     }
   }
 
   /**
-   * This method allows you to change the properties manually.
+   * Manually changes the properties. The updated properties persist and trigger the mutation callback.
+   *
+   * @param props - A partial set of changeable properties to be updated.
    */
   public changeProps(props: Partial<ChangeableProps>) {
     this._props = { ...this._props, ...props };
@@ -216,7 +187,7 @@ export class MutableProps<
   }
 
   /**
-   * Destroy the responsive properties.
+   * Cleans up and destroys the responsive properties.
    */
   public destroy() {
     if (this._viewportCallback) {

package/src/base/MutableProps/types.ts

@@ -1,16 +1,19 @@
 export namespace NMutableProps {
   export interface IResponsive<S> {
     /**
-     * The breakpoint at which properties will change.
+     * Defines the breakpoint at which the properties should change.
+     * The `breakpoint` can represent either a specific screen width (in pixels)
+     * or a predefined device type or viewport size.
+     *
      * Available breakpoints:
      * <ul>
-     *   <li>any number - width breakpoint</li>
-     *   <li>'d' - for desktop size</li>
-     *   <li>'t' - for tablet size</li>
-     *   <li>'p' - for phone size</li>
-     *   <li>'phone' - for phone devices</li>
-     *   <li>'tablet' - for tablet devices</li>
-     *   <li>'mobile' - for phone or tablet devices</li>
+     *   <li><code>number</code> - Width breakpoint in pixels, e.g., 768 for tablets or 1024 for desktops.</li>
+     *   <li><code>'viewport_desktop'</code> - When the viewport width is categorized as desktop size.</li>
+     *   <li><code>'viewport_tablet'</code> - When the viewport width is categorized as tablet size.</li>
+     *   <li><code>'viewport_phone'</code> - When the viewport width is categorized as phone size.</li>
+     *   <li><code>'device_phone'</code> - When the user is on a phone device, regardless of viewport size.</li>
+     *   <li><code>'device_tablet'</code> - When the user is on a tablet device, regardless of viewport size.</li>
+     *   <li><code>'device_mobile'</code> - When the user is on any mobile device (either phone or tablet).</li>
      * </ul>
      */
     breakpoint:
@@ -21,6 +24,10 @@ export namespace NMutableProps {
       | 'device_phone'
       | 'device_tablet'
       | 'device_mobile';
+
+    /**
+     * The property settings that should be applied when the defined breakpoint is matched.
+     */
     settings: Partial<S>;
   }
 }