vevet 3.20.0 → 4.0.0-beta.0

package/src/styles/components/CustomCursor.scss

@@ -5,8 +5,8 @@ $custom-cursor-scale-duration: 0.5s !default;
 $custom-cursor-alpha: 0.5 !default;
 $custom-cursor-color: #000 !default;
 
-.#{$prefix}custom-cursor-container {
-  &.#{$prefix}custom-cursor-hide-defaut-cursor {
+.v-custom-cursor-container {
+  &.v-custom-cursor-hide-default-cursor {
     cursor: none;
 
     * {
@@ -15,11 +15,11 @@ $custom-cursor-color: #000 !default;
   }
 }
 
-.#{$prefix}custom-cursor {
+.v-custom-cursor {
   --cursor-w: 50px;
   --cursor-h: 50px;
 
-  &.#{$prefix}custom-cursor-in-window {
+  &.v-custom-cursor-in-window {
     position: fixed;
   }
 
@@ -34,11 +34,11 @@ $custom-cursor-color: #000 !default;
   @include transition(opacity $custom-cursor-alpha-duration);
   opacity: 0;
 
-  &.#{$prefix}custom-cursor-in-action {
+  &.v-custom-cursor-in-action {
     opacity: 1;
   }
 
-  &.#{$prefix}custom-cursor-disabled {
+  &.v-custom-cursor-disabled {
     opacity: 0;
   }
     
@@ -53,7 +53,7 @@ $custom-cursor-color: #000 !default;
 
     @include transition(transform $custom-cursor-scale-duration);
 
-    &.#{$prefix}custom-cursor-click {
+    &.v-custom-cursor-click {
       transform: scale(0.75);
     }
   }

package/{lib/styles/components/SmoothScroll.scss → src/styles/components/CustomScroll.scss}

@@ -1,18 +1,18 @@
 @import '../mixins/index';
 
-.#{$prefix}smooth-scroll {
+.v-custom-scroll {
   position: relative;
   width: 100%;
   height: 100%;
   overflow: hidden;
 
   &__wrapper {
-    &.#{$prefix}smooth-scroll_vertical {
+    &.v-custom-scroll_vertical {
       width: 100%;
       height: auto;
     }
 
-    &.#{$prefix}smooth-scroll_horizontal {
+    &.v-custom-scroll_horizontal {
       width: max-content;
       height: 100%;
     }

package/src/styles/components/Preloader.scss

@@ -2,7 +2,7 @@
 
 $preloader-bg-color: #000 !default;
 
-.#{$prefix}preloader {
+.v-preloader {
   position: fixed;
   top: 0;
   left: 0;

package/src/styles/components/ScrollBar.scss

@@ -7,11 +7,11 @@ $scrollbar-track-size: 10px !default;
 $scrollbar-thumb-size: 50px !default;
 $scrollbar-thumb-radius: 5px !default;
 
-.#{$prefix}scrollbar-parent {
+.v-scrollbar-parent {
   @include hide-scroll-bars;
 }
 
-.#{$prefix}scrollbar {
+.v-scrollbar {
   position: absolute;
   z-index: 9;
 
@@ -27,8 +27,8 @@ $scrollbar-thumb-radius: 5px !default;
     opacity: 0;
     @include transition(opacity $scrollbar-duration);
 
-    &.#{$prefix}scrollbar_is-hovered,
-    &.#{$prefix}scrollbar_in-action {
+    &.v-scrollbar_is-hovered,
+    &.v-scrollbar_in-action {
       opacity: 1;
     }
   }

package/src/styles/components/index.scss

@@ -1,4 +1,4 @@
 @import './CustomCursor';
 @import './Preloader';
 @import './ScrollBar';
-@import './SmoothScroll';
+@import './CustomScroll';

package/src/styles/index.scss

@@ -1,4 +1,3 @@
 @import './base';
-@import './globals/index';
 
 @import './components/index';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './general';
+export * from './utility';

package/src/types/utility.ts

@@ -1,4 +1,4 @@
-interface IModuleLike {
+export interface IModuleLike {
   prop: any;
   prefix: string;
   name: string;
@@ -24,7 +24,7 @@ export declare type TBuiltin =
   | Window
   | IModuleLike;
 
-declare type TDeepRequired<T> = T extends TBuiltin
+export declare type TDeepRequired<T> = T extends TBuiltin
   ? NonNullable<T>
   : T extends Map<infer K, infer V>
     ? Map<TDeepRequired<K>, TDeepRequired<V>>

package/src/utils/common/PCancelable.ts

@@ -1,3 +1,20 @@
 import PCancelable from '@anton.bobrov/p-cancelable';
 
 export { PCancelable };
+
+/**
+ * This module imports and re-exports the `PCancelable` class from the `@anton.bobrov/p-cancelable` package.
+ *
+ * `PCancelable` provides a way to create promises that can be canceled. It is useful in scenarios where
+ * you want to cancel an ongoing asynchronous operation before it finishes.
+ *
+ * @example
+ * const p = new PCancelable((resolve, reject, onCancel) => {
+ *   const timeout = setTimeout(resolve, 1000);
+ *   onCancel(() => clearTimeout(timeout));
+ * });
+ *
+ * p.cancel(); // Cancels the operation
+ *
+ * @see {@link https://github.com/antonbobrov/p-cancelable}
+ */

package/src/utils/common/normalizedTimeoutCallback.ts

@@ -1,11 +1,23 @@
 /**
- * Launch a function in a certain amount of time
- * If the `delay` argument is zero, the callback will be launched synchronously
+ * Launches a function after a specified delay. If the `delay` is zero,
+ * the callback is executed immediately (synchronously).
+ *
+ * @param callback - The function to be executed after the delay.
+ * @param delay - The amount of time (in milliseconds) to wait before executing the callback.
+ * If the delay is `0`, the callback will be executed synchronously.
+ *
+ * @returns {Object} An object with a `clear` method that can be used to cancel the timeout.
  *
  * @example
+ * // Executes the callback after 1 second (1000 milliseconds).
+ * normalizedTimeoutCallback(() => {
+ *   console.log('Executed after 1 second');
+ * }, 1000);
  *
- * normalizedTimeoutCallback(callback, 1000);
- * normalizedTimeoutCallback(callback, 0); // synchronous, without delay
+ * // Executes the callback immediately.
+ * normalizedTimeoutCallback(() => {
+ *   console.log('Executed synchronously');
+ * }, 0);
  */
 export function normalizedTimeoutCallback(callback: Function, delay: number) {
   let timeout: NodeJS.Timeout | undefined;
@@ -17,6 +29,9 @@ export function normalizedTimeoutCallback(callback: Function, delay: number) {
   }
 
   return {
+    /**
+     * Clears the timeout if it was set.
+     */
     clear: () => {
       if (timeout) {
         clearTimeout(timeout);

package/src/utils/common/objectKeys.ts

@@ -1,4 +1,14 @@
-/** Get object keys */
+/**
+ * Retrieves the keys of an object as an array of the object's keys.
+ *
+ * This function ensures that the returned keys are typed correctly based on the input object.
+ *
+ * @param object - The object from which the keys will be retrieved.
+ *
+ * @example
+ * const person = { name: 'Alice', age: 25 };
+ * const keys = objectKeys(person); // ['name', 'age']
+ */
 export function objectKeys<T>(object: T): (keyof T)[] {
-  return Object.keys(object as any) as any;
+  return Object.keys(object as any) as (keyof T)[];
 }

package/src/utils/common/pickObjectProps.ts

@@ -1,19 +1,31 @@
 /**
- * Pick object properties
+ * Pick specific properties from an object.
+ *
+ * This function creates a new object composed of the properties listed in the `keys` array,
+ * extracted from the `source` object.
+ *
+ * @param source - The source object from which to pick properties.
+ * @param keys - An array of keys that should be picked from the source object.
  *
  * @example
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const result = pickObjectProps(obj, ['a', 'c']);
+ * // => { a: 1, c: 3 }
  *
- * pickObjectProps({ a: 1, b: 2, c: 3 }, ['a', 'c']); // => { a: 1, c: 3 }
+ * @example
+ * const user = { name: 'John', age: 30, email: 'john@example.com' };
+ * const picked = pickObjectProps(user, ['name', 'email']);
+ * // => { name: 'John', email: 'john@example.com' }
  */
 export function pickObjectProps<
   T extends Record<string, any>,
   K extends keyof T,
 >(source: T, keys: K[]): Pick<T, K> {
-  const result: any = {};
+  const result: Partial<T> = {};
 
   keys.forEach((key) => {
     result[key] = source[key];
   });
 
-  return result;
+  return result as Pick<T, K>;
 }

package/src/utils/common/times.ts

@@ -1,10 +1,19 @@
 /**
- * Repeat something `n` times
+ * Repeats a function `n` times and returns an array of the results.
+ *
+ * The function executes the provided `callback` for each iteration, passing the current index and the total count as arguments.
+ * It collects and returns the results of the callback in an array.
+ *
+ * @param callback - The function to be called on each iteration. Receives the current index and the total count.
+ * @param count - The number of times to execute the callback.
  *
  * @example
+ * const result = times((index, count) => index / count, 5);
+ * // => [0, 0.2, 0.4, 0.6, 0.8]
  *
- * times((index, count) => index / count, 5);
- * // [0, 0.2, 0.4, 0.6, 0.8]
+ * @example
+ * const repeatedStrings = times(() => 'hello', 3);
+ * // => ['hello', 'hello', 'hello']
  */
 export function times<T>(
   callback: (index: number, count: number) => T,

package/src/utils/common/uid.ts

@@ -1,15 +1,17 @@
 let index = 0;
 
 /**
- * Generate a unique ID
+ * Generates a unique ID with an optional prefix.
  *
- * @example
+ * This function returns a string that combines a prefix (default is 'id') with a unique incrementing number.
+ * It ensures each call will return a unique identifier.
  *
+ * @example
  * uid(); // => 'id_1'
  * uid('test'); // => 'test_2'
  * uid('0'); // => '0_3'
  */
-export function uid(prefix = 'id') {
+export function uid(prefix = 'id'): string {
   index += 1;
 
   return `${prefix}_${index}`;

package/src/utils/image/load.ts

@@ -5,30 +5,34 @@ const cachedImages: {
   image: HTMLImageElement;
 }[] = [];
 
-type TLoadImageProps = {
+/** Image loading options */
+export type TLoadImageProps = {
   /**
+   * Specifies the `crossOrigin` attribute for the image.
+   * Can be `null` or a string such as 'anonymous' or 'use-credentials'.
    * @default null
    */
   crossOrigin?: string | null;
   /**
+   * When set to `true`, the image will be cached in memory and will not be loaded again for subsequent requests.
    * @default false
    */
   useCache?: boolean;
 };
 
 /**
- * Load an image
+ * Loads an image from a given source, either a URL or an HTMLImageElement.
+ * Supports caching and handling cross-origin requests.
  *
  * @example
- *
  * const loaderWithoutCache = loadImage('/image.jpg');
- *
  * loaderWithoutCache.then((img) => console.log(img)).catch(() => {});
  *
  * const loaderWithCache = loadImage('/image.jpg', {
  *   crossOrigin: 'anonymous',
  *   useCache: true,
  * });
+ * loaderWithCache.then((img) => console.log(img)).catch(() => {});
  */
 export function loadImage(
   source: string | HTMLImageElement,
@@ -38,6 +42,7 @@ export function loadImage(
     crossOrigin: null,
     useCache: false,
   };
+
   const loadProps = {
     ...defaultLoadProps,
     ...props,

package/src/utils/image/pathsToProps.ts

@@ -15,17 +15,23 @@ export interface IImageAdaptivePaths<
 }
 
 /**
- * Transform image paths to properties
+ * Transforms image paths into properties for use in `src` and `srcSet` attributes.
+ * Supports adaptive images with WebP and fallback formats.
  *
- * @example
+ * Depending on WebP support, this function selects the most appropriate image for `src`
+ * and generates the `srcSet` if adaptive image sizes are provided.
  *
+ * @example
+ * // Basic usage with original, thumb, and thumbWebp paths
  * imagePathsToProps({
  *   original: '/original.jpg',
  *   thumb: '/thumb.jpg',
  *   thumbWebp: '/thumb.webp',
  * });
- * // => {"src":"/thumb.webp","srcSet":""}
+ * // => { src: '/thumb.webp', srcSet: '' }
  *
+ * @example
+ * // Usage with adaptive sizes for different screen widths
  * imagePathsToProps({
  *   original: '/original.jpg',
  *   thumb: '/thumb.jpg',
@@ -47,7 +53,7 @@ export interface IImageAdaptivePaths<
  *     2560: '/2560.webp',
  *   },
  * });
- * // => {"src":"/thumb.webp","srcSet":"/640.webp 640w, /750.webp 750w, /1024.webp 1024w, /1440.webp 1440w, /1920.webp 1920w, /2560.webp 2560w"}
+ * // => { src: '/thumb.webp', srcSet: '/640.webp 640w, /750.webp 750w, /1024.webp 1024w, /1440.webp 1440w, /1920.webp 1920w, /2560.webp 2560w' }
  */
 export function imagePathsToProps(data: IImagePaths | IImageAdaptivePaths) {
   const app = typeof window !== 'undefined' ? getApp() : undefined;

package/src/utils/image/sizesToSrcSet.ts

@@ -1,15 +1,19 @@
 /**
- * Transform image sizes to src set
+ * Transforms an object of image sizes into a `srcSet` string suitable for
+ * responsive images using the `srcSet` attribute.
  *
- * @example
+ * Each key in the `sizes` object represents a width in pixels, and the associated value is the image URL.
+ *
+ * @param {Record<string | number, string>} sizes - An object where the keys are widths (in pixels) and the values are URLs for the images.
+ * @returns {string} A `srcSet` string, where each image URL is followed by its width (e.g., "640w").
  *
+ * @example
  * imageSizesToSrcSet({
  *   640: '/640.jpg',
  *   750: '/750.jpg',
  *   1024: '/1024.jpg',
  *   1440: '/1440.jpg',
  * });
- *
  * // => "/640.jpg 640w, /750.jpg 750w, /1024.jpg 1024w, /1440.jpg 1440w"
  */
 export function imageSizesToSrcSet(sizes: Record<string | number, string>) {

package/src/utils/internal/getApp.ts

@@ -1,3 +1,28 @@
+import { Vevet } from '@/src/Vevet';
+import { IVevet } from '@/src/Vevet/global';
+import { IVevetProps } from '@/src/Vevet/types';
+
+declare global {
+  interface Window {
+    vevetApp: IVevet;
+    VEVET_PROPS: Partial<IVevetProps>;
+  }
+}
+
 export function getApp() {
+  if (!window.vevetApp) {
+    const appProps = window.VEVET_PROPS ?? {};
+
+    const app = Vevet(appProps);
+
+    window.vevetApp = app;
+  }
+
   return window.vevetApp;
 }
+
+if (typeof window !== 'undefined') {
+  // @ts-ignore
+  // eslint-disable-next-line no-underscore-dangle
+  window.__vevetAutoInitialize = getApp();
+}

package/src/utils/listeners/isIntersectionObserverSupported.ts

@@ -1,5 +1,5 @@
 /**
- * Check if intersection observer is supported
+ * Check if `IntersectionObserver` is supported
  */
 export function isIntersectionObserverSupported() {
   if (

package/src/utils/listeners/onResize.ts

@@ -1,8 +1,8 @@
-import { NViewport } from '@/src/Application/events/createViewport';
 import { NCallbacks } from '@/base/Callbacks';
 import { getApp } from '../internal/getApp';
+import { IViewportCallbackTypes } from '@/src/Vevet/events/createViewport/types';
 
-export type TOnResizeTarget = keyof NViewport.ICallbacksTypes;
+export type TOnResizeTarget = keyof IViewportCallbackTypes;
 
 export interface IOnResizeCallbackProps {
   trigger: 'unknown' | 'Viewport' | 'ResizeObserver';
@@ -17,13 +17,12 @@ export interface IOnResizeProps {
   element?: Element | Element[] | false;
   /**
    * Viewport target on resize.
-   * It will be used if `element` is not provided
-   * or `ResizeObserver` is not supported.
+   * It will be used if `element` is not provided or `ResizeObserver` is not supported.
    * @default 'any'
    */
   viewportTarget?: TOnResizeTarget;
   /**
-   * Has both `vewport resize` and `ResizeObserver`
+   * Has both `viewport` callbacks and `ResizeObserver`
    * @default false
    */
   hasBothEvents?: boolean;
@@ -46,9 +45,9 @@ export interface IOnResize {
 }
 
 /**
- * Add events on resize.
- * If `element` is provided, `ResizeObserver` will be used (first callback will not be fired).
- * Otherwise, viewport callbacks will be used.
+ * Adds resize event listeners to either an element (using `ResizeObserver`) or the viewport (using custom resize events).
+ * It handles debouncing and allows the removal of listeners when no longer needed.
+ * If both `element` and `hasBothEvents` are provided, both `ResizeObserver` and viewport resize events will be used.
  *
  * @example
  *
@@ -56,18 +55,18 @@ export interface IOnResize {
  *   onResize: () => console.log('resize'),
  *   element: document.getElementById('app')!,
  *   viewportTarget: 'any',
- *   hasBothEvents: true,   // trace both element and viewport sizes
+ *   hasBothEvents: true,   // Trace both element and viewport sizes
  *   resizeDebounce: 100,
  * });
  *
- * // resize with timeout called twice, but `onResize` will be called only once
+ * // Trigger resize with debounce
  * handler.debounceResize();
  * handler.debounceResize();
  *
- * // resize without timeout
+ * // Trigger resize without debounce
  * handler.resize();
  *
- * // remove listeners
+ * // Remove listeners
  * handler.remove();
  */
 export function onResize({
@@ -94,11 +93,7 @@ export function onResize({
     );
   };
 
-  if (
-    element &&
-    (element instanceof Element || Array.isArray(element)) &&
-    'ResizeObserver' in window
-  ) {
+  if (element && (element instanceof Element || Array.isArray(element))) {
     resizeObserver = new ResizeObserver(() => {
       if (isFirstResizeObserverCallback) {
         isFirstResizeObserverCallback = false;

package/src/utils/math/clamp.ts

@@ -1,18 +1,23 @@
 /**
- * Clamp the value between two points
+ * Clamp the value between two points.
+ * Ensures that `value` is between the minimum and maximum of the provided `scope`.
+ *
+ * @param value - The value to be clamped.
+ * @param scope - The range to clamp the value between, defaulting to [0, 1].
  *
  * @example
  *
  * clamp(1.5, [0.1, 0.9]); // => 0.9
  * clamp(0.001, [0.1, 0.9]); // => 0.1
+ * clamp(0.5, [0, 1]); // => 0.5
  */
-export function clamp(val: number, scope = [0, 1]) {
-  if (val < scope[0]) {
+export function clamp(value: number, scope = [0, 1]): number {
+  if (value < scope[0]) {
     return scope[0];
   }
-  if (val > scope[1]) {
+  if (value > scope[1]) {
     return scope[1];
   }
 
-  return val;
+  return value;
 }

package/src/utils/math/clampScope.ts

@@ -2,7 +2,14 @@ import { scoped } from './scoped';
 import { clamp } from './clamp';
 
 /**
- * Get progress relatively to the scope and clamp it within two points
+ * Get progress relative to a given scope and then clamp it within another range.
+ *
+ * The function first scales the `value` relative to `scopeProp` using the `scoped` function,
+ * and then clamps the result within `clampProp` using the `clamp` function.
+ *
+ * @param value - The value to be scaled and clamped.
+ * @param scopeProp - The scope within which the value will be scaled.
+ * @param clampProp - The range to clamp the scaled value within.
  *
  * @example
  *
@@ -13,6 +20,6 @@ export function clampScope(
   value: number,
   scopeProp = [0, 1],
   clampProp = [0, 1],
-) {
+): number {
   return clamp(scoped(value, scopeProp), clampProp);
 }

package/src/utils/math/easing.ts

@@ -41,7 +41,10 @@ export type {
 } from 'easing-progress';
 
 /**
- * Easing progress
+ * Calculates easing progress using a specified easing function, bezier curve, or custom easing function.
+ *
+ * @param progress - The current progress value (between 0 and 1).
+ * @param easingType - The easing type to apply. It can be a predefined easing function, a bezier array, or a custom easing function. Defaults to the global app's easing settings if available.
  *
  * @example
  *

package/src/utils/math/inScope.ts

@@ -1,5 +1,8 @@
 /**
- * Check if the value is within the scope
+ * Check if a given value is within a defined scope (inclusive of the scope's boundaries).
+ *
+ * @param value - The value to check.
+ * @param scopeValue - An array defining the range [min, max] where `value` should be compared against.
  *
  * @example
  *
@@ -8,6 +11,6 @@
  * inScope(2, [0, 1]); // => false
  * inScope(-1, [0, 1]); // => false
  */
-export function inScope(val: number, scopeValue = [0, 1]) {
-  return val >= scopeValue[0] && val <= scopeValue[1];
+export function inScope(value: number, scopeValue = [0, 1]) {
+  return value >= scopeValue[0] && value <= scopeValue[1];
 }

package/src/utils/math/lerp.ts

@@ -1,5 +1,13 @@
 /**
- * Linear interpolation
+ * Performs linear interpolation between the current and target values using an ease factor.
+ *
+ * Linear interpolation (LERP) calculates the intermediate value between two values (`current` and `target`)
+ * based on a given easing factor.
+ *
+ * @param current - The current value or starting point.
+ * @param target - The target value or end point.
+ * @param factor - The factor, typically between 0 and 1, which controls how fast the interpolation happens. A value closer to 0 makes the change slower, and a value closer to 1 makes it faster.
+ * @param approximationLeft - The threshold within which the difference between `current` and `target` is considered negligible, and the function returns the `target` value directly.
  *
  * @example
  *
@@ -9,10 +17,10 @@
 export function lerp(
   current: number,
   target: number,
-  ease: number,
+  factor: number,
   approximationLeft = 0.001,
 ) {
-  const value = current * (1 - ease) + target * ease;
+  const value = current * (1 - factor) + target * factor;
   const difference = Math.abs(target - value);
 
   if (difference <= approximationLeft) {

package/src/utils/math/normalizeNestedScope.ts

@@ -1,10 +1,19 @@
 /**
- * Cast scope value relative to global scope
+ * Normalizes a nested scope (`innerScope`) relative to a larger `globalScope`.
+ *
+ * This function calculates the relative position of an inner scope within a global scope,
+ * adjusting the inner scope's values based on the size and position of the global scope.
+ *
+ * @param innerScope - The scope that is nested within the global scope. This is a range [start, end] relative to the global scope.
+ * @param globalScope - The global scope or range [start, end] that the inner scope should be normalized to.
  *
  * @example
  *
- * normalizeNestedScope([0, 1], [0.1, 0.8]); // => [0.1, 0.8]
- * normalizeNestedScope([0.2, 0.9], [0.1, 0.8]); // => [0.24, 0.73]
+ * normalizeNestedScope([0, 1], [0.1, 0.8]);
+ * // => [0.1, 0.8] // No change, since innerScope matches the full globalScope
+ *
+ * normalizeNestedScope([0.2, 0.9], [0.1, 0.8]);
+ * // => [0.24, 0.73] // Adjusted to fit within globalScope [0.1, 0.8]
  */
 export function normalizeNestedScope(
   innerScope: [number, number] | number[],