@egjs/flicking 4.15.0 → 4.16.0-beta.0

package/src/core/panel/VirtualPanel.ts

@@ -2,19 +2,22 @@
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
-import { DIRECTION } from "../../const/external";
+import { DIRECTION } from "../../constants/values";
 import { circulateIndex } from "../../utils";
 
 import Panel, { PanelOptions } from "./Panel";
 import VirtualElementProvider from "./provider/VirtualElementProvider";
 
-interface VirtualPanelOptions extends PanelOptions {
+/**
+ * Options for creating a {@link VirtualPanel}
+ */
+export interface VirtualPanelOptions extends PanelOptions {
+  /** A provider instance that returns the actual html element */
   elementProvider: VirtualElementProvider;
 }
 
 /**
- * An slide data component that holds information of a single HTMLElement
- * @ko 슬라이드 데이터 컴포넌트로, 단일 HTMLElement의 정보를 갖고 있습니다
+ * A slide data component that holds information of a single HTMLElement
  */
 class VirtualPanel extends Panel {
   protected _elProvider: VirtualElementProvider;
@@ -22,27 +25,25 @@ class VirtualPanel extends Panel {
 
   /**
    * `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;
+  }
 
   /**
    * Cached innerHTML by the previous render function
-   * @ko 이전 렌더링에서 캐시된 innerHTML 정보
-   * @type {string|null}
    * @readonly
    */
-  public get cachedInnerHTML() { return this._cachedInnerHTML; }
+  public get cachedInnerHTML(): string | null {
+    return this._cachedInnerHTML;
+  }
 
   /**
-   * An number for indexing which element it will be rendered on
-   * @ko 몇 번째 엘리먼트에 렌더링될 것인지를 나타내는 숫자
-   * @type {number}
+   * A number for indexing which element it will be rendered on
    * @readonly
    */
-  public get elementIndex() {
+  public get elementIndex(): number {
     const flicking = this._flicking;
     const virtualElCount = flicking.panelsPerView + 1;
     const panelCount = flicking.panelCount;
@@ -50,19 +51,14 @@ class VirtualPanel extends Panel {
 
     if (this._toggled) {
       // To prevent element duplication
-      index = this._toggleDirection === DIRECTION.NEXT
-        ? index + panelCount
-        : index - panelCount;
+      index = this._toggleDirection === DIRECTION.NEXT ? index + panelCount : index - panelCount;
     }
 
     return circulateIndex(index, virtualElCount);
   }
 
   /**
-   * @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 options - {@link VirtualPanelOptions}
    */
   public constructor(options: VirtualPanelOptions) {
     super(options);

package/src/core/panel/index.ts

@@ -2,16 +2,11 @@
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
-import Panel, { PanelOptions } from "./Panel";
-import VirtualPanel from "./VirtualPanel";
+import Panel, { PanelBoundingBoxRange, PanelMarginInfo, PanelOptions } from "./Panel";
+import VirtualPanel, { VirtualPanelOptions } from "./VirtualPanel";
 
 export * from "./provider";
 
-export {
-  Panel,
-  VirtualPanel
-};
+export { Panel, VirtualPanel };
 
-export type {
-  PanelOptions
-};
+export type { PanelOptions, PanelBoundingBoxRange, PanelMarginInfo, VirtualPanelOptions };

package/src/core/panel/provider/VanillaElementProvider.ts

@@ -13,8 +13,12 @@ class VanillaElementProvider implements ElementProvider {
   private _element: HTMLElement;
   private _rendered: boolean;
 
-  public get element() { return this._element; }
-  public get rendered() { return this._rendered; }
+  public get element() {
+    return this._element;
+  }
+  public get rendered() {
+    return this._rendered;
+  }
 
   public constructor(element: HTMLElement) {
     this._element = element;

package/src/core/panel/provider/VirtualElementProvider.ts

@@ -15,8 +15,12 @@ class VirtualElementProvider implements ElementProvider {
   private _flicking: Flicking;
   private _panel: VirtualPanel;
 
-  public get element() { return this._virtualElement.nativeElement; }
-  public get rendered() { return this._virtualElement.visible; }
+  public get element() {
+    return this._virtualElement.nativeElement;
+  }
+  public get rendered() {
+    return this._virtualElement.visible;
+  }
 
   private get _virtualElement() {
     const flicking = this._flicking;

package/src/core/panel/provider/index.ts

@@ -6,11 +6,6 @@ import ElementProvider from "./ElementProvider";
 import VanillaElementProvider from "./VanillaElementProvider";
 import VirtualElementProvider from "./VirtualElementProvider";
 
-export {
-  VanillaElementProvider,
-  VirtualElementProvider
-};
+export { VanillaElementProvider, VirtualElementProvider };
 
-export type {
-  ElementProvider
-};
+export type { ElementProvider };

package/src/{core → error}/FlickingError.ts

@@ -7,10 +7,8 @@ import { setPrototypeOf } from "../utils";
 
 /**
  * Special type of known error that {@link Flicking} throws.
- * @ko Flicking 내부에서 알려진 오류 발생시 throw되는 에러
- * @property {number} code Error code<ko>에러 코드</ko>
- * @property {string} message Error message<ko>에러 메시지</ko>
- * @see {@link ERROR_CODE ERROR_CODE}
+ * @remarks
+ * see {@link FlickingErrors} for possible error codes and explantaion
  * @example
  * ```ts
  * import Flicking, { FlickingError, ERROR_CODES } from "@egjs/flicking";
@@ -18,7 +16,7 @@ import { setPrototypeOf } from "../utils";
  *   const flicking = new Flicking(".flicking-viewport")
  * } catch (e) {
  *   if (e instanceof FlickingError && e.code === ERROR_CODES.ELEMENT_NOT_FOUND) {
- *     console.error("Element not found")
+ *     console.error(e.message)
  *   }
  * }
  * ```
@@ -27,8 +25,8 @@ class FlickingError extends Error {
   public code: number;
 
   /**
-   * @param message Error message<ko>에러 메시지</ko>
-   * @param code Error code<ko>에러 코드</ko>
+   * @param message - Error message
+   * @param code - Error code
    */
   public constructor(message: string, code: number) {
     super(message);

package/src/error/codes.ts

@@ -0,0 +1,164 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+/* eslint-disable @typescript-eslint/restrict-template-expressions */
+
+import type { FlickingErrors } from "./types";
+
+type ErrorKey = keyof FlickingErrors;
+
+/**
+ * Internal error catalog containing all error information.
+ * @remarks
+ * This is the single source of truth for all error codes and messages.
+ * Use {@link ERROR_CODE} and {@link MESSAGE} exports for public access.
+ * @privateRemarks
+ * ## How to add a new error code
+ *
+ * 1. **Add to this `errors` object:**
+ *    ```typescript
+ *    NEW_ERROR_NAME: {
+ *      code: 15,  // next available number
+ *      message: "Error message" // or function for parameterized messages
+ *    }
+ *    ```
+ *
+ * 2. **Document in FlickingErrors** (types.ts):
+ *    - Add property with same name and type signature
+ *    - Write comprehensive TSDoc with @remarks, @example, @see tags
+ *    - Include: description, common causes, solutions, wrong/correct examples
+ *
+ * 3. **Verify:**
+ *    - `pnpm build` - check TypeScript compilation
+ *    - `pnpm api-docs:docusaurus` - generate documentation
+ *    - Check packages/docs/docs/api/interfaces/FlickingErrors.mdx
+ *
+ * Note: `CODE` and `MESSAGE` exports are auto-generated via reduce, no manual updates needed.
+ * @internal
+ */
+const errors: FlickingErrors = {
+  WRONG_TYPE: {
+    code: 0,
+    message: (wrongVal, correctTypes) =>
+      `${wrongVal}(${typeof wrongVal}) is not a ${correctTypes.map(type => `"${type}"`).join(" or ")}.`
+  },
+  ELEMENT_NOT_FOUND: {
+    code: 1,
+    message: selector => `Element with selector "${selector}" not found.`
+  },
+  VAL_MUST_NOT_NULL: {
+    code: 2,
+    message: (val, name) => `${name} should be provided. Given: ${val}`
+  },
+  NOT_ATTACHED_TO_FLICKING: {
+    code: 3,
+    message: 'This module is not attached to the Flicking instance. "init()" should be called first.'
+  },
+  WRONG_OPTION: {
+    code: 4,
+    message: (optionName, val) => `Option "${optionName}" is not in correct format, given: ${val}`
+  },
+  INDEX_OUT_OF_RANGE: {
+    code: 5,
+    message: (val, min, max) => `Index "${val}" is out of range: should be between ${min} and ${max}.`
+  },
+  POSITION_NOT_REACHABLE: {
+    code: 6,
+    message: position => `Position "${position}" is not reachable.`
+  },
+  TRANSFORM_NOT_SUPPORTED: {
+    code: 7,
+    message: "Browser does not support CSS transform."
+  },
+  STOP_CALLED_BY_USER: {
+    code: 8,
+    message: "Event stop() is called by user."
+  },
+  ANIMATION_INTERRUPTED: {
+    code: 9,
+    message: "Animation is interrupted by user input."
+  },
+  ANIMATION_ALREADY_PLAYING: {
+    code: 10,
+    message: "Animation is already playing."
+  },
+  NOT_ALLOWED_IN_FRAMEWORK: {
+    code: 11,
+    message: "This behavior is not allowed in the frameworks like React, Vue, or Angular."
+  },
+  NOT_INITIALIZED: {
+    code: 12,
+    message: "Flicking is not initialized yet, call init() first."
+  },
+  NO_ACTIVE: {
+    code: 13,
+    message: "There's no active panel that Flicking has selected. This may be due to the absence of any panels."
+  },
+  NOT_ALLOWED_IN_VIRTUAL: {
+    code: 14,
+    message: "This behavior is not allowed when the virtual option is enabled"
+  }
+};
+
+/**
+ * Error codes of {@link FlickingError}.
+ * @remarks
+ * Each error code represents a specific error condition that can occur during Flicking's lifecycle.
+ * Use these codes to identify and handle errors programmatically.
+ *
+ * For detailed documentation of each error code, see {@link FlickingErrors}.
+ * @example
+ * ```typescript
+ * import {FlickingError, ERROR_CODE} from "@egjs/flicking";
+ *
+ * try {
+ *   flicking.moveTo(999);
+ * } catch (err) {
+ *   if (err instancof FlickingError && err.code === ERROR_CODE.INDEX_OUT_OF_RANGE) {
+ *     console.log(err.message);
+ *   }
+ * }
+ * ```
+ * @public
+ * @see {@link FlickingErrors} for detailed documentation of each error code
+ */
+export const CODE = (Object.keys(errors) as ErrorKey[]).reduce(
+  (acc, key) => {
+    acc[key] = errors[key].code;
+    return acc;
+  },
+  {} as Record<ErrorKey, number>
+) as { [K in ErrorKey]: FlickingErrors[K]["code"] };
+
+/**
+ * Error message generators for {@link FlickingError}.
+ * @remarks
+ * These functions generate human-readable error messages for each error code.
+ * Used internally by Flicking to create {@link FlickingError} instances with
+ * contextual information.
+ * @internal
+ */
+export const MESSAGE = (Object.keys(errors) as ErrorKey[]).reduce(
+  (acc, key) => {
+    acc[key] = errors[key].message;
+    return acc;
+  },
+  {} as Record<string, any>
+) as { [K in ErrorKey]: FlickingErrors[K]["message"] };
+
+/**
+ * Alias for {@link CODE}.
+ * @remarks
+ * Exported as `ERROR_CODE` for semantic clarity when importing.
+ * @example
+ * ```typescript
+ * import { ERROR_CODE } from "@egjs/flicking";
+ *
+ * if (err.code === ERROR_CODE.INDEX_OUT_OF_RANGE) {
+ *   // Handle index error
+ * }
+ * ```
+ * @public
+ */
+export { CODE as ERROR_CODE };

package/src/error/groups.ts

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+
+import { ERROR_CODE } from "./codes";
+
+/**
+ * Error codes that may be thrown during panel movement operations.
+ * @remarks
+ * These errors can occur when using navigation methods like {@link Flicking.prev},
+ * {@link Flicking.next}, or {@link Flicking.moveTo}.
+ *
+ * Common scenarios:
+ *
+ * - `NOT_INITIALIZED`: Attempting to navigate before Flicking is ready
+ *
+ * - `INDEX_OUT_OF_RANGE`: Target panel index doesn't exist
+ *
+ * - `POSITION_NOT_REACHABLE`: Target camera position is invalid
+ *
+ * - `ANIMATION_INTERRUPTED`: User interaction during animation
+ *
+ * - `ANIMATION_ALREADY_PLAYING`: Starting new animation while one is in progress
+ *
+ * - `STOP_CALLED_BY_USER`: User prevented navigation via `event.stop()`
+ *
+ * - `NO_ACTIVE`: No panels available to navigate
+ */
+export type MovementErrors =
+  | typeof ERROR_CODE.NOT_INITIALIZED
+  | typeof ERROR_CODE.INDEX_OUT_OF_RANGE
+  | typeof ERROR_CODE.POSITION_NOT_REACHABLE
+  | typeof ERROR_CODE.ANIMATION_INTERRUPTED
+  | typeof ERROR_CODE.ANIMATION_ALREADY_PLAYING
+  | typeof ERROR_CODE.STOP_CALLED_BY_USER
+  | typeof ERROR_CODE.NO_ACTIVE;
+
+/**
+ * Error codes that may be thrown when manipulating the DOM.
+ * @remarks
+ * These errors can occur when using DOM manipulation methods like
+ * {@link Flicking.insert}, {@link Flicking.append}, {@link Flicking.prepend},
+ * {@link Flicking.replace}, or {@link Flicking.remove}.
+ *
+ * Common scenarios:
+ *
+ * - `NOT_ATTACHED_TO_FLICKING`: Component not properly initialized
+ *
+ * - `ELEMENT_NOT_FOUND`: Invalid CSS selector or element doesn't exist
+ *
+ * - `VAL_MUST_NOT_NULL`: Required parameter is null/undefined
+ *
+ * - `WRONG_TYPE`: Invalid parameter type
+ *
+ * - `INDEX_OUT_OF_RANGE`: Target index doesn't exist
+ *
+ * - `NOT_ALLOWED_IN_FRAMEWORK`: Using DOM methods in React/Vue/Angular
+ *
+ * - `NOT_ALLOWED_IN_VIRTUAL`: Using DOM methods with virtual mode enabled
+ * @public
+ */
+export type DOMManipulationErrors =
+  | typeof ERROR_CODE.NOT_ATTACHED_TO_FLICKING
+  | typeof ERROR_CODE.ELEMENT_NOT_FOUND
+  | typeof ERROR_CODE.VAL_MUST_NOT_NULL
+  | typeof ERROR_CODE.WRONG_TYPE
+  | typeof ERROR_CODE.INDEX_OUT_OF_RANGE
+  | typeof ERROR_CODE.NOT_ALLOWED_IN_FRAMEWORK
+  | typeof ERROR_CODE.NOT_ALLOWED_IN_VIRTUAL;
+
+/**
+ * Error codes that may be thrown during Flicking initialization.
+ * @remarks
+ * These errors can occur when creating a new Flicking instance or calling {@link Flicking.init}.
+ *
+ * Common scenarios:
+ *
+ * - `ELEMENT_NOT_FOUND`: Viewport element doesn't exist in DOM
+ *
+ * - `WRONG_OPTION`: Invalid configuration option value
+ *
+ * - `TRANSFORM_NOT_SUPPORTED`: Browser doesn't support CSS transforms (IE8 and below)
+ * @public
+ */
+export type InitializationErrors =
+  | typeof ERROR_CODE.ELEMENT_NOT_FOUND
+  | typeof ERROR_CODE.WRONG_OPTION
+  | typeof ERROR_CODE.TRANSFORM_NOT_SUPPORTED;
+
+/**
+ * Error codes that may be thrown during animation updates.
+ * @remarks
+ * These errors can occur when calling {@link Flicking.update} to manually update
+ * the animation state.
+ *
+ * Common scenarios:
+ *
+ * - `NOT_INITIALIZED`: Calling update before Flicking is ready
+ *
+ * - `ANIMATION_INTERRUPTED`: User interrupted the animation during update
+ * @public
+ */
+export type AnimationUpdateErrors = typeof ERROR_CODE.NOT_INITIALIZED | typeof ERROR_CODE.ANIMATION_INTERRUPTED;
+
+/**
+ * Error codes that may be thrown when restoring Flicking status.
+ * @remarks
+ * These errors can occur when using {@link Flicking.setStatus} to restore
+ * a previously saved status (from {@link Flicking.getStatus}).
+ *
+ * Common scenarios:
+ *
+ * - `NOT_INITIALIZED`: Attempting to restore before initialization
+ *
+ * - `INDEX_OUT_OF_RANGE`: Saved status references non-existent panel
+ *
+ * - `POSITION_NOT_REACHABLE`: Saved position is no longer valid
+ * @public
+ */
+export type StatusRestoreErrors =
+  | typeof ERROR_CODE.NOT_INITIALIZED
+  | typeof ERROR_CODE.INDEX_OUT_OF_RANGE
+  | typeof ERROR_CODE.POSITION_NOT_REACHABLE;

package/src/error/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+
+export { CODE, ERROR_CODE, MESSAGE } from "./codes";
+export { default as FlickingError } from "./FlickingError";
+export * from "./groups";
+export * from "./types";