@egjs/flicking-plugins 4.7.2-beta.1 → 4.7.2-beta.10

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})`;

package/src/Sync.ts

@@ -1,35 +1,53 @@
+import type { MoveEndEvent, MoveEvent, MoveStartEvent, Plugin, SelectEvent, WillChangeEvent } from "@egjs/flicking";
 import Flicking, { clamp, EVENTS } from "@egjs/flicking";
-import type { MoveEndEvent, MoveEvent, MoveStartEvent, Plugin, WillChangeEvent, SelectEvent } from "@egjs/flicking";
 
 import { SYNC } from "./const";
 import { addClass, removeClass } from "./utils";
 
 /**
- * @property {string} [type="camera"] Types of methods to synchronize between Flickings. "camera" will sync by camera position, and "index" will sync by panel index
- * @property {SychronizableFlickingOptions} [synchronizedFlickingOptions=[]]	Detailed options for syncing Flickings.
+ * Options for the {@link Sync} plugin
  */
 export interface SyncOptions {
+  /**
+   * Method to synchronize between Flickings. `"camera"` syncs by camera position, `"index"` syncs by panel index
+   * @defaultValue "camera"
+   */
   type: typeof SYNC.TYPE.CAMERA | typeof SYNC.TYPE.INDEX;
+  /**
+   * Detailed options for each Flicking instance to synchronize
+   * @defaultValue []
+   */
   synchronizedFlickingOptions: SychronizableFlickingOptions[];
 }
 
 /**
- * @property {Flicking} flicking An instance of Flicking to sync
- * @property {boolean} [isClickable=false] By enabling this option, clicking the given Flicking's panel will change the given & other Flicking's index
- * @property {boolean} [isSlidable=false] By enabling this option, the given Flicking's scroll with mouse/touch input will change other Flicking's index. Only available for the index type
- * @property {string | undefined} [activeClass=undefined] An extra class for the panels when selected
+ * Per-instance synchronization options used in {@link SyncOptions.synchronizedFlickingOptions}
  */
 export interface SychronizableFlickingOptions {
+  /**
+   * The Flicking instance to synchronize
+   */
   flicking: Flicking;
+  /**
+   * Whether clicking this Flicking's panel changes the index of all synced Flickings
+   * @defaultValue false
+   */
   isClickable?: boolean;
+  /**
+   * Whether mouse/touch scroll on this Flicking changes other Flickings' index. Only available for the `"index"` type
+   * @defaultValue false
+   */
   isSlidable?: boolean;
+  /**
+   * CSS class added to the active (selected) panel
+   * @defaultValue undefined
+   */
   activeClass?: string;
 }
 
 /**
- * Plugin for synchronizing multiple flickings
- * @ko 다양한 형태로 Flicking들이 같이 움직이게 할 수 있습니다.
- * @memberof Flicking.Plugins
+ * Plugin for synchronizing multiple Flicking instances
+ * @see {@link https://naver.github.io/egjs-flicking/docs/demos/plugins/sync | Demo: Sync}
  */
 class Sync implements Plugin {
   /* Internal Values */
@@ -40,26 +58,48 @@ class Sync implements Plugin {
   private _type: SyncOptions["type"];
   private _synchronizedFlickingOptions: SyncOptions["synchronizedFlickingOptions"];
 
-  public get type() { return this._type; }
-  public get synchronizedFlickingOptions() { return this._synchronizedFlickingOptions; }
+  /** Current value of the {@link SyncOptions.type | type} option. */
+  public get type() {
+    return this._type;
+  }
+  /** Current value of the {@link SyncOptions.synchronizedFlickingOptions | synchronizedFlickingOptions} option. */
+  public get synchronizedFlickingOptions() {
+    return this._synchronizedFlickingOptions;
+  }
 
+  /** Sets {@link SyncOptions.type | type}. */
   public set type(val: SyncOptions["type"]) {
     this._type = val;
   }
 
+  /** Sets {@link SyncOptions.synchronizedFlickingOptions | synchronizedFlickingOptions}. */
   public set synchronizedFlickingOptions(val: SyncOptions["synchronizedFlickingOptions"]) {
     this._synchronizedFlickingOptions = val;
   }
 
-  /** */
-  public constructor({
-    type = SYNC.TYPE.CAMERA,
-    synchronizedFlickingOptions = []
-  }: Partial<SyncOptions> = {}) {
+  /**
+   * @param options - Options for the Sync instance
+   * @example
+   * ```ts
+   * flicking.addPlugins(new Sync({
+   *   type: "camera",
+   *   synchronizedFlickingOptions: [
+   *     { flicking: flicking1 },
+   *     { flicking: flicking2, isClickable: true }
+   *   ]
+   * }));
+   * ```
+   */
+  public constructor(options: Partial<SyncOptions> = {}) {
+    const { type = SYNC.TYPE.CAMERA, synchronizedFlickingOptions = [] } = options;
+
     this._type = type;
     this._synchronizedFlickingOptions = synchronizedFlickingOptions;
   }
 
+  /** Initialize the plugin and set up synchronization event listeners between Flicking instances.
+   * @param flicking - The Flicking instance to attach this plugin to
+   */
   public init(flicking: Flicking): void {
     const synced = this._synchronizedFlickingOptions;
 
@@ -78,6 +118,7 @@ class Sync implements Plugin {
     });
   }
 
+  /** Destroy the plugin and remove all synchronization event listeners. */
   public destroy(): void {
     const flicking = this._flicking;
 
@@ -90,6 +131,7 @@ class Sync implements Plugin {
     this._flicking = null;
   }
 
+  /** Update the active class state for all synchronized Flicking instances. */
   public update(): void {
     this._synchronizedFlickingOptions.forEach(options => {
       this._updateClass(options, options.flicking.index);
@@ -184,7 +226,7 @@ class Sync implements Plugin {
   };
 
   private _onMoveEnd = (e: MoveEndEvent): void => {
-    this._disabledIndex.forEach((i) => {
+    this._disabledIndex.forEach(i => {
       const flicking = this._synchronizedFlickingOptions[i].flicking;
       flicking.enableInput();
       flicking.control.updateInput();
@@ -226,7 +268,7 @@ class Sync implements Plugin {
     if (!activeClass) return;
 
     flicking.panels.forEach(panel => {
-      if (panel.index === index)  {
+      if (panel.index === index) {
         addClass(panel.element, activeClass);
       } else {
         removeClass(panel.element, activeClass);

package/src/index.ts

@@ -1,30 +1,17 @@
-/**
- * @namespace Flicking
- */
-/**
- * @namespace Flicking.Plugins
- */
-import Parallax from "./Parallax";
-import Fade from "./Fade";
-import AutoPlay from "./AutoPlay";
 import Arrow from "./Arrow";
-import Sync, { SyncOptions, SychronizableFlickingOptions } from "./Sync";
+import AutoPlay from "./AutoPlay";
+import Fade from "./Fade";
+import Parallax from "./Parallax";
 import Perspective from "./Perspective";
+import Sync, { SychronizableFlickingOptions, SyncOptions } from "./Sync";
 
 export * from "./pagination";
 
-export {
-  Parallax,
-  Fade,
-  AutoPlay,
-  Arrow,
-  Sync,
-  Perspective
-};
+export { Parallax, Fade, AutoPlay, Arrow, Sync, Perspective };
 
-export type {
-  SyncOptions,
-  SychronizableFlickingOptions
-};
+export type { SyncOptions, SychronizableFlickingOptions };
 
+export type { ArrowOptions } from "./Arrow";
+export type { AutoPlayOptions } from "./AutoPlay";
 export * from "./const";
+export type { PerspectiveOptions } from "./Perspective";