vevet 4.4.2 → 5.0.1

package/src/base/index.ts

@@ -1,5 +1,3 @@
 export * from './Callbacks';
-export * from './Component';
 export * from './Module';
-export * from './MutableProps';
-export * from './Plugin';
+export * from './Responsive';

package/src/components/Canvas/index.ts

@@ -0,0 +1,229 @@
+import { TRequiredProps } from '@/internal/requiredProps';
+import { onResize } from '@/utils/listeners/onResize';
+import { Module } from '@/base/Module';
+import {
+  ICanvasCallbacksMap,
+  ICanvasMutableProps,
+  ICanvasStaticProps,
+  TCanvasRender,
+} from './types';
+import { initVevet } from '@/global/initVevet';
+
+export * from './types';
+
+/**
+ * A class for managing an HTML5 Canvas element and its 2D context.
+ *
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/Canvas)
+ *
+ * @group Components
+ */
+export class Canvas<
+  CallbacksMap extends ICanvasCallbacksMap = ICanvasCallbacksMap,
+  StaticProps extends ICanvasStaticProps = ICanvasStaticProps,
+  MutableProps extends ICanvasMutableProps = ICanvasMutableProps,
+> extends Module<CallbacksMap, StaticProps, MutableProps> {
+  /** Get default static properties */
+  public _getStatic(): TRequiredProps<StaticProps> {
+    return {
+      ...super._getStatic(),
+      container: null,
+      append: true,
+      resizeOnInit: true,
+      resizeOnRuntime: false,
+      viewportTarget: 'any',
+      resizeDebounce: 0,
+    } as TRequiredProps<StaticProps>;
+  }
+
+  /** Get default mutable properties */
+  public _getMutable(): TRequiredProps<MutableProps> {
+    return {
+      ...super._getMutable(),
+      width: 'auto',
+      height: 'auto',
+      dpr: 'auto',
+    } as TRequiredProps<MutableProps>;
+  }
+
+  /** The canvas element created for rendering */
+  protected _canvas: HTMLCanvasElement;
+
+  /** The canvas element instance. */
+  get canvas() {
+    return this._canvas;
+  }
+
+  /** The 2D rendering context. */
+  protected _ctx: CanvasRenderingContext2D;
+
+  /** Returns the 2D rendering context */
+  get ctx() {
+    return this._ctx;
+  }
+
+  /** The current width of the canvas, considering the device pixel ratio (DPR) */
+  protected _width: number;
+
+  /** Canvas width (DPR applied). */
+  get width() {
+    return this._width;
+  }
+
+  /** Width without DPR scaling. */
+  get offsetWidth() {
+    return this.width / this.dpr;
+  }
+
+  /** The current height of the canvas, considering the device pixel ratio (DPR) */
+  protected _height: number;
+
+  /** Canvas height (DPR applied). */
+  get height() {
+    return this._height;
+  }
+
+  /** Height without DPR scaling. */
+  get offsetHeight() {
+    return this.height / this.dpr;
+  }
+
+  /** The current device pixel ratio (DPR) */
+  protected _dpr: number;
+
+  /** Current device pixel ratio. */
+  get dpr() {
+    return this._dpr;
+  }
+
+  /** Checks if the canvas is ready to render. */
+  get canRender() {
+    return this.width > 0 && this.height > 0;
+  }
+
+  /**
+   * Constructor for the Ctx2D class.
+   */
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
+
+    const {
+      append: shouldAppend,
+      container,
+      resizeOnInit: hasResizeOnInit,
+      resizeOnRuntime: hasRuntimeResize,
+      viewportTarget,
+      resizeDebounce,
+    } = this.props;
+
+    // Set default values
+    this._width = 0;
+    this._height = 0;
+    this._dpr = 1;
+
+    // Create canvas element
+    this._canvas = document.createElement('canvas');
+
+    // Add canvas styles
+    const { style } = this._canvas;
+    style.position = 'absolute';
+    style.top = '0';
+    style.left = '0';
+    style.width = '100%';
+    style.height = '100%';
+
+    // Append canvas to container if required
+    if (shouldAppend && container instanceof HTMLElement) {
+      container.append(this._canvas);
+
+      this.onDestroy(() => this.canvas.remove());
+    }
+
+    // Create 2D context
+    this._ctx = this._canvas.getContext('2d')!;
+
+    // Set resize events
+    if (hasResizeOnInit) {
+      this.resize();
+    }
+
+    if (hasRuntimeResize) {
+      const resizeHandler = onResize({
+        callback: () => this.resize(),
+        element: this.props.container,
+        viewportTarget,
+        resizeDebounce,
+        name: this.name,
+      });
+
+      this.onDestroy(() => resizeHandler.remove());
+    }
+  }
+
+  /** Handle property mutations */
+  protected _handleProps() {
+    super._handleProps();
+
+    this.resize();
+  }
+
+  /** Triggers a canvas resize based on container or viewport dimensions. */
+  public resize() {
+    const core = initVevet();
+    const { props, canvas } = this;
+    const { container } = this.props;
+
+    // Calculate DPR
+    this._dpr = typeof props.dpr === 'number' ? props.dpr : core.dpr;
+
+    // Calculate new width and height
+    let newWidth = 0;
+    let newHeight = 0;
+
+    if (props.width === 'auto') {
+      newWidth = container?.offsetWidth || core.width;
+    } else {
+      newWidth = props.width;
+    }
+
+    if (props.height === 'auto') {
+      newHeight = container?.offsetHeight || core.height;
+    } else {
+      newHeight = props.height;
+    }
+
+    // Apply DPR
+    newWidth *= this._dpr;
+    newHeight *= this._dpr;
+
+    // Update canvas size
+    this._width = newWidth;
+    this._height = newHeight;
+    canvas.width = newWidth;
+    canvas.height = newHeight;
+
+    // Callbacks
+    this.callbacks.emit('resize', undefined);
+  }
+
+  /**
+   * Renders content on the canvas if it's ready.
+   *
+   * @param render - A function that performs the actual rendering on the canvas.
+   */
+  public render(render: TCanvasRender) {
+    if (!this.canRender) {
+      return;
+    }
+
+    render({
+      ctx: this.ctx,
+      width: this.width,
+      height: this.height,
+      dpr: this.dpr,
+      offsetWidth: this.offsetWidth,
+      offsetHeight: this.offsetHeight,
+      canvas: this.canvas,
+    });
+  }
+}

package/src/components/Canvas/types.ts

@@ -0,0 +1,125 @@
+import { IViewportCallbacksMap } from '@/core/exported';
+import {
+  IModuleCallbacksMap,
+  IModuleMutableProps,
+  IModuleStaticProps,
+} from '@/base/Module';
+
+/**
+ * Static properties for canvas configuration.
+ */
+export interface ICanvasStaticProps extends IModuleStaticProps {
+  /**
+   * Parent element used to determine canvas size. If `null`, it uses the viewport.
+   * @default null
+   */
+  container?: HTMLElement | null;
+
+  /**
+   * If `true`, appends the canvas to the `container`. Ignored if `container` is `null`.
+   * @default true
+   */
+  append?: boolean;
+
+  /**
+   * Automatically adjusts canvas size on initialization.
+   * @default true
+   */
+  resizeOnInit?: boolean;
+
+  /**
+   * Enables dynamic resizing based on viewport or container changes.
+   * @default false
+   */
+  resizeOnRuntime?: boolean;
+
+  /**
+   * Defines which dimension(s) should trigger a resize.
+   * @default 'any'
+   */
+  viewportTarget?: keyof IViewportCallbacksMap;
+
+  /**
+   * Debounce time (ms) for resize handling.
+   * @default 0
+   */
+  resizeDebounce?: number;
+}
+
+/**
+ * Mutable properties for canvas configuration.
+ */
+export interface ICanvasMutableProps extends IModuleMutableProps {
+  /**
+   * Canvas width. Use `'auto'` to match the container's width.
+   * @default 'auto'
+   */
+  width?: 'auto' | number;
+
+  /**
+   * Canvas height. Use `'auto'` to match the container's height.
+   * @default 'auto'
+   */
+  height?: 'auto' | number;
+
+  /**
+   * Device Pixel Ratio (DPR). Use `'auto'` for automatic detection.
+   * @default 'auto'
+   */
+  dpr?: 'auto' | number;
+}
+
+/**
+ * Event callbacks for canvas operations.
+ */
+export interface ICanvasCallbacksMap extends IModuleCallbacksMap {
+  /**
+   * Fires when the canvas is resized.
+   */
+  resize: undefined;
+}
+
+/**
+ * Arguments provided to the canvas render function.
+ */
+export interface ICanvasRenderArg {
+  /**
+   * 2D rendering context of the canvas.
+   */
+  ctx: CanvasRenderingContext2D;
+
+  /**
+   * Canvas width, adjusted for DPR.
+   */
+  width: number;
+
+  /**
+   * Canvas height, adjusted for DPR.
+   */
+  height: number;
+
+  /**
+   * Device pixel ratio used for rendering.
+   */
+  dpr: number;
+
+  /**
+   * Canvas offset width (before DPR adjustment).
+   */
+  offsetWidth: number;
+
+  /**
+   * Canvas offset height (before DPR adjustment).
+   */
+  offsetHeight: number;
+
+  /**
+   * HTMLCanvasElement associated with the canvas.
+   */
+  canvas: HTMLCanvasElement;
+}
+
+/**
+ * Function type for canvas rendering.
+ */
+export type TCanvasRender = (props: ICanvasRenderArg) => void;

package/src/components/CanvasMedia/index.ts

@@ -0,0 +1,140 @@
+import { getPos } from 'get-image-pos';
+import { TRequiredProps } from '@/internal/requiredProps';
+import {
+  ICanvasMediaCallbacksMap,
+  ICanvasMediaMutableProps,
+  ICanvasMediaStaticProps,
+} from './types';
+import { Canvas, ICanvasRenderArg } from '../Canvas';
+import { addEventListener } from '@/utils';
+
+export * from './types';
+
+/**
+ * The `CanvasMedia` class allows pre-rendering of media (such as images or video) onto a canvas.
+ * This can be useful for reducing payloads by preparing the media for further use in a more optimized form.
+ *
+ * [Documentation](https://antonbobrov.github.io/vevet/docs/components/CanvasMedia)
+ *
+ * @group Components
+ */
+export class CanvasMedia<
+  CallbacksMap extends ICanvasMediaCallbacksMap = ICanvasMediaCallbacksMap,
+  StaticProps extends ICanvasMediaStaticProps = ICanvasMediaStaticProps,
+  MutableProps extends ICanvasMediaMutableProps = ICanvasMediaMutableProps,
+> extends Canvas<CallbacksMap, StaticProps, MutableProps> {
+  /** Get default static properties */
+  public _getStatic(): TRequiredProps<StaticProps> {
+    return {
+      ...super._getStatic(),
+      autoRenderVideo: true,
+    } as TRequiredProps<StaticProps>;
+  }
+
+  /** Get default mutable properties */
+  public _getMutable(): TRequiredProps<MutableProps> {
+    return {
+      ...super._getMutable(),
+      rule: 'cover',
+    } as TRequiredProps<MutableProps>;
+  }
+
+  constructor(props?: StaticProps & MutableProps) {
+    super(props);
+
+    this._setMediaEvents();
+  }
+
+  /** Checks if the media element has the `requestVideoFrameCallback` method */
+  protected get hasRequestVideoFrameCallback() {
+    return 'requestVideoFrameCallback' in this.props.media;
+  }
+
+  /** Add media events */
+  protected _setMediaEvents() {
+    const { autoRenderVideo: hasVideoAutoRender, media } = this.props;
+
+    if (!hasVideoAutoRender || !(media instanceof HTMLVideoElement)) {
+      return;
+    }
+
+    // use requestVideoFrameCallback
+    if (this.hasRequestVideoFrameCallback) {
+      this._requestVideoFrame();
+
+      return;
+    }
+
+    // use timeupdate listener
+    const timeupdate = addEventListener(media, 'timeupdate', () => {
+      this.render();
+    });
+
+    this.onDestroy(() => timeupdate());
+  }
+
+  /** Resize the canvas */
+  public resize() {
+    super.resize();
+
+    this.render();
+  }
+
+  /** Auto rendering for videos */
+  protected _requestVideoFrame() {
+    if (this.isDestroyed) {
+      return;
+    }
+
+    this.render();
+
+    const { media } = this.props;
+
+    if (media instanceof HTMLVideoElement) {
+      media.requestVideoFrameCallback(() => this._requestVideoFrame());
+    }
+  }
+
+  /** Pre-renders the media resource onto the canvas. */
+  public render() {
+    super.render((props) => this._prerender(props));
+  }
+
+  /**
+   * Prerenders the media onto the canvas using the specified positioning rule.
+   */
+  protected _prerender({ width, height, ctx }: ICanvasRenderArg) {
+    const { media, rule } = this.props;
+
+    // Determine the media source and its dimensions
+    let source: Exclude<ICanvasMediaStaticProps['media'], Canvas>;
+    let sourceWidth: number | undefined;
+    let sourceHeight: number | undefined;
+
+    if (media instanceof Canvas) {
+      source = media.canvas;
+      sourceWidth = media.width;
+      sourceHeight = media.height;
+    } else {
+      source = media as any;
+    }
+
+    // Calculate media position and size based on the posRule
+    const size = getPos({
+      source,
+      sourceWidth,
+      sourceHeight,
+      rule,
+      scale: 1,
+      width,
+      height,
+    });
+
+    // Clear the canvas and draw the media with the calculated size
+    ctx.clearRect(0, 0, width, height);
+    ctx.drawImage(source, size.x, size.y, size.width, size.height);
+
+    // Trigger prerender callback
+    this.callbacks.emit('render', undefined);
+  }
+}

package/src/components/CanvasMedia/types.ts

@@ -0,0 +1,56 @@
+import { Canvas } from '../Canvas';
+import {
+  ICanvasCallbacksMap,
+  ICanvasMutableProps,
+  ICanvasStaticProps,
+} from '../Canvas/types';
+
+/**
+ * Static properties for the CanvasMedia class.
+ */
+export interface ICanvasMediaStaticProps extends ICanvasStaticProps {
+  /**
+   * The media element to be rendered.
+   * Accepts a Canvas instance or common media elements like images and videos.
+   */
+  media:
+    | Canvas
+    | HTMLImageElement
+    | SVGImageElement
+    | HTMLVideoElement
+    | HTMLCanvasElement;
+
+  /**
+   * If `true`, video elements will automatically render on each frame update.
+   * @default true
+   */
+  autoRenderVideo?: boolean;
+}
+
+/**
+ * Extended mutable properties for the CanvasMedia class.
+ */
+export interface ICanvasMediaMutableProps extends ICanvasMutableProps {
+  /**
+   * Defines how the media element is positioned within the canvas.
+   * @default 'cover'
+   */
+  rule?:
+    | 'cover'
+    | 'contain'
+    | 'top-left'
+    | 'top-right'
+    | 'bottom-left'
+    | 'bottom-right'
+    | 'center';
+}
+
+/**
+ * Extended callbacks map for the CanvasMedia class.
+ */
+export interface ICanvasMediaCallbacksMap extends ICanvasCallbacksMap {
+  /**
+   * Fires after the media element has been rendered onto the canvas.
+   */
+  render: undefined;
+}