feat: add VFXProps.zIndex (#80)

* feat: add VFXProps.zIndex

* chore: improve doc comments

Author: fand

packages/vfx-js/src/types.ts

@@ -42,7 +42,7 @@ export type VFXProps = {
     shader?: ShaderPreset | string;
 
     /**
-     * The release time for the element.
+     * The release time for the element. (Default: `0`)
      *
      * Basically, VFX-JS starts rendering the element when the element entered the viewport,
      * and it stops rendering after it got out of the viewport by scroll etc.
@@ -86,7 +86,7 @@ export type VFXProps = {
     uniforms?: VFXUniforms;
 
     /**
-     * The opacity for the original HTML element.
+     * The opacity for the original HTML element. (Default: `false`)
      *
      * By default, VFX-JS hides the original element by setting its opacity to 0.
      * However, in some cases you might want not to hide the original element.
@@ -100,7 +100,8 @@ export type VFXProps = {
     overlay?: true | number;
 
     /**
-     * Allow shader outputs to oveflow the original element area.
+     * Allow shader outputs to oveflow the original element area. (Default: `0`)
+     *
      * If true, REACT-VFX will render the shader in fullscreen.
      * If number is specified, REACT-VFX adds paddings with the given value.
      *
@@ -119,14 +120,23 @@ export type VFXProps = {
         | { top?: number; right?: number; bottom?: number; left?: number };
 
     /**
-     * Texture wrapping mode.
+     * Texture wrapping mode. (Default: `"repeat"`)
      *
      * You can pass a single value to specify both horizontal and vertical wrapping at once,
      * or you can provide a tuple to spefify different modes for horizontal / vertical wrapping.
      *
      * If not provided, VFX-JS will use "repeat" mode for both horizontal and vertical wrapping.
      */
     wrap?: VFXWrap | [VFXWrap, VFXWrap];
+
+    /**
+     * Z-index inside WebGL world. (Default: `0`)
+     *
+     * VFX-JS renders elements in ascending order by `zIndex`.
+     * For example, when we have elements with `zIndex: 1` and `zIndex: -1`, the second element is rendered first.
+     * When elements have the same `zIndex`, they are rendered in the order they were added.
+     */
+    zIndex?: number;
 };
 
 /**
@@ -176,6 +186,7 @@ export type VFXElement = {
     isGif: boolean;
     overflow: VFXElementOverflow;
     originalOpacity: number;
+    zIndex: number;
 };
 
 /**

packages/vfx-js/src/vfx-player.ts

@@ -284,9 +284,14 @@ export class VFXPlayer {
             isGif,
             overflow,
             originalOpacity,
+            zIndex: opts.zIndex ?? 0,
         };
 
+        // Insert element and sort elements by z-index.
+        // Array.prototype.sort is stable sort, so the elements with same z
+        // will be rendered by the order they are added to VFX.
         this.#elements.push(elem);
+        this.#elements.sort((a, b) => a.zIndex - b.zIndex);
     }
 
     removeElement(element: HTMLElement): void {