@egjs/flicking 4.14.2-beta.2 → 4.16.0-beta.0

package/src/control/Control.ts

@@ -4,19 +4,32 @@
  */
 import { OnRelease } from "@egjs/axes";
 import { ComponentEvent } from "@egjs/component";
-
-import Flicking from "../Flicking";
-import FlickingError from "../core/FlickingError";
-import Panel from "../core/panel/Panel";
+import { DIRECTION } from "../constants/values";
 import AxesController from "../control/AxesController";
-import { DIRECTION, EVENTS } from "../const/external";
-import * as ERROR from "../const/error";
+import Panel from "../core/panel/Panel";
+import * as ERROR from "../error/codes";
+import FlickingError from "../error/FlickingError";
+import { EVENTS } from "../event/names";
+import Flicking from "../Flicking";
+import { ValueOf } from "../types/internal";
 import { getDirection, getFlickingAttached } from "../utils";
-import { ValueOf } from "../type/internal";
+
+/**
+ * Parameters for {@link Control.moveToPanel}
+ * @public
+ */
+export interface MoveToPanelParams {
+  /** Duration of the animation (unit: ms) */
+  duration: number;
+  /** Direction to move, only available in the {@link Flicking.circular | circular} mode */
+  direction?: ValueOf<typeof DIRECTION>;
+  /** {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes} */
+  axesEvent?: OnRelease;
+}
 
 /**
  * A component that manages inputs and animation of Flicking
- * @ko Flicking의 입력 장치 & 애니메이션을 담당하는 컴포넌트
+ * @public
  */
 abstract class Control {
   // Internal States
@@ -26,43 +39,42 @@ abstract class Control {
   protected _nextPanel: Panel | null;
 
   /**
-   * 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}의 이벤트를 처리하는 컨트롤러 컴포넌트
-   * @type {AxesController}
+   * A controller that handles the {@link https://naver.github.io/egjs-axes/ | @egjs/axes} events
    * @readonly
    */
-  public get controller() { return this._controller; }
+  public get controller(): AxesController {
+    return this._controller;
+  }
   /**
-   * Index number of the {@link Flicking#currentPanel currentPanel}
-   * @ko {@link Flicking#currentPanel currentPanel}의 인덱스 번호
-   * @type {number}
-   * @default 0
+   * Index number of the {@link Flicking.currentPanel | currentPanel}
+   * @defaultValue 0
    * @readonly
    */
-  public get activeIndex() { return this._activePanel?.index ?? -1; }
+  public get activeIndex(): number {
+    return this._activePanel?.index ?? -1;
+  }
   /**
    * An active panel
-   * @ko 현재 선택된 패널
-   * @type {Panel | null}
    * @readonly
    */
-  public get activePanel() { return this._activePanel; }
+  public get activePanel(): Panel | null {
+    return this._activePanel;
+  }
   /**
    * Whether Flicking's animating
-   * @ko 현재 애니메이션 동작 여부
-   * @type {boolean}
    * @readonly
    */
-  public get animating() { return this._controller.state.animating; }
+  public get animating(): boolean {
+    return this._controller.state.animating;
+  }
   /**
    * Whether user is clicking or touching
-   * @ko 현재 사용자가 클릭/터치중인지 여부
-   * @type {boolean}
    * @readonly
    */
-  public get holding() { return this._controller.state.holding; }
+  public get holding(): boolean {
+    return this._controller.state.holding;
+  }
 
-  /** */
   public constructor() {
     this._flicking = null;
     this._controller = new AxesController();
@@ -71,53 +83,21 @@ abstract class Control {
 
   /**
    * Move {@link Camera} to the given position
-   * @ko {@link Camera}를 주어진 좌표로 이동합니다
-   * @method
-   * @abstract
-   * @memberof Control
-   * @instance
-   * @name moveToPosition
-   * @param {number} position The target position to move<ko>이동할 좌표</ko>
-   * @param {number} duration Duration of the panel movement animation (unit: ms).<ko>패널 이동 애니메이션 진행 시간 (단위: ms)</ko>
-   * @param {object} [axesEvent] {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} event of {@link https://naver.github.io/egjs-axes/ Axes}
-   * <ko>{@link https://naver.github.io/egjs-axes/ Axes}의 {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} 이벤트</ko>
-   * @fires Flicking#moveStart
-   * @fires Flicking#move
-   * @fires Flicking#moveEnd
-   * @fires Flicking#willChange
-   * @fires Flicking#changed
-   * @fires Flicking#willRestore
-   * @fires Flicking#restored
-   * @fires Flicking#needPanel
-   * @fires Flicking#visibleChange
-   * @fires Flicking#reachEdge
-   * @throws {FlickingError}
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|When the given panel is already removed or not in the Camera's {@link Camera#range range}|
-   * |{@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|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|When the animation is interrupted by user input|
-   * <ko>
-   *
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|주어진 패널이 제거되었거나, Camera의 {@link Camera#range range} 밖에 있을 경우|
-   * |{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING}|{@link Control#init init}이 이전에 호출되지 않은 경우|
-   * |{@link ERROR_CODE ANIMATION_INTERRUPTED}|사용자 입력에 의해 애니메이션이 중단된 경우|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|발생된 이벤트들 중 하나라도 `stop()`이 호출된 경우|
-   *
-   * </ko>
-   * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
+   * @param position - The target position to move
+   * @param duration - Duration of the panel movement animation (unit: ms)
+   * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+   * @fires {@link MovementEvents}
+   * @throws {@link MovementErrors}
+   * @returns A Promise which will be resolved after reaching the target position
    */
   public abstract moveToPosition(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
 
   /**
    * Initialize Control
-   * @ko Control을 초기화합니다
-   * @param {Flicking} flicking An instance of {@link Flicking}<ko>Flicking의 인스턴스</ko>
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method is called automatically during {@link Flicking.init}. It initializes the internal controller.
+   * @param flicking - An instance of {@link Flicking}
+   * @returns The current instance for method chaining
    */
   public init(flicking: Flicking): this {
     this._flicking = flicking;
@@ -128,8 +108,8 @@ abstract class Control {
 
   /**
    * Destroy Control and return to initial state
-   * @ko Control을 초기 상태로 되돌립니다
-   * @return {void}
+   * @remarks
+   * This method destroys the internal controller and resets all internal values.
    */
   public destroy(): void {
     this._controller.destroy();
@@ -140,9 +120,9 @@ abstract class Control {
 
   /**
    * Enable input from the user (mouse/touch)
-   * @ko 사용자의 입력(마우스/터치)를 활성화합니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This is a shorthand for `Flicking.enableInput`.
+   * @returns The current instance for method chaining
    */
   public enable(): this {
     this._controller.enable();
@@ -152,9 +132,9 @@ abstract class Control {
 
   /**
    * Disable input from the user (mouse/touch)
-   * @ko 사용자의 입력(마우스/터치)를 막습니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This is a shorthand for `Flicking.disableInput`.
+   * @returns The current instance for method chaining
    */
   public disable(): this {
     this._controller.disable();
@@ -164,9 +144,9 @@ abstract class Control {
 
   /**
    * Releases ongoing user input (mouse/touch)
-   * @ko 사용자의 현재 입력(마우스/터치)를 중단시킵니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method immediately releases the user's input, similar to the user lifting their finger.
+   * @returns The current instance for method chaining
    */
   public release(): this {
     this._controller.release();
@@ -176,15 +156,13 @@ abstract class Control {
 
   /**
    * Change the destination and duration of the animation currently playing
-   * @ko 재생 중인 애니메이션의 목적지와 재생 시간을 변경합니다
-   * @param {Panel} panel The target panel to move<ko>이동할 패널</ko>
-   * @param {number} duration Duration of the animation (unit: ms)<ko>애니메이션 진행 시간 (단위: ms)</ko>
-   * @param {DIRECTION} direction Direction to move, only available in the {@link Flicking#circular circular} mode<ko>이동할 방향. {@link Flicking#circular circular} 옵션 활성화시에만 사용 가능합니다</ko>
-   * @chainable
-   * @throws {FlickingError}
-   * {@link ERROR_CODE POSITION_NOT_REACHABLE} When the given panel is already removed or not in the Camera's {@link Camera#range range}
-   * <ko>{@link ERROR_CODE POSITION_NOT_REACHABLE} 주어진 패널이 제거되었거나, Camera의 {@link Camera#range range} 밖에 있을 경우</ko>
-   * @return {this}
+   * @remarks
+   * This method does nothing if no animation is currently playing.
+   * @param panel - The target panel to move
+   * @param duration - Duration of the animation (unit: ms)
+   * @param direction - Direction to move, only available in the {@link Flicking.circular | circular} mode
+   * @throws {@link AnimationUpdateErrors}
+   * @returns The current instance for method chaining
    */
   public updateAnimation(panel: Panel, duration?: number, direction?: ValueOf<typeof DIRECTION>): this {
     const state = this._controller.state;
@@ -198,9 +176,9 @@ abstract class Control {
 
   /**
    * Stops the animation currently playing
-   * @ko 재생 중인 애니메이션을 중단시킵니다
-   * @chainable
-   * @return {this}
+   * @remarks
+   * This method does nothing if no animation is currently playing.
+   * @returns The current instance for method chaining
    */
   public stopAnimation(): this {
     const state = this._controller.state;
@@ -213,15 +191,13 @@ abstract class Control {
 
   /**
    * Update position after resizing
-   * @ko resize 이후에 position을 업데이트합니다
-   * @param {number} progressInPanel Previous camera's progress in active panel before resize<ko>Resize 이전 현재 선택된 패널 내에서의 카메라 progress 값</ko>
-   * @throws {FlickingError}
-   * {@link ERROR_CODE NOT_ATTACHED_TO_FLICKING} When {@link Camera#init init} is not called before
-   * <ko>{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING} {@link Camera#init init}이 이전에 호출되지 않은 경우</ko>
-   * @chainable
-   * @return {Promise<void>}
+   * @remarks
+   * This method moves the camera to the active panel's position after a resize operation.
+   * @param progressInPanel - Previous camera's progress in active panel before resize
+   * @throws {@link InitializationErrors}
    */
-  public updatePosition(progressInPanel: number): void { // eslint-disable-line @typescript-eslint/no-unused-vars
+  public updatePosition(progressInPanel: number): void {
+    // eslint-disable-line @typescript-eslint/no-unused-vars
     const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const activePanel = this._activePanel;
@@ -232,10 +208,10 @@ abstract class Control {
   }
 
   /**
-   * Update {@link Control#controller controller}'s state
-   * @ko {@link Control#controller controller}의 내부 상태를 갱신합니다
-   * @chainable
-   * @return {this}
+   * Update {@link Control.controller | controller}'s state
+   * @remarks
+   * This method synchronizes the controller state with the current camera parameters.
+   * @returns The current instance for method chaining
    */
   public updateInput(): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -247,10 +223,10 @@ abstract class Control {
   }
 
   /**
-   * Reset {@link Control#activePanel activePanel} to `null`
-   * @ko {@link Control#activePanel activePanel}을 `null`로 초기화합니다
-   * @chainable
-   * @return {this}
+   * Reset {@link Control.activePanel | activePanel} to `null`
+   * @remarks
+   * This method is called when the active panel is removed from the renderer.
+   * @returns The current instance for method chaining
    */
   public resetActive(): this {
     this._activePanel = null;
@@ -260,51 +236,16 @@ abstract class Control {
 
   /**
    * Move {@link Camera} to the given panel
-   * @ko {@link Camera}를 해당 패널 위로 이동합니다
-   * @param {Panel} panel The target panel to move<ko>이동할 패널</ko>
-   * @param {object} options An options object<ko>옵션 오브젝트</ko>
-   * @param {number} duration Duration of the animation (unit: ms)<ko>애니메이션 진행 시간 (단위: ms)</ko>
-   * @param {object} [axesEvent] {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} event of {@link https://naver.github.io/egjs-axes/ Axes}
-   * <ko>{@link https://naver.github.io/egjs-axes/ Axes}의 {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} 이벤트</ko>
-   * @param {DIRECTION} [direction=DIRECTION.NONE] Direction to move, only available in the {@link Flicking#circular circular} mode<ko>이동할 방향. {@link Flicking#circular circular} 옵션 활성화시에만 사용 가능합니다</ko>
-   * @fires Flicking#moveStart
-   * @fires Flicking#move
-   * @fires Flicking#moveEnd
-   * @fires Flicking#willChange
-   * @fires Flicking#changed
-   * @fires Flicking#willRestore
-   * @fires Flicking#restored
-   * @fires Flicking#needPanel
-   * @fires Flicking#visibleChange
-   * @fires Flicking#reachEdge
-   * @throws {FlickingError}
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|When the given panel is already removed or not in the Camera's {@link Camera#range range}|
-   * |{@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|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|When the animation is interrupted by user input|
-   * <ko>
-   *
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|주어진 패널이 제거되었거나, Camera의 {@link Camera#range range} 밖에 있을 경우|
-   * |{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING}|{@link Control#init init}이 이전에 호출되지 않은 경우|
-   * |{@link ERROR_CODE ANIMATION_INTERRUPTED}|사용자 입력에 의해 애니메이션이 중단된 경우|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|발생된 이벤트들 중 하나라도 `stop()`이 호출된 경우|
-   *
-   * </ko>
-   * @return {Promise<void>} A Promise which will be resolved after reaching the target panel<ko>해당 패널 도달시에 resolve되는 Promise</ko>
+   * @param panel - The target panel to move
+   * @param options - {@link MoveToPanelParams}
+   * @fires {@link MovementEvents}
+   * @throws {@link MovementErrors}
+   * @returns A Promise which will be resolved after reaching the target panel
    */
-  public async moveToPanel(panel: Panel, {
-    duration,
-    direction = DIRECTION.NONE,
-    axesEvent
-  }: {
-    duration: number;
-    direction?: ValueOf<typeof DIRECTION>;
-    axesEvent?: OnRelease;
-  }) {
+  public async moveToPanel(
+    panel: Panel,
+    { duration, direction = DIRECTION.NONE, axesEvent }: MoveToPanelParams
+  ): Promise<void> {
     const position = this._getPosition(panel, direction);
     this._triggerIndexChangeEvent(panel, panel.position, axesEvent, direction);
 
@@ -313,6 +254,8 @@ abstract class Control {
 
   /**
    * @internal
+   * @privateRemarks
+   * Sets the active panel and triggers {@link ChangedEvent} or {@link RestoredEvent} based on whether the panel changed.
    */
   public setActive(newActivePanel: Panel, prevActivePanel: Panel | null, isTrusted: boolean) {
     const flicking = getFlickingAttached(this._flicking);
@@ -323,23 +266,29 @@ abstract class Control {
     flicking.camera.updateAdaptiveHeight();
 
     if (newActivePanel !== prevActivePanel) {
-      flicking.trigger(new ComponentEvent(EVENTS.CHANGED, {
-        index: newActivePanel.index,
-        panel: newActivePanel,
-        prevIndex: prevActivePanel?.index ?? -1,
-        prevPanel: prevActivePanel,
-        isTrusted,
-        direction: prevActivePanel ? getDirection(prevActivePanel.position, newActivePanel.position) : DIRECTION.NONE
-      }));
+      flicking.trigger(
+        new ComponentEvent(EVENTS.CHANGED, {
+          index: newActivePanel.index,
+          panel: newActivePanel,
+          prevIndex: prevActivePanel?.index ?? -1,
+          prevPanel: prevActivePanel,
+          isTrusted,
+          direction: prevActivePanel ? getDirection(prevActivePanel.position, newActivePanel.position) : DIRECTION.NONE
+        })
+      );
     } else {
-      flicking.trigger(new ComponentEvent(EVENTS.RESTORED, {
-        isTrusted
-      }));
+      flicking.trigger(
+        new ComponentEvent(EVENTS.RESTORED, {
+          isTrusted
+        })
+      );
     }
   }
 
   /**
    * @internal
+   * @privateRemarks
+   * Copies internal state from another Control instance. Used when changing moveType option.
    */
   public copy(control: Control) {
     this._flicking = control._flicking;
@@ -347,7 +296,17 @@ abstract class Control {
     this._controller = control._controller;
   }
 
-  protected _triggerIndexChangeEvent(panel: Panel, position: number, axesEvent?: OnRelease, direction?: ValueOf<typeof DIRECTION>) {
+  /**
+   * @internal
+   * @privateRemarks
+   * Triggers {@link WillChangeEvent} or {@link WillRestoreEvent} based on whether the target panel differs from the active panel.
+   */
+  protected _triggerIndexChangeEvent(
+    panel: Panel,
+    position: number,
+    axesEvent?: OnRelease,
+    direction?: ValueOf<typeof DIRECTION>
+  ) {
     const flicking = getFlickingAttached(this._flicking);
     const triggeringEvent = panel !== this._activePanel ? EVENTS.WILL_CHANGE : EVENTS.WILL_RESTORE;
     const camera = flicking.camera;
@@ -368,6 +327,11 @@ abstract class Control {
     }
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Animates the camera to the target position and handles animation completion or interruption.
+   */
   protected async _animateToPosition({
     position,
     duration,
@@ -380,7 +344,6 @@ abstract class Control {
     axesEvent?: OnRelease;
   }) {
     const flicking = getFlickingAttached(this._flicking);
-
     // 거리(1px 미만)가 매우 짧은 경우 duration이 늘어지는걸 방지하기 위해 0으로 바꿔 즉시 변경
     let nextDuration = duration;
 
@@ -395,17 +358,24 @@ abstract class Control {
     if (nextDuration <= 0) {
       return animate();
     } else {
-      return animate().then(async () => {
-        if (flicking.initialized) {
-          await flicking.renderer.render();
-        }
-      }).catch(err => {
-        if (axesEvent && err instanceof FlickingError && err.code === ERROR.CODE.ANIMATION_INTERRUPTED) return;
-        throw err;
-      });
+      return animate()
+        .then(async () => {
+          if (flicking.initialized) {
+            await flicking.renderer.render();
+          }
+        })
+        .catch(err => {
+          if (axesEvent && err instanceof FlickingError && err.code === ERROR.CODE.ANIMATION_INTERRUPTED) return;
+          throw err;
+        });
     }
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Calculates the target position for a panel, considering circular mode and direction constraints.
+   */
   private _getPosition(panel: Panel, direction: ValueOf<typeof DIRECTION> = DIRECTION.NONE) {
     const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
@@ -424,14 +394,11 @@ abstract class Control {
       // Circular mode is enabled, find nearest distance to panel
       const camPos = this._controller.position; // Actual position of the Axes
       const camRangeDiff = camera.rangeDiff;
-      const possiblePositions = [position, position + camRangeDiff, position - camRangeDiff]
-        .filter(pos => {
-          if (direction === DIRECTION.NONE) return true;
+      const possiblePositions = [position, position + camRangeDiff, position - camRangeDiff].filter(pos => {
+        if (direction === DIRECTION.NONE) return true;
 
-          return direction === DIRECTION.PREV
-            ? pos <= camPos
-            : pos >= camPos;
-        });
+        return direction === DIRECTION.PREV ? pos <= camPos : pos >= camPos;
+      });
 
       position = possiblePositions.reduce((nearestPosition, pos) => {
         if (Math.abs(camPos - pos) < Math.abs(camPos - nearestPosition)) {

package/src/control/FreeControl.ts

@@ -3,59 +3,53 @@
  * egjs projects are licensed under the MIT license
  */
 import { OnRelease } from "@egjs/axes";
-
-import FlickingError from "../core/FlickingError";
-import * as ERROR from "../const/error";
+import * as ERROR from "../error/codes";
+import FlickingError from "../error/FlickingError";
 import { getFlickingAttached } from "../utils";
 
 import Control from "./Control";
 
 /**
- * An options for the {@link FreeControl}
- * @ko {@link FreeControl} 생성시 사용되는 옵션
- * @interface
- * @property {boolean} stopAtEdge Make scroll animation to stop at the start/end of the scroll area, not going out the bounce area
- * <ko>스크롤 애니메이션을 스크롤 영역의 시작과 끝부분에서 멈추도록 하여, 바운스 영역을 넘어가지 않도록 합니다</ko>
+ * Options for the {@link FreeControl}
  */
 export interface FreeControlOptions {
+  /** Make scroll animation to stop at the start/end of the scroll area, not going out the bounce area */
   stopAtEdge: boolean;
 }
 
 /**
  * A {@link Control} that can be scrolled freely without alignment
- * @ko 패널이 정해진 지점에 정렬되지 않고, 자유롭게 스크롤할 수 있는 이동 방식을 사용하는 {@link Control}
+ * @public
  */
 class FreeControl extends Control {
   private _stopAtEdge: FreeControlOptions["stopAtEdge"];
 
   /**
    * Make scroll animation to stop at the start/end of the scroll area, not going out the bounce area
-   * @ko 스크롤 애니메이션을 스크롤 영역의 시작과 끝부분에서 멈추도록 하여, 바운스 영역을 넘어가지 않도록 합니다
-   * @type {boolean}
-   * @default true
+   * @defaultValue true
    */
-  public get stopAtEdge() { return this._stopAtEdge; }
+  public get stopAtEdge(): boolean {
+    return this._stopAtEdge;
+  }
 
-  public set stopAtEdge(val: FreeControlOptions["stopAtEdge"]) { this._stopAtEdge = val; }
+  public set stopAtEdge(val: FreeControlOptions["stopAtEdge"]) {
+    this._stopAtEdge = val;
+  }
 
-  /** */
-  public constructor({
-    stopAtEdge = true
-  }: Partial<FreeControlOptions> = {}) {
+  public constructor(options: Partial<FreeControlOptions> = {}) {
     super();
 
+    const { stopAtEdge = true } = options;
+
     this._stopAtEdge = stopAtEdge;
   }
 
   /**
    * Update position after resizing
-   * @ko resize 이후에 position을 업데이트합니다
-   * @param {number} progressInPanel Previous camera's progress in active panel before resize<ko>Resize 이전 현재 선택된 패널 내에서의 카메라 progress 값</ko>
-   * @throws {FlickingError}
-   * {@link ERROR_CODE NOT_ATTACHED_TO_FLICKING} When {@link Camera#init init} is not called before
-   * <ko>{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING} {@link Camera#init init}이 이전에 호출되지 않은 경우</ko>
-   * @chainable
-   * @return {Promise<void>}
+   * @remarks
+   * Unlike the base Control, FreeControl preserves the progress within the panel instead of snapping to the panel position.
+   * @param progressInPanel - Previous camera's progress in active panel before resize
+   * @throws {@link InitializationErrors}
    */
   public updatePosition(progressInPanel: number): void {
     const flicking = getFlickingAttached(this._flicking);
@@ -72,39 +66,14 @@ class FreeControl extends Control {
 
   /**
    * Move {@link Camera} to the given position
-   * @ko {@link Camera}를 주어진 좌표로 이동합니다
-   * @param {number} position The target position to move<ko>이동할 좌표</ko>
-   * @param {number} duration Duration of the panel movement animation (unit: ms).<ko>패널 이동 애니메이션 진행 시간 (단위: ms)</ko>
-   * @param {object} [axesEvent] {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} event of {@link https://naver.github.io/egjs-axes/ Axes}
-   * <ko>{@link https://naver.github.io/egjs-axes/ Axes}의 {@link https://naver.github.io/egjs-axes/release/latest/doc/eg.Axes.html#event:release release} 이벤트</ko>
-   * @fires Flicking#moveStart
-   * @fires Flicking#move
-   * @fires Flicking#moveEnd
-   * @fires Flicking#willChange
-   * @fires Flicking#changed
-   * @fires Flicking#willRestore
-   * @fires Flicking#restored
-   * @fires Flicking#needPanel
-   * @fires Flicking#visibleChange
-   * @fires Flicking#reachEdge
-   * @throws {FlickingError}
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|When the given panel is already removed or not in the Camera's {@link Camera#range range}|
-   * |{@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|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|When the animation is interrupted by user input|
-   * <ko>
-   *
-   * |code|condition|
-   * |---|---|
-   * |{@link ERROR_CODE POSITION_NOT_REACHABLE}|주어진 패널이 제거되었거나, Camera의 {@link Camera#range range} 밖에 있을 경우|
-   * |{@link ERROR_CODE NOT_ATTACHED_TO_FLICKING}|{@link Control#init init}이 이전에 호출되지 않은 경우|
-   * |{@link ERROR_CODE ANIMATION_INTERRUPTED}|사용자 입력에 의해 애니메이션이 중단된 경우|
-   * |{@link ERROR_CODE STOP_CALLED_BY_USER}|발생된 이벤트들 중 하나라도 `stop()`이 호출된 경우|
-   *
-   * </ko>
-   * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
+   * @remarks
+   * Unlike SnapControl, FreeControl moves to the exact position without snapping to panel boundaries.
+   * @param position - The target position to move
+   * @param duration - Duration of the panel movement animation (unit: ms)
+   * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+   * @fires {@link MovementEvents}
+   * @throws {@link MovementErrors}
+   * @returns A Promise which will be resolved after reaching the target position
    */
   public moveToPosition(position: number, duration: number, axesEvent?: OnRelease) {
     const flicking = getFlickingAttached(this._flicking);
@@ -115,7 +84,9 @@ class FreeControl extends Control {
     const anchorAtPosition = camera.findAnchorIncludePosition(targetPos);
 
     if (!anchorAtPosition) {
-      return Promise.reject(new FlickingError(ERROR.MESSAGE.POSITION_NOT_REACHABLE(position), ERROR.CODE.POSITION_NOT_REACHABLE));
+      return Promise.reject(
+        new FlickingError(ERROR.MESSAGE.POSITION_NOT_REACHABLE(position), ERROR.CODE.POSITION_NOT_REACHABLE)
+      );
     }
 
     const targetPanel = anchorAtPosition.panel;
@@ -125,7 +96,12 @@ class FreeControl extends Control {
       this._triggerIndexChangeEvent(targetPanel, position, axesEvent);
     }
 
-    return this._animateToPosition({ position: this._stopAtEdge ? targetPos : position, duration, newActivePanel: targetPanel, axesEvent });
+    return this._animateToPosition({
+      position: this._stopAtEdge ? targetPos : position,
+      duration,
+      newActivePanel: targetPanel,
+      axesEvent
+    });
   }
 }