vevet 2.17.0 → 3.0.0-beta.1

package/src/base/Module/index.ts

@@ -0,0 +1,324 @@
+import {
+  addEventListener,
+  IAddEventListener,
+  IAddEventListenerOptions,
+  ListenerElement,
+} from 'vevet-dom';
+import { DeepRequired } from 'ts-essentials';
+import { NModule } from './types';
+import { MutableProps, NMutableProps } from '../MutableProps';
+import { Callbacks, NCallbacks } from '../Callbacks';
+import { mergeWithoutArrays } from '@/utils/common';
+import { Viewport } from '@/src/Application/events/Viewport';
+import { TRequiredModuleProp } from '@/types/utility';
+
+export type { NModule };
+
+type TViewportAdd = Viewport['add'];
+
+/**
+ * Module base
+ */
+export class Module<
+  StaticProps extends NModule.IStaticProps = NModule.IStaticProps,
+  ChangeableProps extends NModule.IChangeableProps = NModule.IChangeableProps,
+  CallbacksTypes extends NModule.ICallbacksTypes = NModule.ICallbacksTypes
+> {
+  /**
+   * Get Default properties (should be extended)
+   */
+  protected _getDefaultProps() {
+    return { parent: null } as DeepRequired<StaticProps & ChangeableProps>;
+  }
+
+  /** Current properties */
+  get props() {
+    return this._mutableProps.props as TRequiredModuleProp<
+      StaticProps & ChangeableProps
+    >;
+  }
+
+  /** Responsive properties */
+  private _mutableProps: MutableProps<StaticProps, ChangeableProps>;
+
+  /** Module Callbacks */
+  private _callbacks: Callbacks<CallbacksTypes>;
+
+  /** Module Callbacks */
+  get callbacks() {
+    return this._callbacks;
+  }
+
+  /** Module listeners */
+  private _listeners: IAddEventListener[];
+
+  /**
+   * Destroyable actions
+   */
+  private _destroyableActions: (() => void)[];
+
+  /**
+   * Classnames to remove
+   */
+  private _classNamesToRemove: NModule.IClassNamesToRemove[];
+
+  /** Vevet Application */
+  private _app!: typeof window.vevetApp;
+
+  /** Vevet Application */
+  get app() {
+    return this._app;
+  }
+
+  /** Module name */
+  get name() {
+    return this.constructor.name;
+  }
+
+  /** Module prefix */
+  get prefix() {
+    return '';
+  }
+
+  /** The module is initialized */
+  private _isInitialized = false;
+
+  /** The module is initialized */
+  get isInitialized() {
+    return this._isInitialized;
+  }
+
+  /** The module is destroyed */
+  private _isDestroyed = false;
+
+  /** The module is 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'));
+   */
+  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
+  ) {
+    if (window.vevetApp) {
+      this._app = window.vevetApp;
+    } else {
+      throw new Error(
+        'Vevet.Application does not exist yet. Call "new Vevet.Application()" before using all the stuff'
+      );
+    }
+
+    this._callbacks = new Callbacks<CallbacksTypes>();
+    this._listeners = [];
+    this._destroyableActions = [];
+    this._classNamesToRemove = [];
+
+    const props = mergeWithoutArrays(
+      this._getDefaultProps(),
+      initialProps || {}
+    );
+
+    this._mutableProps = new MutableProps(
+      props as StaticProps & ChangeableProps,
+      () => this._onPropsMutate(),
+      this.name
+    );
+
+    if (canInit) {
+      this.init();
+    }
+  }
+
+  /** Add responsive rules */
+  public addResponsiveProps(rules: NMutableProps.IResponsive<ChangeableProps>) {
+    if (this.isInitialized) {
+      throw new Error(
+        'Responsive properties cannot be added after `init` is called'
+      );
+    } else {
+      this._mutableProps.addResponsiveProps(rules);
+    }
+  }
+
+  /** Change module properties */
+  public changeProps(props: Partial<ChangeableProps>) {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    this._mutableProps.changeProps(props);
+
+    this._callbacks.tbt('propsChange', undefined);
+  }
+
+  /**
+   * This method is called on properties change
+   */
+  protected _onPropsMutate() {
+    this._callbacks.tbt('propsMutate', undefined);
+  }
+
+  /** Initializes the class */
+  public init() {
+    if (this.isInitialized) {
+      return;
+    }
+
+    this._isInitialized = true;
+
+    this._init();
+
+    // destroy the current module on parent destroy
+    if (this.props.parent) {
+      this.props.parent.addCallback('destroy', () => this.destroy(), {
+        isProtected: true,
+        name: this.name,
+      });
+    }
+  }
+
+  /** Inner extra initialization */
+  protected _init() {}
+
+  /** Add destroyable actions */
+  protected addDestroyableAction(action: () => void) {
+    this._destroyableActions.push(action);
+  }
+
+  /**
+   * Add a viewport callback that will be removed on class destroy
+   */
+  public addViewportCallback(
+    target: Parameters<TViewportAdd>[0],
+    action: Parameters<TViewportAdd>[1],
+    data: Parameters<TViewportAdd>[2] = {}
+  ) {
+    const callback = this._app.viewport.add(target, action, {
+      ...data,
+      name: this.constructor.name,
+    });
+
+    this.addDestroyableAction(() => callback.remove());
+  }
+
+  /** Add a module callback */
+  public addCallback<T extends keyof CallbacksTypes>(
+    target: T,
+    action: NCallbacks.TAction<CallbacksTypes[T]>,
+    settings: NCallbacks.ISettings = {}
+  ) {
+    return this.callbacks.add(target, action, settings);
+  }
+
+  /** Add a DOM event listener */
+  public addEventListener<
+    El extends ListenerElement,
+    Target extends keyof HTMLElementEventMap,
+    Callback extends (evt: HTMLElementEventMap[Target]) => void
+  >(
+    el: El,
+    target: Target,
+    callback: Callback,
+    options?: IAddEventListenerOptions
+  ): IAddEventListener {
+    const listener = addEventListener(el, target, callback, options);
+    this._listeners.push(listener);
+
+    return {
+      ...listener,
+      remove: () => {
+        this._listeners = this._listeners.filter(
+          (item) => item.id !== listener.id
+        );
+
+        return listener.remove();
+      },
+    };
+  }
+
+  protected className(...classNames: string[]) {
+    return classNames.map((value) => `${this.prefix}${value}`).join(' ');
+  }
+
+  /** Toggle classList */
+  protected toggleClassName(
+    element: Element,
+    className: string,
+    isActive: boolean
+  ) {
+    const isAlreadyExists = element.classList.contains(className);
+
+    element.classList.toggle(className, isActive);
+
+    if (!isAlreadyExists) {
+      this._classNamesToRemove.push({ element, className });
+    }
+  }
+
+  /** Destroy the module */
+  public destroy() {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    this._destroy();
+  }
+
+  /** Destroy the module */
+  protected _destroy() {
+    this._callbacks.tbt('destroy', undefined);
+    this._callbacks.destroy();
+
+    this._mutableProps.destroy();
+
+    this._destroyableActions.forEach((action) => action());
+    this._listeners.forEach((listener) => listener.remove());
+
+    this._classNamesToRemove.forEach(({ element, className }) =>
+      element.classList.remove(className)
+    );
+
+    this._isDestroyed = true;
+  }
+}

package/src/base/Module/stories/index.stories.tsx

@@ -0,0 +1,13 @@
+import type { StoryObj, Meta } from '@storybook/react';
+import { Component } from '.';
+
+type TComponent = typeof Component;
+
+const meta: Meta<TComponent> = {
+  title: 'Base/Module',
+  component: Component,
+};
+
+export default meta;
+
+export const Default: StoryObj<TComponent> = {};

package/src/base/Module/stories/index.tsx

@@ -0,0 +1,71 @@
+import React, { FC, useEffect, useState } from 'react';
+import { Module, NModule } from '..';
+
+interface IStaticProps extends NModule.IStaticProps {
+  staticName: 'My name';
+}
+
+interface IChangeableProps extends NModule.IChangeableProps {
+  weight: number;
+  height: number;
+}
+
+interface ICallbacks extends NModule.ICallbacksTypes {}
+
+export const Component: FC = () => {
+  const [features, setFeatures] = useState<any>({});
+
+  useEffect(() => {
+    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();
+    setFeatures(module.props);
+
+    module.addCallback('propsChange', () => {
+      // eslint-disable-next-line no-console
+      console.log('change props');
+
+      setFeatures({ ...module.props });
+    });
+
+    module.addCallback('propsMutate', () => {
+      // eslint-disable-next-line no-console
+      console.log('mutate props');
+
+      setFeatures({ ...module.props });
+    });
+
+    const timeout = setTimeout(() => {
+      module.changeProps({ weight: 90 });
+    }, 2500);
+
+    return () => {
+      module.destroy();
+      clearTimeout(timeout);
+    };
+  }, []);
+
+  return (
+    <div>
+      {Object.entries(features).map(([key, value]) => (
+        <div key={key}>
+          {key}: {String(value)}
+        </div>
+      ))}
+    </div>
+  );
+};

package/src/base/Module/types.ts

@@ -0,0 +1,26 @@
+import { NCallbacks } from '../Callbacks/types';
+
+export namespace NModule {
+  /**
+   * Mutable Properties (may change on window resize or through {@linkcode Module.changeProps})
+   */
+  export interface IChangeableProps {}
+
+  /** Static properties */
+  export interface IStaticProps {
+    /** Parent module */
+    parent?: any;
+  }
+
+  /** Available callbacks */
+  export interface ICallbacksTypes extends NCallbacks.ITypes {
+    destroy: undefined;
+    propsChange: undefined;
+    propsMutate: undefined;
+  }
+
+  export interface IClassNamesToRemove {
+    element: Element;
+    className: string;
+  }
+}

package/src/base/MutableProps/index.ts

@@ -0,0 +1,232 @@
+import { mergeWithoutArrays } from '@/utils/common';
+import { NCallbacks } from '../Callbacks/types';
+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}.
+ *
+ * @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>
+> {
+  /**
+   * Vevet Application.
+   */
+  private _app: typeof window.vevetApp;
+
+  /**
+   * Reference properties.
+   * These properties may change only through {@linkcode MutableProps.changeProps}.
+   */
+  private _refProps: StaticProps & ChangeableProps;
+
+  /**
+   * Current properties.
+   * These properties may change both on {@linkcode MutableProps.changeProps} and resize.
+   */
+  private _props: StaticProps & ChangeableProps;
+
+  /**
+   * A set of responsive rules
+   */
+  private _responsiveRules: NMutableProps.IResponsive<ChangeableProps>[] = [];
+
+  /**
+   * Get current properties
+   */
+  get props() {
+    return this._props;
+  }
+
+  /**
+   * Viewport callback
+   */
+  private _viewportCallback?: NCallbacks.IAddedCallback;
+
+  /**
+   * Active breakpoints used to define if properties have changed
+   */
+  private _activeBreakpoints: (string | number)[];
+
+  /**
+   * @example
+   *
+   * const static = {
+   *   myProp: true,
+   * };
+   *
+   * const responsive = [
+   *   {
+   *     breakpoint: 'm',
+   *     settings: {
+   *       myProp: false
+   *     }
+   *   }
+   * ];
+   *
+   * const props = new MutableProps(static, responsive);
+   */
+  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
+     */
+    private _onMutate: () => void = () => {},
+    /**
+     * Name of the responsive properties.
+     */
+    private _name = 'Responsive Props'
+  ) {
+    this._app = window.vevetApp;
+    this._refProps = mergeWithoutArrays({}, _initProps);
+    this._props = mergeWithoutArrays({}, _initProps);
+
+    this._activeBreakpoints = [];
+  }
+
+  /**
+   * Add responsive rules
+   */
+  public addResponsiveProps(rules: NMutableProps.IResponsive<ChangeableProps>) {
+    this._responsiveRules.push(rules);
+
+    this._responseProps();
+
+    if (typeof this._viewportCallback !== 'undefined') {
+      return;
+    }
+
+    this._viewportCallback = this._app.viewport.add(
+      'width',
+      this._responseProps.bind(this),
+      { name: this._name }
+    );
+  }
+
+  /**
+   * Change properties according to the "responsive" settings
+   */
+  private _responseProps() {
+    const app = this._app;
+    const { viewport } = app;
+
+    let newProps: (StaticProps & ChangeableProps) | false = false;
+    const statProp = mergeWithoutArrays({}, this._refProps);
+
+    const prevActiveBreakpointsString = [...this._activeBreakpoints].join('_');
+    this._activeBreakpoints = [];
+
+    // go through all breakpoints
+    // and check if a proper breakpoint exists
+    this._responsiveRules.forEach(({ settings, breakpoint }) => {
+      if (typeof breakpoint === 'number') {
+        if (viewport.width <= breakpoint) {
+          this._activeBreakpoints.push(breakpoint);
+          newProps = mergeWithoutArrays(statProp, settings);
+        }
+      } else if (typeof breakpoint === 'string') {
+        // viewport size
+        if (
+          (breakpoint === 'viewport_desktop' && viewport.isDesktop) ||
+          (breakpoint === 'viewport_tablet' && viewport.isTablet) ||
+          (breakpoint === 'viewport_phone' && viewport.isPhone)
+        ) {
+          this._activeBreakpoints.push(breakpoint);
+          newProps = mergeWithoutArrays(statProp, settings);
+        }
+
+        // device type
+        if (
+          (breakpoint === 'device_phone' && app.isPhone) ||
+          (breakpoint === 'device_tablet' && app.isTablet) ||
+          (breakpoint === 'device_mobile' && app.isMobile)
+        ) {
+          this._activeBreakpoints.push(breakpoint);
+          newProps = mergeWithoutArrays(statProp, settings);
+        }
+      }
+    });
+
+    // check if properties really changed
+    const activeBreakpointsString = this._activeBreakpoints.join('_');
+    const isPropsChanged =
+      activeBreakpointsString !== prevActiveBreakpointsString;
+
+    // if there's no breakpoint, restore the props
+    if (!newProps) {
+      this._props = mergeWithoutArrays(this._props, this._refProps);
+    } else {
+      // otherwise, change the properties
+      this._props = mergeWithoutArrays(this._props, newProps);
+    }
+
+    // callback
+    if (isPropsChanged) {
+      this._onMutate();
+    }
+  }
+
+  /**
+   * This method allows you to change the properties manually.
+   */
+  public changeProps(props: Partial<ChangeableProps>) {
+    this._props = mergeWithoutArrays(this._props, props);
+    this._refProps = mergeWithoutArrays(this._refProps, props);
+
+    this._onMutate();
+  }
+
+  /**
+   * Destroy the responsive properties.
+   */
+  public destroy() {
+    if (this._viewportCallback) {
+      this._viewportCallback.remove();
+    }
+  }
+}

package/src/base/MutableProps/stories/index.stories.tsx

@@ -0,0 +1,13 @@
+import type { StoryObj, Meta } from '@storybook/react';
+import { Component } from '.';
+
+type TComponent = typeof Component;
+
+const meta: Meta<TComponent> = {
+  title: 'Base/MutableProps',
+  component: Component,
+};
+
+export default meta;
+
+export const Default: StoryObj<TComponent> = {};