vevet 4.4.1 → 5.0.0

package/src/internal/requiredProps.ts

@@ -0,0 +1,47 @@
+interface IModuleLike {
+  prefix: string;
+  destroy: () => void;
+}
+
+declare type TPrimitive =
+  | string
+  | number
+  | boolean
+  | bigint
+  | symbol
+  | undefined
+  | null;
+
+declare type TBuiltin =
+  | TPrimitive
+  | Function
+  | Date
+  | Error
+  | RegExp
+  | Element
+  | Window
+  | IModuleLike;
+
+declare type TTRequiredProps<T> = T extends TBuiltin
+  ? NonNullable<T>
+  : T extends Map<infer K, infer V>
+    ? Map<TTRequiredProps<K>, TTRequiredProps<V>>
+    : T extends ReadonlyMap<infer K, infer V>
+      ? ReadonlyMap<TTRequiredProps<K>, TTRequiredProps<V>>
+      : T extends WeakMap<infer K, infer V>
+        ? WeakMap<TTRequiredProps<K>, TTRequiredProps<V>>
+        : T extends Set<infer U>
+          ? Set<TTRequiredProps<U>>
+          : T extends ReadonlySet<infer U>
+            ? ReadonlySet<TTRequiredProps<U>>
+            : T extends WeakSet<infer U>
+              ? WeakSet<TTRequiredProps<U>>
+              : T extends Promise<infer U>
+                ? Promise<TTRequiredProps<U>>
+                : T extends {}
+                  ? {
+                      [K in keyof T]-?: TTRequiredProps<T[K]>;
+                    }
+                  : NonNullable<T>;
+
+export declare type TRequiredProps<T> = TTRequiredProps<T>;

package/src/styles/index.scss

@@ -1,3 +1,32 @@
-@import './base';
+$vevet-sm: 899px !default;
+$vevet-md: 1199px !default;
 
-@import './components/index';
+@mixin vevet-lg () {
+  @media (min-width: ($vevet-md + 0.001)) {
+    @content;
+  }
+}
+
+@mixin vevet-md () {
+  @media (min-width: ($vevet-sm + 0.001)) and (max-width: $vevet-md) {
+    @content;
+  }
+}
+
+@mixin vevet-md-max () {
+  @media (max-width: $vevet-md) {
+    @content;
+  }
+}
+
+@mixin vevet-md-min () {
+  @media (min-width: ($vevet-sm + 0.001)) {
+    @content;
+  }
+}
+
+@mixin vevet-sm () {
+  @media (max-width: $vevet-sm) {
+    @content;
+  }
+}

package/src/utils/common/index.ts

@@ -1,3 +1,2 @@
-export * from './normalizedTimeoutCallback';
-export * from './PCancelable';
 export * from './uid';
+export * from './toPixels';

package/src/utils/common/toPixels.ts

@@ -0,0 +1,64 @@
+import { initVevet } from '@/global/initVevet';
+
+type TCache = Map<string | number, number>;
+
+declare global {
+  interface Window {
+    vevet5_toPixelsCache: TCache;
+  }
+}
+
+const isBrowser = typeof window !== 'undefined';
+
+/**
+ * Transform value to pixels. Supported units: `px` | 'rem' | 'vw' | 'vh' | 'svh'.
+ *
+ * @group Utils
+ *
+ * @example
+ * toPixels('100px'); // => 100
+ * toPixels('1vw'); // => 19.20
+ */
+export function toPixels(value: string | number) {
+  if (!isBrowser) {
+    return 0;
+  }
+  const app = initVevet();
+
+  if (!window.vevet5_toPixelsCache) {
+    window.vevet5_toPixelsCache = new Map();
+
+    app.onViewport(
+      'any',
+      () => {
+        window.vevet5_toPixelsCache.clear();
+      },
+      { name: 'toPixels' },
+    );
+  }
+
+  if (window.vevet5_toPixelsCache.has(value)) {
+    return window.vevet5_toPixelsCache.get(value)!;
+  }
+
+  let finalValue = 0;
+  const num = parseFloat(`${value}`);
+
+  if (typeof value === 'number') {
+    finalValue = value;
+  } else if (Number.isNaN(num)) {
+    finalValue = 0;
+  } else if (value.includes('rem')) {
+    finalValue = num * app.rem;
+  } else if (value.includes('vw')) {
+    finalValue = num * app.vw;
+  } else if (value.includes('vh')) {
+    finalValue = num * app.vh;
+  } else if (value.includes('svh')) {
+    finalValue = num * app.svh;
+  }
+
+  window.vevet5_toPixelsCache.set(value, finalValue);
+
+  return finalValue;
+}

package/src/utils/common/uid.ts

@@ -6,12 +6,14 @@ let index = 0;
  * 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.
  *
+ * @group Utils
+ *
  * @example
  * uid(); // => 'id_1'
  * uid('test'); // => 'test_2'
- * uid('0'); // => '0_3'
+ * uid(0); // => '0_3'
  */
-export function uid(prefix = 'id'): string {
+export function uid(prefix: string | number = 'id'): string {
   index += 1;
 
   return `${prefix}_${index}`;

package/src/utils/index.ts

@@ -1,5 +1,3 @@
 export * from './common';
-export * from './image';
 export * from './listeners';
 export * from './math';
-export * from './scroll';

package/src/utils/listeners/addEventListener.ts

@@ -0,0 +1,39 @@
+/**
+ * A utility function to add an event listener to a specified element.
+ *
+ * This function adds an event listener for the specified event type and
+ * returns a function that can be called to remove the event listener.
+ *
+ * @param element - The target element to which the event listener will be attached.
+ * @param target - The name of the event to listen for (e.g., 'click', 'scroll').
+ * @param listener - The callback function to execute when the event occurs.
+ * @param options - Optional parameters for the event listener.
+ *
+ * @group Utils
+ *
+ * @example
+ * const button = document.getElementById('myButton');
+ * const removeClickListener = addEventListener(button, 'click', (event) => {
+ *   console.log('Button clicked!');
+ * });
+ *
+ * // To remove the event listener later
+ * removeClickListener();
+ */
+export function addEventListener<
+  Target extends keyof HTMLElementEventMap,
+  Listener extends (event: DocumentEventMap[Target]) => void,
+>(
+  element: Document | Element | Window,
+  target: Target,
+  listener: Listener,
+  options?: boolean | AddEventListenerOptions,
+) {
+  element.addEventListener(target, listener as any, options);
+
+  const remove = () => {
+    element.removeEventListener(target, listener as any, options);
+  };
+
+  return remove;
+}

package/src/utils/listeners/index.ts

@@ -1,2 +1,3 @@
-export * from './isIntersectionObserverSupported';
+export * from './addEventListener';
+export * from './normalizeWheel';
 export * from './onResize';

package/src/utils/listeners/normalizeWheel.ts

@@ -0,0 +1,26 @@
+import normalizeWheelFunc from 'normalize-wheel';
+
+/**
+ * Normalize wheel delta. This function is re-exported from `normalize-wheel` for convenience.
+ * It helps normalize the wheel event's delta values (spinX, spinY, pixelX, pixelY) across different browsers.
+ *
+ * @see https://www.npmjs.com/package/normalize-wheel
+ *
+ * @group Utils
+ *
+ * @example
+ *
+ * document.addEventListener('wheel', (event) => {
+ *   const normalized = normalizeWheel(event);
+ *   console.log(normalized);
+ *   // => { spinX: -0, spinY: 1.25, pixelX: -0, pixelY: 125 }
+ * });
+ */
+export function normalizeWheel(event: WheelEvent) {
+  return normalizeWheelFunc(event);
+}
+
+/**
+ * Type definition for the normalized wheel event.
+ */
+export type TNormalizeWheel = ReturnType<typeof normalizeWheel>;

package/src/utils/listeners/onResize.ts

@@ -1,123 +1,119 @@
-import { NCallbacks } from '@/base/Callbacks';
-import { getApp } from '../internal/getApp';
-import { IViewportCallbackTypes } from '@/src/Vevet/events/createViewport/types';
+import { IViewportCallbacksMap } from '@/core/exported';
+import { initVevet } from '@/global/initVevet';
 
-export type TOnResizeTarget = keyof IViewportCallbackTypes;
-
-export interface IOnResizeCallbackProps {
-  trigger: 'unknown' | 'Viewport' | 'ResizeObserver';
-}
-
-export type TOnResizeCallback = (props: IOnResizeCallbackProps) => void;
+export type TOnResizeCallback = () => void;
 
 export interface IOnResizeProps {
-  /** Callback on resize */
-  onResize: TOnResizeCallback;
-  /** Observable element */
-  element?: Element | Element[] | false;
   /**
-   * Viewport target on resize.
-   * It will be used if `element` is not provided or `ResizeObserver` is not supported.
-   * @default 'any'
+   * Callback to invoke on resize.
    */
-  viewportTarget?: TOnResizeTarget;
+  callback: TOnResizeCallback;
+
+  /**
+   * Elements to observe for size changes. If null, only viewport events are used.
+   */
+  element?: Element | Element[] | null;
+
   /**
-   * Has both `viewport` callbacks and `ResizeObserver`
-   * @default false
+   * Target viewport property for resize events (enables viewport listeners).
    */
-  hasBothEvents?: boolean;
+  viewportTarget?: keyof IViewportCallbacksMap;
+
   /**
-   * Resize debounce timeout
+   * Debounce delay (ms) for resize events.
    * @default 0
    */
   resizeDebounce?: number;
+
+  /** Viewport callback name. Used for debugging */
+  name?: string;
 }
 
 export interface IOnResize {
-  /** Remove resize events */
+  /**
+   * Remove all resize listeners.
+   */
   remove: () => void;
-  /** Launch resize callback */
+
+  /**
+   * Trigger the resize callback immediately.
+   */
   resize: () => void;
-  /** Launch resize callback with debounce */
+
+  /**
+   * Trigger the resize callback with `resizeDebounce` delay.
+   */
   debounceResize: () => void;
-  /** `ResizeObserver` was used */
-  hasResizeObserver: boolean;
 }
 
 /**
- * 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.
+ * Adds resize listeners to elements (using `ResizeObserver`) and/or the viewport.
  *
- * @example
+ * @group Utils
  *
- * const handler = onResize({
- *   onResize: () => console.log('resize'),
- *   element: document.getElementById('app')!,
- *   viewportTarget: 'any',
- *   hasBothEvents: true,   // Trace both element and viewport sizes
- *   resizeDebounce: 100,
+ * @example
+ * const resizeWithElement = onResize({
+ *   callback: () => console.log('Element resized'),
+ *   element: document.getElementById('app'),
  * });
  *
- * // Trigger resize with debounce
- * handler.debounceResize();
- * handler.debounceResize();
- *
- * // Trigger resize without debounce
- * handler.resize();
+ * const resizeWithViewport = onResize({
+ *   callback: () => console.log('Viewport resized'),
+ *   viewportTarget: 'width',
+ * });
  *
- * // Remove listeners
- * handler.remove();
+ * const resizeWithBoth = onResize({
+ *   callback: () => console.log('Both resized'),
+ *   element: document.getElementById('app'),
+ *   viewportTarget: 'any',
+ * });
  */
 export function onResize({
-  onResize: handleResize,
+  callback,
   element,
-  viewportTarget = 'any',
-  hasBothEvents = false,
+  viewportTarget,
   resizeDebounce = 0,
+  name,
 }: IOnResizeProps): IOnResize {
+  const core = initVevet();
+
   let timeout: NodeJS.Timeout | undefined;
   let resizeObserver: ResizeObserver | undefined;
-  let isFirstResizeObserverCallback = true;
+  let isFirstObserverCallback = true;
 
-  let viewportCallback: NCallbacks.IAddedCallback | undefined;
+  let viewportCallback: (() => void) | undefined;
 
-  const debounceResize = (props?: IOnResizeCallbackProps, delay?: number) => {
+  const debounceResize = (delay?: number) => {
     if (timeout) {
       clearTimeout(timeout);
+      timeout = undefined;
     }
 
-    timeout = setTimeout(
-      () => handleResize(props ?? { trigger: 'unknown' }),
-      delay ?? resizeDebounce,
-    );
+    timeout = setTimeout(() => callback(), delay ?? resizeDebounce);
   };
 
-  if (element && (element instanceof Element || Array.isArray(element))) {
+  // Initialize ResizeObserver if element is provided
+  if (element) {
     resizeObserver = new ResizeObserver(() => {
-      if (isFirstResizeObserverCallback) {
-        isFirstResizeObserverCallback = false;
+      if (isFirstObserverCallback) {
+        isFirstObserverCallback = false;
 
         return;
       }
 
-      debounceResize(
-        { trigger: 'ResizeObserver' },
-        getApp().props.resizeDebounce + resizeDebounce,
-      );
+      debounceResize(core.props.resizeDebounce + resizeDebounce);
     });
 
-    if (Array.isArray(element)) {
-      element.forEach((item) => resizeObserver?.observe(item));
-    } else {
-      resizeObserver.observe(element);
-    }
+    (Array.isArray(element) ? element : [element]).forEach((el) => {
+      resizeObserver?.observe(el);
+    });
   }
 
-  if (hasBothEvents || !resizeObserver) {
-    viewportCallback = getApp().viewport.callbacks.add(viewportTarget, () =>
-      debounceResize({ trigger: 'Viewport' }),
-    );
+  // Attach viewport event listeners if specified
+  if (viewportTarget) {
+    viewportCallback = core.onViewport(viewportTarget, () => debounceResize(), {
+      name,
+    });
   }
 
   return {
@@ -127,10 +123,9 @@ export function onResize({
       }
 
       resizeObserver?.disconnect();
-      viewportCallback?.remove();
+      viewportCallback?.();
     },
-    resize: () => handleResize({ trigger: 'unknown' }),
+    resize: () => callback(),
     debounceResize: () => debounceResize(),
-    hasResizeObserver: !!resizeObserver,
   };
 }

package/src/utils/math/clamp.ts

@@ -1,23 +1,20 @@
 /**
- * Clamp the value between two points.
- * Ensures that `value` is between the minimum and maximum of the provided `scope`.
+ * Restricts a value to lie within a specified range.
  *
- * @param value - The value to be clamped.
- * @param scope - The range to clamp the value between, defaulting to [0, 1].
+ * Ensures that `value` is no less than `min` and no greater than `max`.
  *
- * @example
+ * @param {number} value - The input value to be clamped.
+ * @param {number} [min=0] - The lower bound of the range (default is 0).
+ * @param {number} [max=1] - The upper bound of the range (default is 1).
+ * @returns {number} - The clamped value within the range [min, max].
+ *
+ * @group Utils
  *
- * 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
+ * @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(value: number, scope = [0, 1]): number {
-  if (value < scope[0]) {
-    return scope[0];
-  }
-  if (value > scope[1]) {
-    return scope[1];
-  }
-
-  return value;
+export function clamp(value: number, min = 0, max = 1) {
+  return Math.max(min, Math.min(value, max));
 }

package/src/utils/math/clampScope.ts

@@ -1,25 +1,29 @@
 import { scoped } from './scoped';
-import { clamp } from './clamp';
+import { clamp as clampFunc } from './clamp';
 
 /**
- * Get progress relative to a given scope and then clamp it within another range.
+ * Maps a value to a relative range and clamps the result 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.
+ * This function first calculates the relative progress of `value` within `scope`
+ * using the `scoped` function. Then, it clamps the resulting progress to `clamp`
+ * 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.
+ * @param {number} value - The input value to be mapped and clamped.
+ * @param {[number, number]} [scope=[0, 1]] - The range (start and end) within which to map the input value.
+ * @param {[number, number]} [clamp=[0, 1]] - The range (start and end) within which to clamp the mapped value.
+ * @returns {number} - The resulting value after mapping and clamping.
+ *
+ * @group Utils
  *
  * @example
+ * clampScope(0.36, [0.35, 1]);
+ * // => 0.015384 (relative progress of 0.36 within [0.35, 1], clamped to [0, 1])
  *
- * clampScope(0.38, [0.35, 1]); // => 0.046
- * clampScope(0.38, [0.35, 1], [0.1, 1]); // => 0.1
+ * clampScope(0.36, [0.35, 1], [0.1, 1]);
+ * // => 0.1 (relative progress of 0.36 within [0.35, 1], clamped to [0.1, 1])
  */
-export function clampScope(
-  value: number,
-  scopeProp = [0, 1],
-  clampProp = [0, 1],
-): number {
-  return clamp(scoped(value, scopeProp), clampProp);
+export function clampScope(value: number, scope = [0, 1], clamp = [0, 1]) {
+  const scopedProgress = scoped(value, scope[0], scope[1]);
+
+  return clampFunc(scopedProgress, clamp[0], clamp[1]);
 }

package/src/utils/math/damp.ts

@@ -0,0 +1,29 @@
+import { lerp } from './lerp';
+
+/**
+ * Linear interpolation with factor based on user's FPS.
+ *
+ * {@link http://www.rorydriscoll.com/2016/03/07/frame-rate-independent-damping-using-lerp/}
+ *
+ * @group Utils
+ *
+ * @param {number} current - The starting value.
+ * @param {number} target - The end value.
+ * @param {number} factor - The interpolation factor, typically between 0 and 1. A lower value results in slower interpolation, while a higher value makes it faster.
+ * @param {number} delta - Time elapsed since the last update in milliseconds
+ * @param {number} [approximation=0] - A small threshold to determine when the difference between the interpolated value and the target is negligible. If the difference is within this threshold, the function returns `target` directly.
+ */
+export function damp(
+  current: number,
+  target: number,
+  factor: number,
+  delta: number,
+  approximation = 0,
+) {
+  return lerp(
+    current,
+    target,
+    1 - Math.exp(-factor * 60 * (delta / 1000)),
+    approximation,
+  );
+}

package/src/utils/math/easing.ts

@@ -1,5 +1,4 @@
 import { easing as easingProgress } from 'easing-progress';
-import { getApp } from '../internal/getApp';
 
 export {
   EaseInBack,
@@ -41,18 +40,29 @@ export type {
 } from 'easing-progress';
 
 /**
- * Calculates easing progress using a specified easing function, bezier curve, or custom easing function.
+ * Applies an easing function to a given progress value.
  *
- * @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.
+ * This function calculates eased progress using a specified easing function,
+ * bezier curve, or custom easing function.
+ *
+ * @param {number} progress - The current progress value, typically between 0 and 1.
+ * @param {TEasingType} easingType - The easing method to apply. It can be:
+ *   - A predefined easing function (e.g., `EaseInBounce`).
+ *   - A bezier array (e.g., `[0.25, 0.1, 0.25, 1]`).
+ *   - A custom easing function (e.g., `(value) => Math.sin(Math.PI * 0.5 * value)`).
+ * @returns {number} - The eased progress value.
+ *
+ * @group Utils
  *
  * @example
+ * easing(0.35, EaseInBounce);
+ * // => 0.167 (eased progress using EaseInBounce)
+ *
+ * easing(0.35, [0.25, 0.1, 0.25, 1]);
+ * // => 0.604 (eased progress using a bezier curve)
  *
- * easing(0.35, EaseInBounce); // => 0.167
- * easing(0.35, [.25, .1, .25, 1]); // => 0.604
- * easing(0.35, (value) => Math.sin(Math.PI * 0.5 * value)); // => 0.522
+ * easing(0.35, (value) => Math.sin(Math.PI * 0.5 * value));
+ * // => 0.522 (eased progress using a custom easing function)
  */
-export const easing: typeof easingProgress = (
-  progress,
-  easingType = getApp()?.props.easing ?? false,
-) => easingProgress(progress, easingType);
+export const easing: typeof easingProgress = (progress, easingType) =>
+  easingProgress(progress, easingType);

package/src/utils/math/inRange.ts

@@ -0,0 +1,29 @@
+/**
+ * Determines if a value lies within a specified range (inclusive of the range boundaries).
+ *
+ * @param {number} value - The value to check.
+ * @param {number} [min=0] - The minimum boundary of the range.
+ * @param {number} [max=1] - The maximum boundary of the range.
+ * @returns {boolean} - `true` if the value is within the range (inclusive), otherwise `false`.
+ *
+ * @group Utils
+ *
+ * @example
+ * inScope(0, 0, 1);
+ * // => true (0 is within the range [0, 1])
+ *
+ * inScope(1, 0, 1);
+ * // => true (1 is within the range [0, 1])
+ *
+ * inScope(2, 0, 1);
+ * // => false (2 is outside the range [0, 1])
+ *
+ * inScope(-1, 0, 1);
+ * // => false (-1 is outside the range [0, 1])
+ */
+export function inRange(value: number, min = 0, max = 1): boolean {
+  const realMin = Math.min(min, max);
+  const realMax = Math.max(min, max);
+
+  return value >= realMin && value <= realMax;
+}

package/src/utils/math/index.ts

@@ -1,9 +1,8 @@
 export * from './clamp';
 export * from './clampScope';
+export * from './damp';
 export * from './easing';
-export * from './inScope';
+export * from './inRange';
 export * from './lerp';
-export * from './normalizeNestedScope';
 export * from './scoped';
-export * from './spreadScope';
-export * from './wrap';
+export * from './loop';