@egjs/flicking-plugins 4.8.0-beta.1 → 4.8.1-beta.0

package/src/AutoPlay.ts

@@ -1,18 +1,44 @@
-import Flicking, { EVENTS, Plugin, DIRECTION, MOVE_TYPE } from "@egjs/flicking";
+import Flicking, { DIRECTION, EVENTS, MOVE_TYPE, Plugin } from "@egjs/flicking";
 
-interface AutoPlayOptions {
+/**
+ * Options for the {@link AutoPlay} plugin
+ */
+export interface AutoPlayOptions {
+  /**
+   * Time to wait before moving on to the next panel (ms)
+   * @defaultValue 2000
+   */
   duration: number;
+  /**
+   * Duration of the panel move animation (ms). If `undefined`, the Flicking instance's `duration` is used
+   * @defaultValue undefined
+   */
   animationDuration: number | undefined;
-  direction: typeof DIRECTION["NEXT"] | typeof DIRECTION["PREV"];
+  /**
+   * The direction in which the panel moves
+   * @defaultValue "NEXT"
+   */
+  direction: (typeof DIRECTION)["NEXT"] | (typeof DIRECTION)["PREV"];
+  /**
+   * Whether to stop when the mouse hovers over the element
+   * @defaultValue false
+   */
   stopOnHover: boolean;
+  /**
+   * Whether to stop autoplay when the plugin is first initialized
+   * @defaultValue false
+   */
   stopOnInit: boolean;
+  /**
+   * If `stopOnHover` is true, time to wait before resuming after mouse leaves (ms)
+   * @defaultValue Same as `duration`
+   */
   delayAfterHover: number;
 }
 
 /**
- * Plugin that allow you to automatically move to the next/previous panel, on a specific time basis
- * @ko 일정 시간마다, 자동으로 다음/이전 패널로 넘어가도록 할 수 있는 플러그인
- * @memberof Flicking.Plugins
+ * Plugin that allows you to automatically move to the next/previous panel on a specific time basis
+ * @see {@link https://naver.github.io/egjs-flicking/docs/demos/plugins/autoplay | Demo: AutoPlay}
  */
 class AutoPlay implements Plugin {
   /* Options */
@@ -29,42 +55,79 @@ class AutoPlay implements Plugin {
   private _mouseEntered = false;
   private _playing = false;
 
-  public get duration() { return this._duration; }
-  public get animationDuration() { return this._animationDuration; }
-  public get direction() { return this._direction; }
-  public get stopOnHover() { return this._stopOnHover; }
-  public get stopOnInit() { return this._stopOnInit; }
-  public get delayAfterHover() { return this._delayAfterHover; }
-  public get playing() { return this._playing; }
-
-  public set duration(val: number) { this._duration = val; }
-  public set animationDuration(val: number | undefined) { this._animationDuration = val; }
-  public set direction(val: AutoPlayOptions["direction"]) { this._direction = val; }
-  public set stopOnHover(val: boolean) { this._stopOnHover = val; }
-  public set stopOnInit(val: boolean) { this._stopOnInit = val; }
-  public set delayAfterHover(val: number) { this._delayAfterHover = val; }
+  /** Current value of the {@link AutoPlayOptions.duration | duration} option. */
+  public get duration() {
+    return this._duration;
+  }
+  /** Current value of the {@link AutoPlayOptions.animationDuration | animationDuration} option. */
+  public get animationDuration() {
+    return this._animationDuration;
+  }
+  /** Current value of the {@link AutoPlayOptions.direction | direction} option. */
+  public get direction() {
+    return this._direction;
+  }
+  /** Current value of the {@link AutoPlayOptions.stopOnHover | stopOnHover} option. */
+  public get stopOnHover() {
+    return this._stopOnHover;
+  }
+  /** Current value of the {@link AutoPlayOptions.stopOnInit | stopOnInit} option. */
+  public get stopOnInit() {
+    return this._stopOnInit;
+  }
+  /** Current value of the {@link AutoPlayOptions.delayAfterHover | delayAfterHover} option. */
+  public get delayAfterHover() {
+    return this._delayAfterHover;
+  }
+  /** Whether the autoplay is currently active
+   * @readonly
+   */
+  public get playing() {
+    return this._playing;
+  }
+
+  /** Sets {@link AutoPlayOptions.duration | duration}. */
+  public set duration(val: number) {
+    this._duration = val;
+  }
+  /** Sets {@link AutoPlayOptions.animationDuration | animationDuration}. */
+  public set animationDuration(val: number | undefined) {
+    this._animationDuration = val;
+  }
+  /** Sets {@link AutoPlayOptions.direction | direction}. */
+  public set direction(val: AutoPlayOptions["direction"]) {
+    this._direction = val;
+  }
+  /** Sets {@link AutoPlayOptions.stopOnHover | stopOnHover}. */
+  public set stopOnHover(val: boolean) {
+    this._stopOnHover = val;
+  }
+  /** Sets {@link AutoPlayOptions.stopOnInit | stopOnInit}. */
+  public set stopOnInit(val: boolean) {
+    this._stopOnInit = val;
+  }
+  /** Sets {@link AutoPlayOptions.delayAfterHover | delayAfterHover}. */
+  public set delayAfterHover(val: number) {
+    this._delayAfterHover = val;
+  }
 
   /**
-   * @param {AutoPlayOptions} options Options for the AutoPlay instance.<ko>AutoPlay 옵션</ko>
-   * @param {number} options.duration Time to wait before moving on to the next panel.<ko>다음 패널로 움직이기까지 대기 시간</ko>
-   * @param {number | undefined} options.animationDuration Duration of animation of moving to the next panel. If undefined, duration option of the Flicking instance is used instead.<ko>패널이 움직이는 애니메이션의 지속 시간, undefined라면 Flicking 인스턴스의 duration 값을 사용한다</ko>
-   * @param {"PREV" | "NEXT"} options.direction The direction in which the panel moves.<ko>패널이 움직이는 방향</ko>
-   * @param {boolean} options.stopOnHover Whether to stop when mouse hover upon the element.<ko>엘리먼트에 마우스를 올렸을 때 AutoPlay를 정지할지 여부</ko>
-   * @param {boolean} options.stopOnInit Whether to stop when mouse hover upon the element.<ko>엘리먼트에 마우스를 올렸을 때 AutoPlay를 정지할지 여부</ko>
-   * @param {number} options.delayAfterHover If stopOnHover is true, the amount of time to wait before moving on to the next panel when mouse leaves the element.<ko>stopOnHover를 사용한다면 마우스가 엘리먼트로부터 나간 뒤 다음 패널로 움직이기까지 대기 시간</ko>
+   * @param options - Options for the AutoPlay instance
    * @example
    * ```ts
    * flicking.addPlugins(new AutoPlay({ duration: 2000, direction: "NEXT" }));
    * ```
    */
-  public constructor({
-    duration = 2000,
-    animationDuration = undefined,
-    direction = DIRECTION.NEXT,
-    stopOnHover = false,
-    stopOnInit = false,
-    delayAfterHover
-  }: Partial<AutoPlayOptions> = {}) {
+  public constructor(options: Partial<AutoPlayOptions> = {}) {
+    const {
+      duration = 2000,
+      animationDuration = undefined,
+      direction = DIRECTION.NEXT,
+      stopOnHover = false,
+      stopOnInit = false,
+      delayAfterHover
+    } = options;
+
     this._duration = duration;
     this._animationDuration = animationDuration;
     this._direction = direction;
@@ -73,6 +136,9 @@ class AutoPlay implements Plugin {
     this._delayAfterHover = delayAfterHover ?? duration;
   }
 
+  /** Initialize the plugin and start autoplay on the given Flicking instance.
+   * @param flicking - The Flicking instance to attach this plugin to
+   */
   public init(flicking: Flicking): void {
     if (this._flicking) {
       this.destroy();
@@ -97,6 +163,7 @@ class AutoPlay implements Plugin {
     }
   }
 
+  /** Destroy the plugin, stop autoplay, and remove all event listeners. */
   public destroy(): void {
     const flicking = this._flicking;
 
@@ -119,14 +186,17 @@ class AutoPlay implements Plugin {
     this._flicking = null;
   }
 
+  /** Update the plugin state. This is a no-op for AutoPlay. */
   public update(): void {
     // DO-NOTHING
   }
 
+  /** Start the autoplay timer. Panels will move automatically after the configured {@link AutoPlayOptions.duration | duration}. */
   public play = () => {
     this._movePanel(this._duration);
   };
 
+  /** Stop the autoplay timer and cancel any pending panel movement. */
   public stop = () => {
     this._playing = false;
     clearTimeout(this._timerId);

package/src/Fade.ts

@@ -1,9 +1,8 @@
 import Flicking, { EVENTS, Plugin } from "@egjs/flicking";
 
 /**
- * You can apply fade in / out effect while panel is moving.
- * @ko 패널들을 움직이면서 fade in / out 효과를 부여할 수 있습니다.
- * @memberof Flicking.Plugins
+ * A plugin to apply fade in/out effect while panels are moving
+ * @see {@link https://naver.github.io/egjs-flicking/docs/demos/plugins/fade | Demo: Fade}
  */
 class Fade implements Plugin {
   private _flicking: Flicking | null;
@@ -12,15 +11,31 @@ class Fade implements Plugin {
   private _selector: string;
   private _scale: number;
 
-  public get selector() { return this._selector; }
-  public get scale() { return this._scale; }
+  /** CSS selector for the element to apply the fade effect. If empty, the panel element itself is used
+   * @readonly
+   */
+  public get selector() {
+    return this._selector;
+  }
+  /** Effect amplification scale
+   * @readonly
+   */
+  public get scale() {
+    return this._scale;
+  }
 
-  public set selector(val: string) { this._selector = val; }
-  public set scale(val: number) { this._scale = val; }
+  /** Sets the CSS selector for the target fade element. */
+  public set selector(val: string) {
+    this._selector = val;
+  }
+  /** Sets the effect amplification scale. */
+  public set scale(val: number) {
+    this._scale = val;
+  }
 
   /**
-   * @param - The selector of the element to which the fade effect is to be applied. If the selector is blank, it applies to panel element. <ko>Fade 효과를 적용할 대상의 선택자. 선택자가 공백이면 패널 엘리먼트에 적용된다.</ko>
-   * @param - Effect amplication scale<ko>효과 증폭도</ko>
+   * @param selector - CSS selector for the element to apply the fade effect. If empty, the panel element itself is used
+   * @param scale - Effect amplification scale
    * @example
    * ```ts
    * flicking.addPlugins(new Fade("p", 1));
@@ -32,6 +47,9 @@ class Fade implements Plugin {
     this._scale = scale;
   }
 
+  /** Initialize the plugin and apply the fade effect to the Flicking instance.
+   * @param flicking - The Flicking instance to attach this plugin to
+   */
   public init(flicking: Flicking): void {
     if (this._flicking) {
       this.destroy();
@@ -44,6 +62,7 @@ class Fade implements Plugin {
     this._onMove();
   }
 
+  /** Destroy the plugin and remove all event listeners. */
   public destroy(): void {
     if (!this._flicking) return;
 
@@ -52,6 +71,7 @@ class Fade implements Plugin {
     this._flicking = null;
   }
 
+  /** Recalculate and apply the fade effect to all visible panels. */
   public update = (): void => {
     this._onMove();
   };
@@ -68,10 +88,10 @@ class Fade implements Plugin {
     panels.forEach(panel => {
       const progress = panel.outsetProgress;
       const el = panel.element;
-      const target = selector ? el.querySelector<HTMLElement>(selector)! : el;
+      const target = selector ? (el.querySelector(selector) as HTMLElement) : el;
 
       if (target) {
-        const opacity = Math.min( 1, Math.max(0, 1 - Math.abs(progress * scale)));
+        const opacity = Math.min(1, Math.max(0, 1 - Math.abs(progress * scale)));
         target.style.opacity = `${opacity}`;
       }
     });

package/src/Parallax.ts

@@ -1,9 +1,8 @@
 import Flicking, { EVENTS, Plugin } from "@egjs/flicking";
 
 /**
- * You can apply parallax effect while panel is moving.
- * @ko 패널들을 움직이면서 parallax 효과를 부여할 수 있습니다.
- * @memberof Flicking.Plugins
+ * A plugin to apply parallax effect while panels are moving
+ * @see {@link https://naver.github.io/egjs-flicking/docs/demos/plugins/parallax | Demo: Parallax}
  */
 class Parallax implements Plugin {
   private _flicking: Flicking | null;
@@ -12,15 +11,31 @@ class Parallax implements Plugin {
   private _selector: string;
   private _scale: number;
 
-  public get selector() { return this._selector; }
-  public get scale() { return this._scale; }
+  /** CSS selector for the element to apply the parallax effect. If empty, the panel element itself is used
+   * @readonly
+   */
+  public get selector() {
+    return this._selector;
+  }
+  /** Effect amplification scale
+   * @readonly
+   */
+  public get scale() {
+    return this._scale;
+  }
 
-  public set selector(val: string) { this._selector = val; }
-  public set scale(val: number) { this._scale = val; }
+  /** Sets the CSS selector for the target parallax element. */
+  public set selector(val: string) {
+    this._selector = val;
+  }
+  /** Sets the effect amplification scale. */
+  public set scale(val: number) {
+    this._scale = val;
+  }
 
   /**
-   * @param {string} selector Selector of the element to apply parallax effect<ko> Parallax 효과를 적용할 엘리먼트의 선택자 </ko>
-   * @param {number} scale Effect amplication scale<ko>효과 증폭도</ko>
+   * @param selector - CSS selector for the element to apply the parallax effect. If empty, the panel element itself is used
+   * @param scale - Effect amplification scale
    * @example
    * ```ts
    * flicking.addPlugins(new Parallax("img", 1));
@@ -32,6 +47,9 @@ class Parallax implements Plugin {
     this._scale = scale;
   }
 
+  /** Initialize the plugin and apply the parallax effect to the Flicking instance.
+   * @param flicking - The Flicking instance to attach this plugin to
+   */
   public init(flicking: Flicking): void {
     if (this._flicking) {
       this.destroy();
@@ -44,6 +62,7 @@ class Parallax implements Plugin {
     this._onMove();
   }
 
+  /** Destroy the plugin and remove all event listeners. */
   public destroy(): void {
     if (!this._flicking) return;
 
@@ -52,6 +71,7 @@ class Parallax implements Plugin {
     this._flicking = null;
   }
 
+  /** Recalculate and apply the parallax effect to all visible panels. */
   public update = (): void => {
     this._onMove();
   };
@@ -66,11 +86,11 @@ class Parallax implements Plugin {
     panels.forEach(panel => {
       const progress = panel.outsetProgress;
       const el = panel.element;
-      const target = this._selector ? el.querySelector<HTMLElement>(this._selector)! : el;
+      const target = this._selector ? (el.querySelector(this._selector) as HTMLElement) : el;
       const parentTarget = target.parentNode as Element;
       const rect = target.getBoundingClientRect();
       const parentRect = parentTarget.getBoundingClientRect();
-      const position = (parentRect.width - rect.width) / 2 * progress * this._scale;
+      const position = ((parentRect.width - rect.width) / 2) * progress * this._scale;
       const transform = `translate(-50%) translate(${position}px)`;
       const style = target.style;
 

package/src/Perspective.ts

@@ -1,17 +1,35 @@
 /* eslint-disable no-underscore-dangle */
 import Flicking, { EVENTS, Plugin } from "@egjs/flicking";
 
-interface PerspectiveOptions {
+/**
+ * Options for the {@link Perspective} plugin
+ */
+export interface PerspectiveOptions {
+  /**
+   * CSS selector for the element to apply the perspective effect. If empty, the panel element itself is used
+   * @defaultValue ""
+   */
   selector: string;
+  /**
+   * Effect amplification scale
+   * @defaultValue 1
+   */
   scale: number;
+  /**
+   * Rotation amplification scale
+   * @defaultValue 1
+   */
   rotate: number;
+  /**
+   * The value of the CSS `perspective` property (px)
+   * @defaultValue 1000
+   */
   perspective: number;
 }
 
 /**
- * You can apply perspective effect while panel is moving.
- * @ko 패널들을 움직이면서 입체감을 부여할 수 있습니다.
- * @memberof Flicking.Plugins
+ * A plugin to apply 3D perspective effect while panels are moving
+ * @see {@link https://naver.github.io/egjs-flicking/docs/demos/plugins/perspective | Demo: Perspective}
  */
 class Perspective implements Plugin {
   private _flicking: Flicking | null;
@@ -22,27 +40,50 @@ class Perspective implements Plugin {
   private _rotate: PerspectiveOptions["rotate"];
   private _perspective: PerspectiveOptions["perspective"];
 
-  public get selector() { return this._selector; }
-  public get scale() { return this._scale; }
-  public get rotate() { return this._rotate; }
-  public get perspective() { return this._perspective; }
+  /** Current value of the {@link PerspectiveOptions.selector | selector} option. */
+  public get selector() {
+    return this._selector;
+  }
+  /** Current value of the {@link PerspectiveOptions.scale | scale} option. */
+  public get scale() {
+    return this._scale;
+  }
+  /** Current value of the {@link PerspectiveOptions.rotate | rotate} option. */
+  public get rotate() {
+    return this._rotate;
+  }
+  /** Current value of the {@link PerspectiveOptions.perspective | perspective} option. */
+  public get perspective() {
+    return this._perspective;
+  }
 
-  public set selector(val: string) { this._selector = val; }
-  public set scale(val: number) { this._scale = val; }
-  public set rotate(val: number) { this._rotate = val; }
-  public set perspective(val: number) { this._perspective = val; }
+  /** Sets {@link PerspectiveOptions.selector | selector}. */
+  public set selector(val: string) {
+    this._selector = val;
+  }
+  /** Sets {@link PerspectiveOptions.scale | scale}. */
+  public set scale(val: number) {
+    this._scale = val;
+  }
+  /** Sets {@link PerspectiveOptions.rotate | rotate}. */
+  public set rotate(val: number) {
+    this._rotate = val;
+  }
+  /** Sets {@link PerspectiveOptions.perspective | perspective}. */
+  public set perspective(val: number) {
+    this._perspective = val;
+  }
 
   /**
-   * @param - The selector of the element to which the perspective effect is to be applied. If the selector is blank, it applies to panel element. <ko>입체 효과를 적용할 대상의 선택자. 선택자가 공백이면 패널 엘리먼트에 적용된다.</ko>
-   * @param - Effect amplication scale.<ko>효과 증폭도</ko>
-   * @param - Effect amplication rotate.<ko>회전 증폭도</ko>
-   * @param - The value of perspective CSS property. <ko>css perspective 속성 값</ko>
+   * @param options - Options for the Perspective instance
    * @example
    * ```ts
-   * flicking.addPlugins(new Perspective({ selector: "p", scale: 1, rotate: 1, perspective = 1000 }));
+   * flicking.addPlugins(new Perspective({ selector: "p", scale: 1, rotate: 1, perspective: 1000 }));
    * ```
    */
-  public constructor({ selector = "", scale = 1, rotate = 1, perspective = 1000 }: Partial<PerspectiveOptions> = {}) {
+  public constructor(options: Partial<PerspectiveOptions> = {}) {
+    const { selector = "", scale = 1, rotate = 1, perspective = 1000 } = options;
+
     this._flicking = null;
     this._selector = selector;
     this._scale = scale;
@@ -50,6 +91,9 @@ class Perspective implements Plugin {
     this._perspective = perspective;
   }
 
+  /** Initialize the plugin and apply the perspective effect to the Flicking instance.
+   * @param flicking - The Flicking instance to attach this plugin to
+   */
   public init(flicking: Flicking): void {
     if (this._flicking) {
       this.destroy();
@@ -62,6 +106,7 @@ class Perspective implements Plugin {
     this._onMove();
   }
 
+  /** Destroy the plugin and remove all event listeners. */
   public destroy(): void {
     if (!this._flicking) return;
 
@@ -70,6 +115,7 @@ class Perspective implements Plugin {
     this._flicking = null;
   }
 
+  /** Recalculate and apply the perspective effect to all visible panels. */
   public update = (): void => {
     this._onMove();
   };
@@ -78,7 +124,7 @@ class Perspective implements Plugin {
     const flicking = this._flicking;
     const selector = this._selector;
     const scale = this._scale;
-    const rotate =  this._rotate;
+    const rotate = this._rotate;
     const perspective = this._perspective;
 
     if (!flicking) return;
@@ -86,12 +132,13 @@ class Perspective implements Plugin {
     const horizontal = flicking.horizontal;
     const panels = flicking.visiblePanels;
 
-    panels.forEach((panel) => {
+    panels.forEach(panel => {
       const progress = panel.outsetProgress;
       const el = panel.element;
-      const target = selector ? el.querySelector<HTMLElement>(selector)! : el;
+      const target = selector ? (el.querySelector(selector) as HTMLElement) : el;
       const panelScale = 1 / (Math.abs(progress * scale) + 1);
-      const rotateDegree = progress > 0 ? Math.min(90, progress * 100 * rotate) : Math.max(-90, progress * 100 * rotate);
+      const rotateDegree =
+        progress > 0 ? Math.min(90, progress * 100 * rotate) : Math.max(-90, progress * 100 * rotate);
       const [rotateX, rotateY] = horizontal ? [0, rotateDegree] : [rotateDegree, 0];
 
       target.style.transform = `perspective(${perspective}px) rotateX(${rotateX}deg) rotateY(${rotateY}deg) scale(${panelScale})`;