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

package/src/camera/Camera.ts

@@ -3,25 +3,44 @@
  * egjs projects are licensed under the MIT license
  */
 import { ComponentEvent } from "@egjs/component";
-
-import Flicking, { FlickingOptions } from "../Flicking";
-import FlickingError from "../core/FlickingError";
-import Panel from "../core/panel/Panel";
+import { ALIGN, CIRCULAR_FALLBACK, DIRECTION, ORDER } from "../constants/values";
 import AnchorPoint from "../core/AnchorPoint";
-import * as ERROR from "../const/error";
-import { ALIGN, CIRCULAR_FALLBACK, DIRECTION, EVENTS, ORDER } from "../const/external";
-import { checkExistence, find, getFlickingAttached, getProgress, getStyle, includes, parseAlign, toArray } from "../utils";
-import { ValueOf } from "../type/internal";
-
-import { CameraMode, BoundCameraMode, CircularCameraMode, LinearCameraMode } from "./mode";
+import Panel from "../core/panel/Panel";
+import * as ERROR from "../error/codes";
+import FlickingError from "../error/FlickingError";
+import { EVENTS } from "../event/names";
+import Flicking, { FlickingOptions } from "../Flicking";
+import { ValueOf } from "../types/internal";
+import {
+  checkExistence,
+  find,
+  getFlickingAttached,
+  getProgress,
+  getStyle,
+  includes,
+  parseAlign,
+  toArray
+} from "../utils";
+
+import { BoundCameraMode, CameraMode, CircularCameraMode, LinearCameraMode } from "./mode";
 
 export interface CameraOptions {
   align: FlickingOptions["align"];
 }
 
+/**
+ * A range with minimum and maximum values
+ */
+export interface CameraRange {
+  /** A minimum position */
+  min: number;
+  /** A maximum position */
+  max: number;
+}
+
 /**
  * A component that manages actual movement inside the viewport
- * @ko 뷰포트 내에서의 실제 움직임을 담당하는 컴포넌트
+ * @public
  */
 class Camera {
   // Options
@@ -38,7 +57,7 @@ class Camera {
   private _offset: number;
   private _circularOffset: number;
   private _circularEnabled: boolean;
-  private _range: { min: number; max: number };
+  private _range: CameraRange;
   private _visiblePanels: Panel[];
   private _anchors: AnchorPoint[];
   private _needPanelTriggered: { prev: boolean; next: boolean };
@@ -47,133 +66,122 @@ class Camera {
   // Internal states getter
   /**
    * The camera element(`.flicking-camera`)
-   * @ko 카메라 엘리먼트(`.flicking-camera`)
-   * @type {HTMLElement}
    * @readonly
    */
-  public get element() { return this._el; }
+  public get element(): HTMLElement {
+    return this._el;
+  }
   /**
    * An array of the child elements of the camera element(`.flicking-camera`)
-   * @ko 카메라 엘리먼트(`.flicking-camera`)의 자식 엘리먼트 배열
-   * @type {HTMLElement[]}
    * @readonly
    */
-  public get children() { return toArray(this._el.children) as HTMLElement[]; }
+  public get children(): HTMLElement[] {
+    return toArray(this._el.children) as HTMLElement[];
+  }
   /**
    * Current position of the camera
-   * @ko Camera의 현재 좌표
-   * @type {number}
    * @readonly
    */
-  public get position() { return this._position; }
+  public get position(): number {
+    return this._position;
+  }
   /**
-   * Align position inside the viewport where {@link Panel}'s {@link Panel#alignPosition alignPosition} should be located at
-   * @ko 패널의 정렬 기준 위치. 뷰포트 내에서 {@link Panel}의 {@link Panel#alignPosition alignPosition}이 위치해야 하는 곳입니다
-   * @type {number}
+   * Align position inside the viewport where {@link Panel}'s {@link Panel.alignPosition | alignPosition} should be located at
    * @readonly
    */
-  public get alignPosition() { return this._alignPos; }
+  public get alignPosition(): number {
+    return this._alignPos;
+  }
   /**
-   * Position offset, used for the {@link Flicking#renderOnlyVisible renderOnlyVisible} option
-   * @ko Camera의 좌표 오프셋. {@link Flicking#renderOnlyVisible renderOnlyVisible} 옵션을 위해 사용됩니다.
-   * @type {number}
-   * @default 0
+   * Position offset, used for the {@link Flicking.renderOnlyVisible | renderOnlyVisible} option
+   * @defaultValue 0
    * @readonly
    */
-  public get offset() { return this._offset - this._circularOffset; }
+  public get offset(): number {
+    return this._offset - this._circularOffset;
+  }
   /**
    * Whether the `circular` option is enabled.
-   * The {@link Flicking#circular circular} option can't be enabled when sum of the panel sizes are too small.
-   * @ko {@link Flicking#circular circular} 옵션이 활성화되었는지 여부를 나타내는 멤버 변수.
-   * {@link Flicking#circular circular} 옵션은 패널의 크기의 합이 충분하지 않을 경우 비활성화됩니다.
-   * @type {boolean}
-   * @default false
+   * @remarks
+   * The {@link Flicking.circular | circular} option can't be enabled when sum of the panel sizes are too small.
+   * @defaultValue false
    * @readonly
    */
-  public get circularEnabled() { return this._circularEnabled; }
+  public get circularEnabled(): boolean {
+    return this._circularEnabled;
+  }
   /**
    * A current camera mode
-   * @type {CameraMode}
    * @readonly
    */
-  public get mode() { return this._mode; }
+  public get mode(): CameraMode {
+    return this._mode;
+  }
   /**
-   * A range that Camera's {@link Camera#position position} can reach
-   * @ko Camera의 {@link Camera#position position}이 도달 가능한 범위
-   * @type {object}
-   * @property {number} min A minimum position<ko>최소 위치</ko>
-   * @property {number} max A maximum position<ko>최대 위치</ko>
+   * A range that Camera's {@link Camera.position | position} can reach
    * @readonly
    */
-  public get range() { return this._range; }
+  public get range(): CameraRange {
+    return this._range;
+  }
   /**
    * A difference between Camera's minimum and maximum position that can reach
-   * @ko Camera가 도달 가능한 최소/최대 좌표의 차이
-   * @type {number}
    * @readonly
    */
-  public get rangeDiff() { return this._range.max - this._range.min; }
+  public get rangeDiff(): number {
+    return this._range.max - this._range.min;
+  }
   /**
    * An array of visible panels from the current position
-   * @ko 현재 보이는 패널들의 배열
-   * @type {Panel[]}
    * @readonly
    */
-  public get visiblePanels() { return this._visiblePanels; }
+  public get visiblePanels(): Panel[] {
+    return this._visiblePanels;
+  }
   /**
    * A range of the visible area from the current position
-   * @ko 현재 위치에서 보이는 범위
-   * @type {object}
-   * @property {number} min A minimum position<ko>최소 위치</ko>
-   * @property {number} min A maximum position<ko>최대 위치</ko>
    * @readonly
    */
-  public get visibleRange() { return { min: this._position - this._alignPos, max: this._position - this._alignPos + this.size }; }
+  public get visibleRange(): CameraRange {
+    return { min: this._position - this._alignPos, max: this._position - this._alignPos + this.size };
+  }
   /**
    * An array of {@link AnchorPoint}s that Camera can be stopped at
-   * @ko 카메라가 도달 가능한 {@link AnchorPoint}의 목록
-   * @type {AnchorPoint[]}
    * @readonly
    */
-  public get anchorPoints() { return this._anchors; }
+  public get anchorPoints(): AnchorPoint[] {
+    return this._anchors;
+  }
   /**
    * A current parameters of the Camera for updating {@link AxesController}
-   * @ko {@link AxesController}를 업데이트하기 위한 현재 Camera 패러미터들
-   * @type {ControlParams}
    * @readonly
    */
-  public get controlParams() { return { range: this._range, position: this._position, circular: this._circularEnabled }; }
+  public get controlParams(): { range: CameraRange; position: number; circular: boolean } {
+    return { range: this._range, position: this._position, circular: this._circularEnabled };
+  }
   /**
    * A Boolean value indicating whether Camera's over the minimum or maximum position reachable
-   * @ko 현재 카메라가 도달 가능한 범위의 최소 혹은 최대점을 넘어섰는지를 나타냅니다
-   * @type {boolean}
    * @readonly
    */
-  public get atEdge() { return this._position <= this._range.min || this._position >= this._range.max; }
+  public get atEdge(): boolean {
+    return this._position <= this._range.min || this._position >= this._range.max;
+  }
   /**
    * Return the size of the viewport
-   * @ko 뷰포트 크기를 반환합니다
-   * @type {number}
    * @readonly
    */
-  public get size() {
+  public get size(): number {
     const flicking = this._flicking;
-    return flicking
-      ? flicking.horizontal
-        ? flicking.viewport.width
-        : flicking.viewport.height
-      : 0;
+    return flicking ? (flicking.horizontal ? flicking.viewport.width : flicking.viewport.height) : 0;
   }
 
   /**
    * Return the camera's position progress from the first panel to last panel
+   * @remarks
    * Range is from 0 to last panel's index
-   * @ko 첫번째 패널로부터 마지막 패널까지의 카메라 위치의 진행도를 반환합니다
-   * 범위는 0부터 마지막 패널의 인덱스까지입니다
-   * @type {number}
    * @readonly
    */
-  public get progress() {
+  public get progress(): number {
     const flicking = this._flicking;
     const position = this._position + this._offset;
     const nearestAnchor = this.findNearestAnchor(this._position);
@@ -195,9 +203,7 @@ class Camera {
 
     if (position < panelPos) {
       const prevPanel = nearestPanel.prev();
-      let prevPosition = prevPanel
-        ? prevPanel.position + prevPanel.offset
-        : prevRange - bounceSize[0];
+      let prevPosition = prevPanel ? prevPanel.position + prevPanel.offset : prevRange - bounceSize[0];
 
       // Looped
       if (prevPosition > panelPos) {
@@ -207,9 +213,7 @@ class Camera {
       return nearestPanel.index - 1 + getProgress(position, prevPosition, panelPos);
     } else {
       const nextPanel = nearestPanel.next();
-      let nextPosition = nextPanel
-        ? nextPanel.position + nextPanel.offset
-        : nextRange + bounceSize[1];
+      let nextPosition = nextPanel ? nextPanel.position + nextPanel.offset : nextRange + bounceSize[1];
 
       // Looped
       if (nextPosition < panelPos) {
@@ -221,30 +225,32 @@ class Camera {
   }
 
   /**
-   * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction direction} CSS property applied to the camera element(`.flicking-camera`)
-   * @ko 카메라 엘리먼트(`.flicking-camera`)에 적용된 {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction direction} CSS 속성
-   * @type {string}
+   * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction | direction} CSS property applied to the camera element(`.flicking-camera`)
    * @readonly
    */
-  public get panelOrder() { return this._panelOrder; }
+  public get panelOrder(): ValueOf<typeof ORDER> {
+    return this._panelOrder;
+  }
 
   // Options Getter
   /**
-   * A value indicating where the {@link Camera#alignPosition alignPosition} should be located at inside the viewport element
-   * @ko {@link Camera#alignPosition alignPosition}이 뷰포트 엘리먼트 내의 어디에 위치해야 하는지를 나타내는 값
-   * @type {ALIGN | string | number}
+   * A value indicating where the {@link Camera.alignPosition | alignPosition} should be located at inside the viewport element
    */
-  public get align() { return this._align; }
+  public get align(): FlickingOptions["align"] {
+    return this._align;
+  }
 
   // Options Setter
   public set align(val: FlickingOptions["align"]) {
     this._align = val;
   }
 
-  /** */
-  public constructor(flicking: Flicking, {
-    align = ALIGN.CENTER
-  }: Partial<CameraOptions> = {}) {
+  /**
+   * Creates a new Camera instance
+   * @param flicking - An instance of {@link Flicking}
+   * @param options - Options for the Camera
+   */
+  public constructor(flicking: Flicking, { align = ALIGN.CENTER }: Partial<CameraOptions> = {}) {
     this._flicking = flicking;
     this._resetInternalValues();
 
@@ -254,11 +260,10 @@ class Camera {
 
   /**
    * Initialize Camera
-   * @ko Camera를 초기화합니다
-   * @throws {FlickingError}
-   * {@link ERROR_CODE VAL_MUST_NOT_NULL} If the camera element(`.flicking-camera`) does not exist inside viewport element
-   * <ko>{@link ERROR_CODE VAL_MUST_NOT_NULL} 뷰포트 엘리먼트 내부에 카메라 엘리먼트(`.flicking-camera`)가 존재하지 않을 경우</ko>
-   * @return {this}
+   * @remarks
+   * This method is called automatically during {@link Flicking.init}. It finds the camera element inside the viewport.
+   * @throws {@link InitializationErrors}
+   * @returns The current instance for method chaining
    */
   public init(): this {
     const viewportEl = this._flicking.viewport.element;
@@ -275,8 +280,9 @@ class Camera {
 
   /**
    * Destroy Camera and return to initial state
-   * @ko Camera를 초기 상태로 되돌립니다
-   * @return {void}
+   * @remarks
+   * This method resets all internal values to their initial state.
+   * @returns The current instance for method chaining
    */
   public destroy(): this {
     this._resetInternalValues();
@@ -285,12 +291,10 @@ class Camera {
 
   /**
    * Move to the given position and apply CSS transform
-   * @ko 해당 좌표로 이동하고, CSS transform을 적용합니다
-   * @param {number} pos A new position<ko>움직일 위치</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>
-   * @return {this}
+   * @remarks
+   * This method updates the camera position, toggles panels for circular mode, and refreshes visible panels.
+   * @param pos - A new position
+   * @throws {@link InitializationErrors}
    */
   public lookAt(pos: number): void {
     const prevOffset = this._offset;
@@ -320,11 +324,10 @@ class Camera {
 
   /**
    * Return a previous {@link AnchorPoint} of given {@link AnchorPoint}
+   * @remarks
    * If it does not exist, return `null` instead
-   * @ko 주어진 {@link AnchorPoint}의 이전 {@link AnchorPoint}를 반환합니다
-   * 존재하지 않을 경우 `null`을 반환합니다
-   * @param {AnchorPoint} anchor A reference {@link AnchorPoint}<ko>기준 {@link AnchorPoint}</ko>
-   * @return {AnchorPoint | null} The previous {@link AnchorPoint}<ko>이전 {@link AnchorPoint}</ko>
+   * @param anchor - A reference {@link AnchorPoint}
+   * @returns The previous {@link AnchorPoint}
    */
   public getPrevAnchor(anchor: AnchorPoint): AnchorPoint | null {
     if (!this._circularEnabled || anchor.index !== 0) {
@@ -344,11 +347,10 @@ class Camera {
 
   /**
    * Return a next {@link AnchorPoint} of given {@link AnchorPoint}
+   * @remarks
    * If it does not exist, return `null` instead
-   * @ko 주어진 {@link AnchorPoint}의 다음 {@link AnchorPoint}를 반환합니다
-   * 존재하지 않을 경우 `null`을 반환합니다
-   * @param {AnchorPoint} anchor A reference {@link AnchorPoint}<ko>기준 {@link AnchorPoint}</ko>
-   * @return {AnchorPoint | null} The next {@link AnchorPoint}<ko>다음 {@link AnchorPoint}</ko>
+   * @param anchor - A reference {@link AnchorPoint}
+   * @returns The next {@link AnchorPoint}
    */
   public getNextAnchor(anchor: AnchorPoint): AnchorPoint | null {
     const anchors = this._anchors;
@@ -369,13 +371,13 @@ class Camera {
 
   /**
    * Return the camera's position progress in the panel below
-   * Value is from 0 to 1 when the camera's inside panel
+   * @remarks
+   * Value is from 0 to 1 when the camera's inside panel.
    * Value can be lower than 0 or bigger than 1 when it's in the margin area
-   * @ko 현재 카메라 아래 패널에서의 위치 진행도를 반환합니다
-   * 반환값은 카메라가 패널 내부에 있을 경우 0부터 1까지의 값을 갖습니다
-   * 패널의 margin 영역에 있을 경우 0보다 작거나 1보다 큰 값을 반환할 수 있습니다
+   * @param panel - A panel to check
+   * @returns Progress value from 0 to 1 (or outside this range when in margin area)
    */
-  public getProgressInPanel(panel: Panel) {
+  public getProgressInPanel(panel: Panel): number {
     const panelRange = panel.range;
 
     return (this._position - panelRange.min) / (panelRange.max - panelRange.min);
@@ -383,11 +385,10 @@ class Camera {
 
   /**
    * Return {@link AnchorPoint} that includes given position
+   * @remarks
    * If there's no {@link AnchorPoint} that includes the given position, return `null` instead
-   * @ko 주어진 좌표를 포함하는 {@link AnchorPoint}를 반환합니다
-   * 주어진 좌표를 포함하는 {@link AnchorPoint}가 없을 경우 `null`을 반환합니다
-   * @param {number} position A position to check<ko>확인할 좌표</ko>
-   * @return {AnchorPoint | null} The {@link AnchorPoint} that includes the given position<ko>해당 좌표를 포함하는 {@link AnchorPoint}</ko>
+   * @param position - A position to check
+   * @returns The {@link AnchorPoint} that includes the given position
    */
   public findAnchorIncludePosition(position: number): AnchorPoint | null {
     return this._mode.findAnchorIncludePosition(position);
@@ -395,20 +396,18 @@ class Camera {
 
   /**
    * Return {@link AnchorPoint} nearest to given position
+   * @remarks
    * If there're no {@link AnchorPoint}s, return `null` instead
-   * @ko 해당 좌표에서 가장 가까운 {@link AnchorPoint}를 반환합니다
-   * {@link AnchorPoint}가 하나도 없을 경우 `null`을 반환합니다
-   * @param {number} position A position to check<ko>확인할 좌표</ko>
-   * @return {AnchorPoint | null} The {@link AnchorPoint} nearest to the given position<ko>해당 좌표에 가장 인접한 {@link AnchorPoint}</ko>
+   * @param position - A position to check
+   * @returns The {@link AnchorPoint} nearest to the given position
    */
   public findNearestAnchor(position: number): AnchorPoint | null {
     return this._mode.findNearestAnchor(position);
   }
 
   /**
-   * Return {@link AnchorPoint} that matches {@link Flicking#currentPanel}
-   * @ko 현재 {@link Flicking#currentPanel}에 해당하는 {@link AnchorPoint}를 반환합니다
-   * @return {AnchorPoint | null}
+   * Return {@link AnchorPoint} that matches {@link Flicking.currentPanel}
+   * @returns The {@link AnchorPoint} that matches current panel
    */
   public findActiveAnchor(): AnchorPoint | null {
     const flicking = getFlickingAttached(this._flicking);
@@ -416,14 +415,16 @@ class Camera {
 
     if (!activePanel) return null;
 
-    return find(this._anchors, anchor => anchor.panel.index === activePanel.index) ?? this.findNearestAnchor(activePanel.position);
+    return (
+      find(this._anchors, anchor => anchor.panel.index === activePanel.index) ??
+      this.findNearestAnchor(activePanel.position)
+    );
   }
 
   /**
    * Clamp the given position between camera's range
-   * @ko 주어진 좌표를 Camera가 도달 가능한 범위 사이의 값으로 만듭니다
-   * @param {number} position A position to clamp<ko>범위를 제한할 좌표</ko>
-   * @return {number} A clamped position<ko>범위 제한된 좌표</ko>
+   * @param position - A position to clamp
+   * @returns A clamped position
    */
   public clampToReachablePosition(position: number): number {
     return this._mode.clampToReachablePosition(position);
@@ -431,9 +432,8 @@ class Camera {
 
   /**
    * Check whether the given panel is inside of the Camera's range
-   * @ko 해당 {@link Panel}이 Camera가 도달 가능한 범위 내에 있는지를 반환합니다
-   * @param panel An instance of {@link Panel} to check<ko>확인할 {@link Panel}의 인스턴스</ko>
-   * @return {boolean} Whether the panel's inside Camera's range<ko>도달 가능한 범위 내에 해당 패널이 존재하는지 여부</ko>
+   * @param panel - An instance of {@link Panel} to check
+   * @returns Whether the panel's inside Camera's range
    */
   public canReach(panel: Panel): boolean {
     return this._mode.canReach(panel);
@@ -441,29 +441,21 @@ class Camera {
 
   /**
    * Check whether the given panel element is visible at the current position
-   * @ko 현재 좌표에서 해당 패널 엘리먼트를 볼 수 있는지 여부를 반환합니다
-   * @param panel An instance of {@link Panel} to check<ko>확인할 {@link Panel}의 인스턴스</ko>
-   * @return Whether the panel element is visible at the current position<ko>현재 위치에서 해당 패널 엘리먼트가 보이는지 여부</ko>
+   * @param panel - An instance of {@link Panel} to check
+   * @returns Whether the panel element is visible at the current position
    */
   public canSee(panel: Panel): boolean {
     return this._mode.canSee(panel);
   }
 
   /**
-   * Update {@link Camera#range range} of Camera
-   * @ko Camera의 {@link Camera#range range}를 업데이트합니다
-   * @method
-   * @abstract
-   * @memberof Camera
-   * @instance
-   * @name updateRange
-   * @chainable
-   * @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>
-   * @return {this}
+   * Update {@link Camera.range | range} of Camera
+   * @remarks
+   * This method recalculates the camera range based on the current panel positions and circular mode settings.
+   * @throws {@link InitializationErrors}
+   * @returns The current instance for method chaining
    */
-  public updateRange() {
+  public updateRange(): this {
     const flicking = getFlickingAttached(this._flicking);
     const renderer = flicking.renderer;
     const panels = renderer.panels;
@@ -477,17 +469,13 @@ class Camera {
   }
 
   /**
-   * Update Camera's {@link Camera#alignPosition alignPosition}
-   * @ko Camera의 {@link Camera#alignPosition alignPosition}을 업데이트합니다
-   * @chainable
-   * @return {this}
+   * Update Camera's {@link Camera.alignPosition | alignPosition}
+   * @returns The current instance for method chaining
    */
   public updateAlignPos(): this {
     const align = this._align;
 
-    const alignVal = typeof align === "object"
-      ? (align as { camera: string | number }).camera
-      : align;
+    const alignVal = typeof align === "object" ? (align as { camera: string | number }).camera : align;
 
     this._alignPos = parseAlign(alignVal, this.size);
 
@@ -495,13 +483,11 @@ class Camera {
   }
 
   /**
-   * Update Camera's {@link Camera#anchorPoints anchorPoints}
-   * @ko Camera의 {@link Camera#anchorPoints anchorPoints}를 업데이트합니다
-   * @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 {this}
+   * Update Camera's {@link Camera.anchorPoints | anchorPoints}
+   * @remarks
+   * Anchor points are positions where the camera can stop. This method recalculates them based on the current mode.
+   * @throws {@link InitializationErrors}
+   * @returns The current instance for method chaining
    */
   public updateAnchors(): this {
     this._anchors = this._mode.getAnchors();
@@ -511,14 +497,11 @@ class Camera {
 
   /**
    * Update Viewport's height to visible panel's max height
-   * @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 {this}
-   */
-  public updateAdaptiveHeight() {
+   * @remarks
+   * This method only takes effect when {@link FlickingOptions.horizontal | horizontal} is `true` and {@link FlickingOptions.adaptive | adaptive} is enabled.
+   * @throws {@link InitializationErrors}
+   */
+  public updateAdaptiveHeight(): void {
     const flicking = getFlickingAttached(this._flicking);
     const activePanel = flicking.control.activePanel;
     const visiblePanels = flicking.visiblePanels;
@@ -531,10 +514,8 @@ class Camera {
 
     if (!flicking.horizontal || !flicking.adaptive || !selectedPanels.length) return;
 
-
     const maxHeight = Math.max(...selectedPanels.map(panel => panel.height));
 
-
     flicking.viewport.setSize({
       height: maxHeight
     });
@@ -542,9 +523,7 @@ class Camera {
 
   /**
    * Update current offset of the camera
-   * @ko 현재 카메라의 오프셋을 업데이트합니다
-   * @chainable
-   * @return {this}
+   * @returns The current instance for method chaining
    */
   public updateOffset(): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -563,9 +542,8 @@ class Camera {
   }
 
   /**
-   * Update direction to match the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction direction} CSS property applied to the camera element
-   * @ko 카메라 엘리먼트에 적용된 {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction direction} CSS 속성에 맞게 방향을 업데이트합니다
-   * @return {this}
+   * Update direction to match the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction | direction} CSS property applied to the camera element
+   * @returns The current instance for method chaining
    */
   public updatePanelOrder(): this {
     const flicking = getFlickingAttached(this._flicking);
@@ -585,10 +563,8 @@ class Camera {
   }
 
   /**
-   * Reset the history of {@link Flicking#event:needPanel needPanel} events so it can be triggered again
-   * @ko 발생한 {@link Flicking#event:needPanel needPanel} 이벤트들을 초기화하여 다시 발생할 수 있도록 합니다
-   * @chainable
-   * @return {this}
+   * Reset the history of {@link Flicking.event:needPanel | needPanel} events so it can be triggered again
+   * @returns The current instance for method chaining
    */
   public resetNeedPanelHistory(): this {
     this._needPanelTriggered = { prev: false, next: false };
@@ -597,8 +573,7 @@ class Camera {
 
   /**
    * Apply "transform" style with the current position to camera element
-   * @ko 현재 위치를 기준으로한 transform 스타일을 카메라 엘리먼트에 적용합니다.
-   * @return {this}
+   * @returns The current instance for method chaining
    */
   public applyTransform(): this {
     const el = this._el;
@@ -616,6 +591,11 @@ class Camera {
     return this;
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Resets all internal state values to their defaults. Called during construction and destruction.
+   */
   private _resetInternalValues() {
     this._position = 0;
     this._lookedOffset = 0;
@@ -629,6 +609,11 @@ class Camera {
     this._needPanelTriggered = { prev: false, next: false };
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Updates the list of visible panels and triggers {@link VisibleChangeEvent} if panels were added or removed.
+   */
   private _refreshVisiblePanels() {
     const flicking = getFlickingAttached(this._flicking);
     const panels = flicking.renderer.panels;
@@ -642,15 +627,22 @@ class Camera {
 
     if (added.length > 0 || removed.length > 0) {
       void flicking.renderer.render().then(() => {
-        flicking.trigger(new ComponentEvent(EVENTS.VISIBLE_CHANGE, {
-          added,
-          removed,
-          visiblePanels: newVisiblePanels
-        }));
+        flicking.trigger(
+          new ComponentEvent(EVENTS.VISIBLE_CHANGE, {
+            added,
+            removed,
+            visiblePanels: newVisiblePanels
+          })
+        );
       });
     }
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Checks if the camera is near the edges and triggers {@link NeedPanelEvent} for infinite scrolling implementations.
+   */
   private _checkNeedPanel(): void {
     const needPanelTriggered = this._needPanelTriggered;
 
@@ -686,7 +678,7 @@ class Camera {
     if (!needPanelTriggered.prev) {
       const firstPanelPrev = firstPanel.range.min;
 
-      if (cameraPrev <= (firstPanelPrev + needPanelThreshold) || cameraPosition <= (cameraRange.min + needPanelThreshold)) {
+      if (cameraPrev <= firstPanelPrev + needPanelThreshold || cameraPosition <= cameraRange.min + needPanelThreshold) {
         flicking.trigger(new ComponentEvent(EVENTS.NEED_PANEL, { direction: DIRECTION.PREV }));
         needPanelTriggered.prev = true;
       }
@@ -695,13 +687,18 @@ class Camera {
     if (!needPanelTriggered.next) {
       const lastPanelNext = lastPanel.range.max;
 
-      if (cameraNext >= (lastPanelNext - needPanelThreshold) || cameraPosition >= (cameraRange.max - needPanelThreshold)) {
+      if (cameraNext >= lastPanelNext - needPanelThreshold || cameraPosition >= cameraRange.max - needPanelThreshold) {
         flicking.trigger(new ComponentEvent(EVENTS.NEED_PANEL, { direction: DIRECTION.NEXT }));
         needPanelTriggered.next = true;
       }
     }
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Checks if the camera has reached the edge of the range and triggers {@link ReachEdgeEvent}.
+   */
   private _checkReachEnd(prevPos: number, newPos: number): void {
     const flicking = getFlickingAttached(this._flicking);
     const range = this._range;
@@ -713,11 +710,18 @@ class Camera {
 
     const direction = newPos <= range.min ? DIRECTION.PREV : DIRECTION.NEXT;
 
-    flicking.trigger(new ComponentEvent(EVENTS.REACH_EDGE, {
-      direction
-    }));
+    flicking.trigger(
+      new ComponentEvent(EVENTS.REACH_EDGE, {
+        direction
+      })
+    );
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Checks for CSS transform support and stores the vendor-prefixed property name. Throws if transforms are not supported.
+   */
   private _checkTranslateSupport = () => {
     const transforms = ["webkitTransform", "msTransform", "MozTransform", "OTransform", "transform"];
 
@@ -736,6 +740,11 @@ class Camera {
     this._transform = transformName;
   };
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Updates the camera mode based on {@link FlickingOptions.circular | circular} and {@link FlickingOptions.bound | bound} options.
+   */
   private _updateMode() {
     const flicking = getFlickingAttached(this._flicking);
 
@@ -748,20 +757,22 @@ class Camera {
       } else {
         const fallbackMode = flicking.circularFallback;
 
-        this._mode = fallbackMode === CIRCULAR_FALLBACK.BOUND
-          ? new BoundCameraMode(flicking)
-          : new LinearCameraMode(flicking);
+        this._mode =
+          fallbackMode === CIRCULAR_FALLBACK.BOUND ? new BoundCameraMode(flicking) : new LinearCameraMode(flicking);
       }
 
       this._circularEnabled = canSetCircularMode;
     } else {
-      this._mode = flicking.bound
-        ? new BoundCameraMode(flicking)
-        : new LinearCameraMode(flicking);
+      this._mode = flicking.bound ? new BoundCameraMode(flicking) : new LinearCameraMode(flicking);
       this._circularEnabled = false;
     }
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Toggles panel positions for circular mode. Returns true if any panel was toggled.
+   */
   private _togglePanels(prevPos: number, pos: number): boolean {
     if (pos === prevPos) return false;