@egjs/flicking 4.15.0 → 4.16.0-beta.0

package/src/core/panel/Panel.ts

@@ -2,23 +2,43 @@
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
+
+import { ALIGN, DIRECTION } from "../../constants/values";
 import Flicking from "../../Flicking";
+import { LiteralUnion, ValueOf } from "../../types/internal";
+import { SetSizeParams } from "../../types/params";
 import { getElementSize, getProgress, getStyle, parseAlign, setSize } from "../../utils";
-import { ALIGN, DIRECTION } from "../../const/external";
-import { LiteralUnion, ValueOf } from "../../type/internal";
 
 import ElementProvider from "./provider/ElementProvider";
 
 export interface PanelOptions {
+  /** An initial index of the panel */
   index: number;
+  /** An initial {@link Flicking.align | align} value of the panel */
   align: LiteralUnion<ValueOf<typeof ALIGN>> | number;
+  /** The Flicking instance that this panel belongs to */
   flicking: Flicking;
+  /** A provider instance that returns the actual html element */
   elementProvider: ElementProvider;
 }
 
+export interface PanelMarginInfo {
+  /** CSS `margin-left` when the {@link Flicking.horizontal | horizontal} is `true`, and `margin-top` else */
+  prev: number;
+  /** CSS `margin-right` when the {@link Flicking.horizontal | horizontal} is `true`, and `margin-bottom` else */
+  next: number;
+}
+
+export interface PanelBoundingBoxRange {
+  /** Bounding box's left({@link Flicking.horizontal | horizontal}: true) / top({@link Flicking.horizontal | horizontal}: false) */
+  min: number;
+  /** Bounding box's right({@link Flicking.horizontal | horizontal}: true) / bottom({@link Flicking.horizontal | horizontal}: false) */
+  max: number;
+}
+
 /**
  * A slide data component that holds information of a single HTMLElement
- * @ko 슬라이드 데이터 컴포넌트로, 단일 HTMLElement의 정보를 갖고 있습니다
+ * @public
  */
 class Panel {
   // Internal States
@@ -28,7 +48,7 @@ class Panel {
   protected _pos: number;
   protected _size: number;
   protected _height: number;
-  protected _margin: { prev: number; next: number };
+  protected _margin: PanelMarginInfo;
   protected _alignPos: number; // Actual align pos
   protected _rendered: boolean;
   protected _removed: boolean;
@@ -43,124 +63,118 @@ class Panel {
   // Internal States Getter
   /**
    * `HTMLElement` that panel's referencing
-   * @ko 패널이 참조하고 있는 `HTMLElement`
-   * @type {HTMLElement}
    * @readonly
    */
-  public get element() { return this._elProvider.element; }
+  public get element(): HTMLElement {
+    return this._elProvider.element;
+  }
   /**
    * @internal
    * @readonly
    */
-  public get elementProvider() { return this._elProvider; }
+  public get elementProvider(): ElementProvider {
+    return this._elProvider;
+  }
   /**
    * Index of the panel
-   * @ko 패널의 인덱스
-   * @type {number}
    * @readonly
    */
-  public get index() { return this._index; }
+  public get index(): number {
+    return this._index;
+  }
   /**
-   * Position of the panel, including {@link Panel#alignPosition alignPosition}
-   * @ko 패널의 현재 좌표, {@link Panel#alignPosition alignPosition}을 포함하고 있습니다
-   * @type {number}
+   * Position of the panel, including {@link Panel.alignPosition | alignPosition}
    * @readonly
    */
-  public get position() { return this._pos + this._alignPos; }
+  public get position(): number {
+    return this._pos + this._alignPos;
+  }
   /**
    * Cached size of the panel element
-   * This is equal to {@link Panel#element element}'s `offsetWidth` if {@link Flicking#horizontal horizontal} is `true`, and `offsetHeight` else
-   * @ko 패널 엘리먼트의 캐시된 크기
-   * 이 값은 {@link Flicking#horizontal horizontal}이 `true`일 경우 {@link Panel#element element}의 `offsetWidth`와 동일하고, `false`일 경우 `offsetHeight`와 동일합니다
-   * @type {number}
+   * @remarks
+   * This is equal to {@link Panel.element | element}'s `offsetWidth` if {@link Flicking.horizontal | horizontal} is `true`, and `offsetHeight` else
    * @readonly
    */
-  public get size() { return this._size; }
+  public get size(): number {
+    return this._size;
+  }
   /**
    * Panel's size including CSS `margin`
-   * This value includes {@link Panel#element element}'s margin left/right if {@link Flicking#horizontal horizontal} is `true`, and margin top/bottom else
-   * @ko CSS `margin`을 포함한 패널의 크기
-   * 이 값은 {@link Flicking#horizontal horizontal}이 `true`일 경우 margin left/right을 포함하고, `false`일 경우 margin top/bottom을 포함합니다
-   * @type {number}
+   * @remarks
+   * This value includes {@link Panel.element | element}'s margin left/right if {@link Flicking.horizontal | horizontal} is `true`, and margin top/bottom else
    * @readonly
    */
-  public get sizeIncludingMargin() { return this._size + this._margin.prev + this._margin.next; }
+  public get sizeIncludingMargin(): number {
+    return this._size + this._margin.prev + this._margin.next;
+  }
   /**
    * Height of the panel element
-   * @ko 패널 엘리먼트의 높이
-   * @type {number}
    * @readonly
    */
-  public get height() { return this._height; }
+  public get height(): number {
+    return this._height;
+  }
   /**
    * Cached CSS `margin` value of the panel element
-   * @ko 패널 엘리먼트의 CSS `margin` 값
-   * @type {object}
-   * @property {number} prev CSS `margin-left` when the {@link Flicking#horizontal horizontal} is `true`, and `margin-top` else
-   * <ko>{@link Flicking#horizontal horizontal}이 `true`일 경우 `margin-left`, `false`일 경우 `margin-top`에 해당하는 값</ko>
-   * @property {number} next CSS `margin-right` when the {@link Flicking#horizontal horizontal} is `true`, and `margin-bottom` else
-   * <ko>{@link Flicking#horizontal horizontal}이 `true`일 경우 `margin-right`, `false`일 경우 `margin-bottom`에 해당하는 값</ko>
    * @readonly
    */
-  public get margin() { return this._margin; }
+  public get margin(): PanelMarginInfo {
+    return this._margin;
+  }
   /**
-   * Align position inside the panel where {@link Camera}'s {@link Camera#alignPosition alignPosition} inside viewport should be located at
-   * @ko 패널의 정렬 기준 위치. {@link Camera}의 뷰포트 내에서의 {@link Camera#alignPosition alignPosition}이 위치해야 하는 곳입니다
-   * @type {number}
+   * Align position inside the panel where {@link Camera}'s {@link Camera.alignPosition | alignPosition} inside viewport should be located at
    * @readonly
    */
-  public get alignPosition() { return this._alignPos; }
+  public get alignPosition(): number {
+    return this._alignPos;
+  }
   /**
-   * A value indicating whether the panel's {@link Flicking#remove remove}d
-   * @ko 패널이 {@link Flicking#remove remove}되었는지 여부를 나타내는 값
-   * @type {boolean}
+   * A value indicating whether the panel's {@link Flicking.remove | remove}d
    * @readonly
    */
-  public get removed() { return this._removed; }
+  public get removed(): boolean {
+    return this._removed;
+  }
   /**
    * A value indicating whether the panel's element is being rendered on the screen
-   * @ko 패널의 엘리먼트가 화면상에 렌더링되고있는지 여부를 나타내는 값
-   * @type {boolean}
    * @readonly
    */
-  public get rendered() { return this._rendered; }
+  public get rendered(): boolean {
+    return this._rendered;
+  }
   /**
    * A value indicating whether the panel's image/video is not loaded and waiting for resize
-   * @ko 패널 내부의 이미지/비디오가 아직 로드되지 않아 {@link Panel#resize resize}될 것인지를 나타내는 값
-   * @type {boolean}
    * @readonly
    */
-  public get loading() { return this._loading; }
+  public get loading(): boolean {
+    return this._loading;
+  }
   /**
    * Panel element's range of the bounding box
-   * @ko 패널 엘리먼트의 Bounding box 범위
-   * @type {object}
-   * @property {number} [min] Bounding box's left({@link Flicking#horizontal horizontal}: true) / top({@link Flicking#horizontal horizontal}: false)
-   * @property {number} [max] Bounding box's right({@link Flicking#horizontal horizontal}: true) / bottom({@link Flicking#horizontal horizontal}: false)
    * @readonly
    */
-  public get range() { return { min: this._pos, max: this._pos + this._size }; }
+  public get range(): PanelBoundingBoxRange {
+    return { min: this._pos, max: this._pos + this._size };
+  }
   /**
    * A value indicating whether the panel's position is toggled by circular behavior
-   * @ko 패널의 위치가 circular 동작에 의해 토글되었는지 여부를 나타내는 값
-   * @type {boolean}
    * @readonly
    */
-  public get toggled() { return this._toggled; }
+  public get toggled(): boolean {
+    return this._toggled;
+  }
   /**
    * A direction where the panel's position is toggled
-   * @ko 패널의 위치가 circular 동작에 의해 토글되는 방향
-   * @type {DIRECTION}
    * @readonly
    */
-  public get toggleDirection() { return this._toggleDirection; }
+  public get toggleDirection(): ValueOf<typeof DIRECTION> {
+    return this._toggleDirection;
+  }
   /**
-   * Actual position offset determined by {@link Panel#order}
-   * @ko {@link Panel#order}에 의한 실제 위치 변경값
-   * @type {number}
+   * Actual position offset determined by {@link Panel.order}
    * @readonly
    */
-  public get offset() {
+  public get offset(): number {
     const toggleDirection = this._toggleDirection;
     const cameraRangeDiff = this._flicking.camera.rangeDiff;
 
@@ -173,11 +187,9 @@ class Panel {
 
   /**
    * Progress of movement between previous or next panel relative to current panel
-   * @ko 이 패널로부터 이전/다음 패널으로의 이동 진행률
-   * @type {number}
    * @readonly
    */
-  public get progress() {
+  public get progress(): number {
     const flicking = this._flicking;
 
     return this.index - flicking.camera.progress;
@@ -185,11 +197,9 @@ class Panel {
 
   /**
    * Progress of movement between points that panel is completely invisible outside of viewport(prev direction: -1, selected point: 0, next direction: 1)
-   * @ko 현재 패널이 뷰포트 영역 밖으로 완전히 사라지는 지점을 기준으로 하는 진행도(prev방향: -1, 선택 지점: 0, next방향: 1)
-   * @type {number}
    * @readonly
    */
-  public get outsetProgress() {
+  public get outsetProgress(): number {
     const position = this.position + this.offset;
     const alignPosition = this._alignPos;
     const camera = this._flicking.camera;
@@ -212,11 +222,9 @@ class Panel {
 
   /**
    * Percentage of area where panel is visible in the viewport
-   * @ko 뷰포트 안에서 패널이 보이는 영역의 비율
-   * @type {number}
    * @readonly
    */
-  public get visibleRatio() {
+  public get visibleRatio(): number {
     const range = this.range;
     const size = this._size;
     const offset = this.offset;
@@ -243,15 +251,17 @@ class Panel {
     return visibleSize / size;
   }
 
-  public set loading(val: boolean) { this._loading = val; }
+  public set loading(val: boolean) {
+    this._loading = val;
+  }
 
   // Options Getter
   /**
-   * A value indicating where the {@link Panel#alignPosition alignPosition} should be located at inside the panel element
-   * @ko {@link Panel#alignPosition alignPosition}이 패널 내의 어디에 위치해야 하는지를 나타내는 값
-   * @type {Constants.ALIGN | string | number}
+   * A value indicating where the {@link Panel.alignPosition | alignPosition} should be located at inside the panel element
    */
-  public get align() { return this._align; }
+  public get align(): PanelOptions["align"] {
+    return this._align;
+  }
 
   // Options Setter
   public set align(val: PanelOptions["align"]) {
@@ -260,18 +270,12 @@ class Panel {
   }
 
   /**
-   * @param {object} options An options object<ko>옵션 오브젝트</ko>
-   * @param {number} [options.index] An initial index of the panel<ko>패널의 초기 인덱스</ko>
-   * @param {Constants.ALIGN | string | number} [options.align] An initial {@link Flicking#align align} value of the panel<ko>패널의 초기 {@link Flicking#align align}값</ko>
-   * @param {Flicking} [options.flicking] A Flicking instance panel's referencing<ko>패널이 참조하는 {@link Flicking} 인스턴스</ko>
-   * @param {Flicking} [options.elementProvider] A provider instance that redirects elements<ko>실제 엘리먼트를 반환하는 엘리먼트 공급자의 인스턴스</ko>
+   * Creates a new Panel instance
+   * @param panelOptions - Options for creating the panel
    */
-  public constructor({
-    index,
-    align,
-    flicking,
-    elementProvider
-  }: PanelOptions) {
+  public constructor(panelOptions: PanelOptions) {
+    const { index, align, flicking, elementProvider } = panelOptions;
+
     this._index = index;
     this._flicking = flicking;
     this._elProvider = elementProvider;
@@ -285,8 +289,9 @@ class Panel {
   }
 
   /**
-   * Mark panel element to be appended on the camera element
    * @internal
+   * @privateRemarks
+   * Marks this panel to be rendered on the camera element.
    */
   public markForShow() {
     this._rendered = true;
@@ -294,8 +299,9 @@ class Panel {
   }
 
   /**
-   * Mark panel element to be removed from the camera element
    * @internal
+   * @privateRemarks
+   * Marks this panel to be hidden from the camera element.
    */
   public markForHide() {
     this._rendered = false;
@@ -304,22 +310,15 @@ class Panel {
 
   /**
    * Update size of the panel
-   * @ko 패널의 크기를 갱신합니다
-   * @param {object} cached Predefined cached size of the panel<ko>사전에 캐시된 패널의 크기 정보</ko>
-   * @chainable
-   * @return {this}
-   */
-  public resize(cached?: {
-    size: number;
-    height?: number;
-    margin: { prev: number; next: number };
-  }): this {
+   * @remarks
+   * This method recalculates the panel's size, margin, and position based on the current DOM state.
+   * @param cached - Predefined cached size of the panel
+   * @returns The current instance for method chaining
+   */
+  public resize(cached?: { size: number; height?: number; margin: { prev: number; next: number } }): this {
     const el = this.element;
     const flicking = this._flicking;
-    const {
-      horizontal,
-      useFractionalSize
-    } = flicking;
+    const { horizontal, useFractionalSize } = flicking;
 
     if (!el) {
       return this;
@@ -328,13 +327,15 @@ class Panel {
     if (cached) {
       this._size = cached.size;
       this._margin = { ...cached.margin };
-      this._height = cached.height ?? getElementSize({
-        el,
-        horizontal: false,
-        useFractionalSize,
-        useOffset: true,
-        style: getStyle(el)
-      });
+      this._height =
+        cached.height ??
+        getElementSize({
+          el,
+          horizontal: false,
+          useFractionalSize,
+          useOffset: true,
+          style: getStyle(el)
+        });
     } else {
       const elStyle = getStyle(el);
 
@@ -348,21 +349,22 @@ class Panel {
 
       this._margin = horizontal
         ? {
-          prev: parseFloat(elStyle.marginLeft || "0"),
-          next: parseFloat(elStyle.marginRight || "0")
-        } : {
-          prev: parseFloat(elStyle.marginTop || "0"),
-          next: parseFloat(elStyle.marginBottom || "0")
-        };
+            prev: parseFloat(elStyle.marginLeft || "0"),
+            next: parseFloat(elStyle.marginRight || "0")
+          }
+        : {
+            prev: parseFloat(elStyle.marginTop || "0"),
+            next: parseFloat(elStyle.marginBottom || "0")
+          };
 
       this._height = horizontal
         ? getElementSize({
-          el,
-          horizontal: false,
-          useFractionalSize,
-          useOffset: true,
-          style: elStyle
-        })
+            el,
+            horizontal: false,
+            useFractionalSize,
+            useOffset: true,
+            style: elStyle
+          })
         : this._size;
     }
 
@@ -373,37 +375,33 @@ class Panel {
   }
 
   /**
-   * Change panel's size. This will change the actual size of the panel element by changing its CSS width/height property
-   * @ko 패널 크기를 변경합니다. 패널 엘리먼트에 해당 크기의 CSS width/height를 적용합니다
-   * @param {object} [size] New panel size<ko>새 패널 크기</ko>
-   * @param {number|string} [size.width] CSS string or number(in px)<ko>CSS 문자열 또는 숫자(px)</ko>
-   * @param {number|string} [size.height] CSS string or number(in px)<ko>CSS 문자열 또는 숫자(px)</ko>
-   * @chainable
-   * @return {this}
+   * Change panel's size
+   * @remarks
+   * This will change the actual size of the panel element by changing its CSS width/height property.
+   * @param size - {@link SetSizeParams}
+   * @returns The current instance for method chaining
    */
-  public setSize(size: Partial<{
-    width: number | string;
-    height: number | string;
-  }>): this {
+  public setSize(size: SetSizeParams): this {
     setSize(this.element, size);
 
     return this;
   }
 
   /**
-   * Check whether the given element is inside of this panel's {@link Panel#element element}
-   * @ko 해당 엘리먼트가 이 패널의 {@link Panel#element element} 내에 포함되어 있는지를 반환합니다
-   * @param {HTMLElement} element The HTMLElement to check<ko>확인하고자 하는 HTMLElement</ko>
-   * @return {boolean} A Boolean value indicating the element is inside of this panel {@link Panel#element element}<ko>패널의 {@link Panel#element element}내에 해당 엘리먼트 포함 여부</ko>
+   * Check whether the given element is inside of this panel's {@link Panel.element | element}
+   * @remarks
+   * This is useful for determining which panel contains a clicked element.
+   * @param element - The HTMLElement to check
+   * @returns A Boolean value indicating the element is inside of this panel {@link Panel.element | element}
    */
   public contains(element: HTMLElement): boolean {
     return !!this.element?.contains(element);
   }
 
   /**
-   * Reset internal state and set {@link Panel#removed removed} to `true`
-   * @ko 내부 상태를 초기화하고 {@link Panel#removed removed}를 `true`로 설정합니다.
-   * @return {void}
+   * Reset internal state and set {@link Panel.removed | removed} to `true`
+   * @remarks
+   * After calling this method, the panel should no longer be used.
    */
   public destroy(): void {
     this._resetInternalStates();
@@ -411,11 +409,10 @@ class Panel {
   }
 
   /**
-   * Check whether the given position is inside of this panel's {@link Panel#range range}
-   * @ko 주어진 좌표가 현재 패널의 {@link Panel#range range}내에 속해있는지를 반환합니다.
-   * @param {number} pos A position to check<ko>확인하고자 하는 좌표</ko>
-   * @param {boolean} [includeMargin=false] Include {@link Panel#margin margin} to the range<ko>패널 영역에 {@link Panel#margin margin}값을 포함시킵니다</ko>
-   * @return {boolean} A Boolean value indicating whether the given position is included in the panel range<ko>해당 좌표가 패널 영역 내에 속해있는지 여부</ko>
+   * Check whether the given position is inside of this panel's {@link Panel.range | range}
+   * @param pos - A position to check
+   * @param includeMargin - Include {@link Panel.margin | margin} to the range
+   * @returns A Boolean value indicating whether the given position is included in the panel range
    */
   public includePosition(pos: number, includeMargin: boolean = false): boolean {
     return this.includeRange(pos, pos, includeMargin);
@@ -423,11 +420,10 @@ class Panel {
 
   /**
    * Check whether the given range is fully included in this panel's area (inclusive)
-   * @ko 주어진 범위가 이 패널 내부에 완전히 포함되는지를 반환합니다
-   * @param {number} min Minimum value of the range to check<ko>확인하고자 하는 최소 범위</ko>
-   * @param {number} max Maximum value of the range to check<ko>확인하고자 하는 최대 범위</ko>
-   * @param {boolean} [includeMargin=false] Include {@link Panel#margin margin} to the range<ko>패널 영역에 {@link Panel#margin margin}값을 포함시킵니다</ko>
-   * @returns {boolean} A Boolean value indicating whether the given range is fully included in the panel range<ko>해당 범위가 패널 영역 내에 완전히 속해있는지 여부</ko>
+   * @param min - Minimum value of the range to check
+   * @param max - Maximum value of the range to check
+   * @param includeMargin - Include {@link Panel.margin | margin} to the range
+   * @returns A Boolean value indicating whether the given range is fully included in the panel range
    */
   public includeRange(min: number, max: number, includeMargin: boolean = false): boolean {
     const margin = this._margin;
@@ -443,10 +439,9 @@ class Panel {
 
   /**
    * Check whether the panel is visble in the given range (exclusive)
-   * @ko 주어진 범위 내에서 이 패널의 일부가 보여지는지를 반환합니다
-   * @param {number} min Minimum value of the range to check<ko>확인하고자 하는 최소 범위</ko>
-   * @param {number} max Maximum value of the range to check<ko>확인하고자 하는 최대 범위</ko>
-   * @returns {boolean} A Boolean value indicating whether the panel is visible<ko>해당 범위 내에서 패널을 볼 수 있는지 여부</ko>
+   * @param min - Minimum value of the range to check
+   * @param max - Maximum value of the range to check
+   * @returns A Boolean value indicating whether the panel is visible
    */
   public isVisibleOnRange(min: number, max: number): boolean {
     const panelRange = this.range;
@@ -456,20 +451,23 @@ class Panel {
 
   /**
    * Move {@link Camera} to this panel
-   * @ko {@link Camera}를 이 패널로 이동합니다
-   * @param {number} [duration] Duration of the animation (unit: ms)<ko>애니메이션 진행 시간 (단위: ms)</ko>
-   * @returns {Promise<void>} A Promise which will be resolved after reaching the panel<ko>패널 도달시에 resolve되는 Promise</ko>
-   */
-  public focus(duration?: number) {
+   * @remarks
+   * This is equivalent to calling `Flicking.moveTo(panel.index, duration)`.
+   * @param duration - Duration of the animation (unit: ms). Defaults to {@link FlickingOptions.duration}
+   * @fires {@link MovementEvents}
+   * @throws {@link MovementErrors}
+   * @returns A Promise which will be resolved after reaching the panel
+   */
+  public focus(duration?: number): Promise<void> {
     return this._flicking.moveTo(this._index, duration);
   }
 
   /**
-   * Get previous(`index - 1`) panel. When the previous panel does not exist, this will return `null` instead
-   * If the {@link Flicking#circularEnabled circular} is enabled, this will return the last panel if called from the first panel
-   * @ko 이전(`index - 1`) 패널을 반환합니다. 이전 패널이 없을 경우 `null`을 반환합니다
-   * {@link Flicking#circularEnabled circular} 모드가 활성화되었을 때 첫번째 패널에서 이 메소드를 호출할 경우 마지막 패널을 반환합니다
-   * @returns {Panel | null} The previous panel<ko>이전 패널</ko>
+   * Get previous(`index - 1`) panel.
+   * @remarks
+   * When the previous panel does not exist, this will return `null` instead
+   * If the {@link Flicking.circularEnabled | circular} is enabled, this will return the last panel if called from the first panel
+   * @returns The previous panel
    */
   public prev(): Panel | null {
     const index = this._index;
@@ -485,11 +483,11 @@ class Panel {
   }
 
   /**
-   * Get next(`index + 1`) panel. When the next panel does not exist, this will return `null` instead
-   * If the {@link Flicking#circularEnabled circular} is enabled, this will return the first panel if called from the last panel
-   * @ko 다음(`index + 1`) 패널을 반환합니다. 다음 패널이 없을 경우 `null`을 반환합니다
-   * {@link Flicking#circularEnabled circular} 모드가 활성화되었을 때 마지막 패널에서 이 메소드를 호출할 경우 첫번째 패널을 반환합니다
-   * @returns {Panel | null} The previous panel<ko>다음 패널</ko>
+   * Get next(`index + 1`) panel.
+   * @remarks
+   * When the next panel does not exist, this will return `null` instead
+   * If the {@link Flicking.circularEnabled | circular} is enabled, this will return the first panel if called from the last panel
+   * @returns The next panel
    */
   public next(): Panel | null {
     const index = this._index;
@@ -505,12 +503,9 @@ class Panel {
   }
 
   /**
-   * Increase panel's index by the given value
-   * @ko 패널의 인덱스를 주어진 값만큼 증가시킵니다
    * @internal
-   * @chainable
-   * @param val An integer greater than or equal to 0<ko>0보다 같거나 큰 정수</ko>
-   * @returns {this}
+   * @privateRemarks
+   * Increases the panel's index by the given value. Called when panels are inserted before this panel.
    */
   public increaseIndex(val: number): this {
     this._index += Math.max(val, 0);
@@ -518,12 +513,9 @@ class Panel {
   }
 
   /**
-   * Decrease panel's index by the given value
-   * @ko 패널의 인덱스를 주어진 값만큼 감소시킵니다
    * @internal
-   * @chainable
-   * @param val An integer greater than or equal to 0<ko>0보다 같거나 큰 정수</ko>
-   * @returns {this}
+   * @privateRemarks
+   * Decreases the panel's index by the given value. Called when panels are removed before this panel.
    */
   public decreaseIndex(val: number): this {
     this._index -= Math.max(val, 0);
@@ -532,20 +524,21 @@ class Panel {
 
   /**
    * @internal
+   * @privateRemarks
+   * Recalculates the panel's position based on the previous panel's position and margins.
    */
   public updatePosition(): this {
     const prevPanel = this._flicking.renderer.panels[this._index - 1];
 
-    this._pos = prevPanel
-      ? prevPanel.range.max + prevPanel.margin.next + this._margin.prev
-      : this._margin.prev;
+    this._pos = prevPanel ? prevPanel.range.max + prevPanel.margin.next + this._margin.prev : this._margin.prev;
 
     return this;
   }
 
   /**
    * @internal
-   * @return {boolean} toggled
+   * @privateRemarks
+   * Toggles the panel's position for circular mode. Returns true if the panel was toggled.
    */
   public toggle(prevPos: number, newPos: number): boolean {
     const toggleDirection = this._toggleDirection;
@@ -570,6 +563,8 @@ class Panel {
 
   /**
    * @internal
+   * @privateRemarks
+   * Updates the toggle direction for circular mode based on the panel's visibility at the camera range edges.
    */
   public updateCircularToggleDirection(): this {
     const flicking = this._flicking;
@@ -610,10 +605,20 @@ class Panel {
     return this;
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Recalculates the align position based on the align option and panel size.
+   */
   private _updateAlignPos() {
     this._alignPos = parseAlign(this._align, this._size);
   }
 
+  /**
+   * @internal
+   * @privateRemarks
+   * Resets all internal state values to their defaults.
+   */
   private _resetInternalStates() {
     this._size = 0;
     this._pos = 0;