@egjs/flicking 4.15.0 → 4.16.0-beta.1

package/src/control/AxesController.ts

@@ -2,21 +2,20 @@
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
-import Axes, { PanInput, AxesEvents, OnRelease } from "@egjs/axes";
-
+import Axes, { AxesEvents, OnRelease, PanInput } from "@egjs/axes";
+import * as AXES from "../constants/internal";
+import { ORDER } from "../constants/values";
+import * as ERROR from "../error/codes";
+import FlickingError from "../error/FlickingError";
 import Flicking from "../Flicking";
-import FlickingError from "../core/FlickingError";
-import * as AXES from "../const/axes";
-import * as ERROR from "../const/error";
-import { ORDER } from "../const/external";
+import { ControlParams } from "../types/external";
 import { getFlickingAttached, parseBounce } from "../utils";
-import { ControlParams } from "../type/external";
 
 import StateMachine from "./StateMachine";
+import State from "./states/State";
 
 /**
- * A controller that handles the {@link https://naver.github.io/egjs-axes/ @egjs/axes} events
- * @ko {@link https://naver.github.io/egjs-axes/ @egjs/axes}의 이벤트를 처리하는 컨트롤러 컴포넌트
+ * A controller that handles the {@link https://naver.github.io/egjs-axes/ | @egjs/axes} events
  * @internal
  */
 class AxesController {
@@ -29,45 +28,42 @@ class AxesController {
   private _dragged: boolean;
 
   /**
-   * An {@link https://naver.github.io/egjs-axes/docs/api/Axes Axes} instance
-   * @ko {@link https://naver.github.io/egjs-axes/docs/api/Axes Axes}의 인스턴스
-   * @type {Axes | null}
+   * An {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
    * @see https://naver.github.io/egjs-axes/docs/api/Axes
    * @readonly
    */
-  public get axes() { return this._axes; }
+  public get axes(): Axes | null {
+    return this._axes;
+  }
   /**
-   * An {@link https://naver.github.io/egjs-axes/docs/api/PanInput PanInput} instance
-   * @ko {@link https://naver.github.io/egjs-axes/docs/api/PanInput PanInput}의 인스턴스
-   * @type {PanInput | null}
+   * An {@link https://naver.github.io/egjs-axes/docs/api/PanInput | PanInput} instance
    * @see https://naver.github.io/egjs-axes/docs/api/PanInput
    * @readonly
    */
-  public get panInput() { return this._panInput; }
+  public get panInput(): PanInput | null {
+    return this._panInput;
+  }
   /**
    * @internal
    */
-  public get stateMachine() { return this._stateMachine; }
+  public get stateMachine(): StateMachine {
+    return this._stateMachine;
+  }
   /**
    * A activated {@link State} that shows the current status of the user input or the animation
-   * @ko 현재 활성화된 {@link State} 인스턴스로 사용자 입력 또는 애니메이션 상태를 나타냅니다
-   * @type {State}
    */
-  public get state() { return this._stateMachine.state; }
+  public get state(): State {
+    return this._stateMachine.state;
+  }
   /**
    * A context of the current animation playing
-   * @ko 현재 재생중인 애니메이션 정보
-   * @type {object}
-   * @property {number} start A start position of the animation<ko>애니메이션 시작 지점</ko>
-   * @property {number} end A end position of the animation<ko>애니메이션 끝 지점</ko>
-   * @property {number} offset camera offset<ko>카메라 오프셋</ko>
    * @readonly
    */
-  public get animatingContext() { return this._animatingContext; }
+  public get animatingContext(): { start: number; end: number; offset: number } {
+    return this._animatingContext;
+  }
   /**
    * A current control parameters of the Axes instance
-   * @ko 활성화된 현재 Axes 패러미터들
-   * @type {ControlParams}
    */
   public get controlParams(): ControlParams {
     const axes = this._axes;
@@ -91,34 +87,33 @@ class AxesController {
 
   /**
    * A Boolean indicating whether the user input is enabled
-   * @ko 현재 사용자 입력이 활성화되었는지를 나타내는 값
-   * @type {boolean}
    * @readonly
    */
-  public get enabled() { return this._panInput?.isEnabled() ?? false; }
+  public get enabled(): boolean {
+    return this._panInput?.isEnabled() ?? false;
+  }
   /**
-   * Current position value in {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html Axes} instance
-   * @ko {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html Axes} 인스턴스 내부의 현재 좌표 값
-   * @type {number}
+   * Current position value in {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
    * @readonly
    */
-  public get position() { return this._axes?.get([AXES.POSITION_KEY])[AXES.POSITION_KEY] ?? 0; }
+  public get position(): number {
+    return this._axes?.get([AXES.POSITION_KEY])[AXES.POSITION_KEY] ?? 0;
+  }
   /**
-   * Current range value in {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html Axes} instance
-   * @ko {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html Axes} 인스턴스 내부의 현재 이동 범위 값
-   * @type {number[]}
+   * Current range value in {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
    * @readonly
    */
-  public get range() { return this._axes?.axis[AXES.POSITION_KEY].range ?? [0, 0]; }
+  public get range(): number[] {
+    return this._axes?.axis[AXES.POSITION_KEY].range ?? [0, 0];
+  }
   /**
    * Actual bounce size(px)
-   * @ko 적용된 bounce 크기(px 단위)
-   * @type {number[]}
    * @readonly
    */
-  public get bounce() { return this._axes?.axis[AXES.POSITION_KEY].bounce as number[] | undefined; }
+  public get bounce(): number[] | undefined {
+    return this._axes?.axis[AXES.POSITION_KEY].bounce as number[] | undefined;
+  }
 
-  /** */
   public constructor() {
     this._resetInternalValues();
     this._stateMachine = new StateMachine();
@@ -126,26 +121,29 @@ class AxesController {
 
   /**
    * Initialize AxesController
-   * @ko AxesController를 초기화합니다
-   * @param {Flicking} flicking An instance of Flicking
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method creates and configures the Axes and PanInput instances.
+   * @param flicking - An instance of {@link Flicking}
+   * @returns The current instance for method chaining
    */
   public init(flicking: Flicking): this {
     this._flicking = flicking;
 
-    this._axes = new Axes({
-      [AXES.POSITION_KEY]: {
-        range: [0, 0],
-        circular: false,
-        bounce: [0, 0]
+    this._axes = new Axes(
+      {
+        [AXES.POSITION_KEY]: {
+          range: [0, 0],
+          circular: false,
+          bounce: [0, 0]
+        }
+      },
+      {
+        deceleration: flicking.deceleration,
+        interruptable: flicking.interruptable,
+        nested: flicking.nested,
+        easing: flicking.easing
       }
-    }, {
-      deceleration: flicking.deceleration,
-      interruptable: flicking.interruptable,
-      nested: flicking.nested,
-      easing: flicking.easing
-    });
+    );
     this._panInput = new PanInput(flicking.viewport.element, {
       inputType: flicking.inputType,
       threshold: flicking.dragThreshold,
@@ -175,8 +173,8 @@ class AxesController {
 
   /**
    * Destroy AxesController and return to initial state
-   * @ko AxesController를 초기 상태로 되돌립니다
-   * @return {void}
+   * @remarks
+   * This method destroys the Axes and PanInput instances and removes all event handlers.
    */
   public destroy(): void {
     if (this._axes) {
@@ -191,9 +189,9 @@ class AxesController {
 
   /**
    * Enable input from the user (mouse/touch)
-   * @ko 사용자의 입력(마우스/터치)를 활성화합니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * Enables the PanInput to receive user interactions.
+   * @returns The current instance for method chaining
    */
   public enable(): this {
     this._panInput?.enable();
@@ -203,9 +201,9 @@ class AxesController {
 
   /**
    * Disable input from the user (mouse/touch)
-   * @ko 사용자의 입력(마우스/터치)를 막습니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * Disables the PanInput to ignore user interactions.
+   * @returns The current instance for method chaining
    */
   public disable(): this {
     this._panInput?.disable();
@@ -215,9 +213,9 @@ class AxesController {
 
   /**
    * Releases ongoing user input (mouse/touch)
-   * @ko 사용자의 현재 입력(마우스/터치)를 중단시킵니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * Immediately releases the PanInput, simulating the user lifting their finger.
+   * @returns The current instance for method chaining
    */
   public release(): this {
     this._panInput?.release();
@@ -227,11 +225,11 @@ class AxesController {
 
   /**
    * Change the destination and duration of the animation currently playing
-   * @ko 재생 중인 애니메이션의 목적지와 재생 시간을 변경합니다
-   * @param {number} position A position to move<ko>이동할 좌표</ko>
-   * @param {number} duration Duration of the animation (unit: ms)<ko>애니메이션 진행 시간 (단위: ms)</ko>
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method updates the Axes animation target position and optionally the duration.
+   * @param position - A position to move
+   * @param duration - Duration of the animation (unit: ms)
+   * @returns The current instance for method chaining
    */
   public updateAnimation(position: number, duration?: number): this {
     this._animatingContext = {
@@ -248,9 +246,9 @@ class AxesController {
 
   /**
    * Stops the animation currently playing
-   * @ko 재생 중인 애니메이션을 중단시킵니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method immediately stops the Axes animation at the current position.
+   * @returns The current instance for method chaining
    */
   public stopAnimation(): this {
     this._axes?.stopAnimation();
@@ -259,13 +257,12 @@ class AxesController {
   }
 
   /**
-   * Update {@link https://naver.github.io/egjs-axes/ @egjs/axes}'s state
-   * @ko {@link https://naver.github.io/egjs-axes/ @egjs/axes}의 상태를 갱신합니다
-   * @chainable
-   * @throws {FlickingError}
-   * {@link ERROR_CODE NOT_ATTACHED_TO_FLICKING} When {@link AxesController#init init} is not called before
-   * <ko>{@link AxesController#init init}이 이전에 호출되지 않은 경우</ko>
-   * @return {this}
+   * Update {@link https://naver.github.io/egjs-axes/ | @egjs/axes}'s state
+   * @remarks
+   * This method synchronizes the Axes state with the given control parameters.
+   * @param controlParams - Control parameters
+   * @throws {@link InitializationErrors}
+   * @returns The current instance for method chaining
    */
   public update(controlParams: ControlParams): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -284,8 +281,9 @@ class AxesController {
 
   /**
    * Attach a handler to the camera element to prevent click events during animation
-   * @ko 카메라 엘리먼트에 애니메이션 도중에 클릭 이벤트를 방지하는 핸들러를 부착합니다
-   * @return {this}
+   * @remarks
+   * This is used when {@link FlickingOptions.preventClickOnDrag | preventClickOnDrag} is enabled.
+   * @returns The current instance for method chaining
    */
   public addPreventClickHandler(): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -301,8 +299,9 @@ class AxesController {
 
   /**
    * Detach a handler to the camera element to prevent click events during animation
-   * @ko 카메라 엘리먼트에 애니메이션 도중에 클릭 이벤트를 방지하는 핸들러를 탈착합니다
-   * @return {this}
+   * @remarks
+   * This is used when {@link FlickingOptions.preventClickOnDrag | preventClickOnDrag} is disabled.
+   * @returns The current instance for method chaining
    */
   public removePreventClickHandler(): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -317,32 +316,23 @@ class AxesController {
   }
 
   /**
-   * Run Axes's {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#setTo setTo} using the given position
-   * @ko Axes의 {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#setTo setTo} 메소드를 주어진 좌표를 이용하여 수행합니다
-   * @param {number} position A position to move<ko>이동할 좌표</ko>
-   * @param {number} duration Duration of the animation (unit: ms)<ko>애니메이션 진행 시간 (단위: ms)</ko>
-   * @param {number} [axesEvent] If provided, it'll use its {@link https://naver#github#io/egjs-axes/release/latest/doc/eg#Axes#html#setTo setTo} method instead<ko>이 값이 주어졌을 경우, 해당 이벤트의 {@link https://naver#github#io/egjs-axes/release/latest/doc/eg#Axes#html#setTo setTo} 메소드를 대신해서 사용합니다.</ko>
-   * @throws {FlickingError}
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING}|When {@link Control#init init} is not called before|
-   * |{@link ERROR_CODE ANIMATION_INTERRUPTED}|When the animation is interrupted by user input|
-   * <ko>
-   *
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING}|{@link Control#init init}이 이전에 호출되지 않은 경우|
-   * |{@link ERROR_CODE ANIMATION_INTERRUPTED}|사용자 입력에 의해 애니메이션이 중단된 경우|
-   *
-   * </ko>
-   * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
+   * Run Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#setTo | setTo} using the given position
+   * @remarks
+   * If the target position equals the current position, the promise resolves immediately without animation.
+   * @param position - A position to move
+   * @param duration - Duration of the animation (unit: ms)
+   * @param axesEvent - If provided, it'll use its {@link https://naver.github.io/egjs-axes/docs/api/Axes#setTo | setTo} method instead
+   * @throws {@link MovementErrors}
+   * @returns A Promise which will be resolved after reaching the target position
    */
   public animateTo(position: number, duration: number, axesEvent?: OnRelease): Promise<void> {
     const axes = this._axes;
     const state = this._stateMachine.state;
 
     if (!axes) {
-      return Promise.reject(new FlickingError(ERROR.MESSAGE.NOT_ATTACHED_TO_FLICKING, ERROR.CODE.NOT_ATTACHED_TO_FLICKING));
+      return Promise.reject(
+        new FlickingError(ERROR.MESSAGE.NOT_ATTACHED_TO_FLICKING, ERROR.CODE.NOT_ATTACHED_TO_FLICKING)
+      );
     }
 
     const startPos = this.getCurrentPosition();
@@ -398,7 +388,6 @@ class AxesController {
 
   /**
    * Returns the current axes position
-   * @ko 현재 axes의 position을 반환합니다.
    */
   public getCurrentPosition() {
     return this._axes?.get([AXES.POSITION_KEY])[AXES.POSITION_KEY] ?? 0;
@@ -415,6 +404,11 @@ class AxesController {
     panInput.options.scale = flicking.horizontal ? [flicking.camera.panelOrder === ORDER.RTL ? 1 : -1, 0] : [0, -1];
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Resets all internal values to their defaults. Called during construction and destruction.
+   */
   private _resetInternalValues() {
     this._flicking = null;
     this._axes = null;
@@ -423,14 +417,29 @@ class AxesController {
     this._dragged = false;
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Handles the Axes hold event to reset the dragged state.
+   */
   private _onAxesHold = () => {
     this._dragged = false;
   };
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Handles the Axes change event to update the dragged state.
+   */
   private _onAxesChange = () => {
     this._dragged = !!this._panInput?.isEnabled();
   };
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Prevents click events when the user has dragged. Used for {@link FlickingOptions.preventClickOnDrag}.
+   */
   private _preventClickWhenDragged = (e: MouseEvent) => {
     if (this._dragged) {
       e.preventDefault();