@egjs/flicking 4.3.1 → 4.4.0

package/src/const/error.ts

@@ -25,6 +25,7 @@
  * <ko>프레임워크(React, Angular, Vue ...)에서 사용 불가능한 메소드를 호출했을 경우</ko>
  * @property {number} NOT_INITIALIZED When the {@link Flicking#init} is not called before but is needed<ko>{@link Flicking#init}의 호출이 필요하나, 아직 호출되지 않았을 경우</ko>
  * @property {number} NO_ACTIVE When there're no active panel that flicking has selected. This may be due to the absence of any panels<ko>현재 Flicking이 선택한 패널이 없을 경우. 일반적으로 패널이 하나도 없는 경우에 발생할 수 있습니다</ko>
+ * @property {number} NOT_ALLOWED_IN_VIRTUAL When the non-allowed method is called while the virtual option is enabled<ko>virtual 옵션이 활성화된 상태에서 사용 불가능한 메소드가 호출되었을 경우</ko>
  */
 export const CODE = {
   WRONG_TYPE: 0,
@@ -40,14 +41,15 @@ export const CODE = {
   ANIMATION_ALREADY_PLAYING: 10,
   NOT_ALLOWED_IN_FRAMEWORK: 11,
   NOT_INITIALIZED: 12,
-  NO_ACTIVE: 13
+  NO_ACTIVE: 13,
+  NOT_ALLOWED_IN_VIRTUAL: 14
 } as const;
 
 export const MESSAGE = {
   WRONG_TYPE: (wrongVal: any, correctTypes: string[]) => `${wrongVal}(${typeof wrongVal}) is not a ${correctTypes.map(type => `"${type}"`).join(" or ")}.`,
   ELEMENT_NOT_FOUND: (selector: string) => `Element with selector "${selector}" not found.`,
   VAL_MUST_NOT_NULL: (val: any, name: string) => `${name} should be provided. Given: ${val}`,
-  NOT_ATTACHED_TO_FLICKING: (name: string) => `${name} is not attached to the Flicking instance. "init()" should be called first.`,
+  NOT_ATTACHED_TO_FLICKING: "This module is not attached to the Flicking instance. \"init()\" should be called first.",
   WRONG_OPTION: (optionName: string, val: any) => `Option "${optionName}" is not in correct format, given: ${val}`,
   INDEX_OUT_OF_RANGE: (val: number, min: number, max: number) => `Index "${val}" is out of range: should be between ${min} and ${max}.`,
   POSITION_NOT_REACHABLE: (position: number) => `Position "${position}" is not reachable.`,
@@ -57,5 +59,6 @@ export const MESSAGE = {
   ANIMATION_ALREADY_PLAYING: "Animation is already playing.",
   NOT_ALLOWED_IN_FRAMEWORK: "This behavior is not allowed in the frameworks like React, Vue, or Angular.",
   NOT_INITIALIZED: "Flicking is not initialized yet, call init() first.",
-  NO_ACTIVE: "There's no active panel that Flicking has selected. This may be due to the absence of any panels."
+  NO_ACTIVE: "There's no active panel that Flicking has selected. This may be due to the absence of any panels.",
+  NOT_ALLOWED_IN_VIRTUAL: "This behavior is not allowed when the virtual option is enabled"
 } as const;

package/src/const/external.ts

@@ -92,3 +92,9 @@ export const MOVE_TYPE = {
   FREE_SCROLL: "freeScroll",
   STRICT: "strict"
 } as const;
+
+export const CLASS = {
+  VERTICAL: "vertical",
+  HIDDEN: "flicking-hidden",
+  DEFAULT_VIRTUAL: "flicking-panel"
+};

package/src/control/AxesController.ts

@@ -211,7 +211,7 @@ class AxesController {
    * @return {this}
    */
   public update(controlParams: ControlParams): this {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const axes = this._axes!;
     const axis = axes.axis[AXES.POSITION_KEY];
@@ -231,7 +231,7 @@ class AxesController {
    * @return {this}
    */
   public addPreventClickHandler(): this {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const axes = this._axes!;
     const cameraEl = flicking.camera.element;
 
@@ -248,7 +248,7 @@ class AxesController {
    * @return {this}
    */
   public removePreventClickHandler(): this {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const axes = this._axes!;
     const cameraEl = flicking.camera.element;
 
@@ -282,17 +282,22 @@ class AxesController {
    */
   public animateTo(position: number, duration: number, axesEvent?: OnRelease): Promise<void> {
     const axes = this._axes;
+    const state = this._stateMachine.state;
 
     if (!axes) {
-      return Promise.reject(new FlickingError(ERROR.MESSAGE.NOT_ATTACHED_TO_FLICKING("Control"), ERROR.CODE.NOT_ATTACHED_TO_FLICKING));
+      return Promise.reject(new FlickingError(ERROR.MESSAGE.NOT_ATTACHED_TO_FLICKING, ERROR.CODE.NOT_ATTACHED_TO_FLICKING));
     }
 
     const startPos = axes.get([AXES.POSITION_KEY])[AXES.POSITION_KEY];
 
     if (startPos === position) {
-      const flicking = getFlickingAttached(this._flicking, "Control");
+      const flicking = getFlickingAttached(this._flicking);
 
       flicking.camera.lookAt(position);
+
+      if (state.targetPanel) {
+        flicking.control.setActive(state.targetPanel, flicking.control.activePanel, axesEvent?.isTrusted ?? false);
+      }
       return Promise.resolve();
     }
 
@@ -317,7 +322,7 @@ class AxesController {
     };
 
     if (duration === 0) {
-      const flicking = getFlickingAttached(this._flicking, "Control");
+      const flicking = getFlickingAttached(this._flicking);
       const camera = flicking.camera;
 
       animate();

package/src/control/Control.ts

@@ -172,7 +172,7 @@ abstract class Control {
    * @return {Promise<void>}
    */
   public updatePosition(_progressInPanel: number): void { // eslint-disable-line @typescript-eslint/no-unused-vars
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const activePanel = this._activePanel;
 
@@ -188,7 +188,7 @@ abstract class Control {
    * @return {this}
    */
   public updateInput(): this {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
 
     this._controller.update(camera.controlParams);
@@ -255,7 +255,7 @@ abstract class Control {
     direction?: ValueOf<typeof DIRECTION>;
     axesEvent?: OnRelease;
   }) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
 
     let position = panel.position;
@@ -299,7 +299,7 @@ abstract class Control {
    * @internal
    */
   public setActive(newActivePanel: Panel, prevActivePanel: Panel | null, isTrusted: boolean) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
 
     this._activePanel = newActivePanel;
 
@@ -322,7 +322,7 @@ abstract class Control {
   }
 
   protected _triggerIndexChangeEvent(panel: Panel, position: number, axesEvent?: OnRelease): void {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const triggeringEvent = panel !== this._activePanel ? EVENTS.WILL_CHANGE : EVENTS.WILL_RESTORE;
     const camera = flicking.camera;
     const activePanel = this._activePanel;
@@ -351,7 +351,7 @@ abstract class Control {
     newActivePanel: Panel;
     axesEvent?: OnRelease;
   }) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const animate = () => this._controller.animateTo(position, duration, axesEvent);
     const state = this._controller.state;
 

package/src/control/FreeControl.ts

@@ -58,7 +58,7 @@ class FreeControl extends Control {
    * @return {Promise<void>}
    */
   public updatePosition(progressInPanel: number): void {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const activePanel = this._activePanel;
 
@@ -107,7 +107,7 @@ class FreeControl extends Control {
    * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
    */
   public async moveToPosition(position: number, duration: number, axesEvent?: OnRelease) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
 
     const camera = flicking.camera;
     const targetPos = camera.clampToReachablePosition(position);

package/src/control/SnapControl.ts

@@ -85,7 +85,7 @@ class SnapControl extends Control {
    * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
    */
   public async moveToPosition(position: number, duration: number, axesEvent?: OnRelease) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const activeAnchor = camera.findActiveAnchor();
     const anchorAtCamera = camera.findNearestAnchor(camera.position);
@@ -128,7 +128,7 @@ class SnapControl extends Control {
   }
 
   private _findSnappedAnchor(position: number, anchorAtCamera: AnchorPoint): AnchorPoint {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const count = this._count;
 
@@ -191,7 +191,7 @@ class SnapControl extends Control {
   }
 
   private _findAdjacentAnchor(posDelta: number, anchorAtCamera: AnchorPoint): AnchorPoint {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const adjacentAnchor = (posDelta > 0 ? camera.getNextAnchor(anchorAtCamera) : camera.getPrevAnchor(anchorAtCamera)) ?? anchorAtCamera;
 

package/src/control/StrictControl.ts

@@ -66,7 +66,7 @@ class StrictControl extends Control {
    * @return {this}
    */
   public updateInput(): this {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const renderer = flicking.renderer;
     const controller = this._controller;
@@ -178,7 +178,7 @@ class StrictControl extends Control {
    * @return {Promise<void>} A Promise which will be resolved after reaching the target position<ko>해당 좌표 도달시에 resolve되는 Promise</ko>
    */
   public async moveToPosition(position: number, duration: number, axesEvent?: OnRelease) {
-    const flicking = getFlickingAttached(this._flicking, "Control");
+    const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
     const activePanel = this._activePanel;
     const axesRange = this._controller.range;

package/src/core/AutoResizer.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+import Flicking from "../Flicking";
+
+class AutoResizer {
+  private _flicking: Flicking;
+  private _enabled: boolean;
+  private _resizeObserver: ResizeObserver | null;
+
+  public get enabled() { return this._enabled; }
+
+  public constructor(flicking: Flicking) {
+    this._flicking = flicking;
+    this._enabled = false;
+    this._resizeObserver = null;
+  }
+
+  public enable(): this {
+    const flicking = this._flicking;
+    const viewport = flicking.viewport;
+
+    if (this._enabled) {
+      this.disable();
+    }
+
+    if (flicking.useResizeObserver && !!window.ResizeObserver) {
+      const viewportSizeNot0 = viewport.width !== 0 || viewport.height !== 0;
+
+      const resizeObserver = viewportSizeNot0
+        ? new ResizeObserver(this._skipFirstResize)
+        : new ResizeObserver(this._onResize);
+
+      resizeObserver.observe(flicking.viewport.element);
+
+      this._resizeObserver = resizeObserver;
+    } else {
+      window.addEventListener("resize", this._onResize);
+    }
+
+    this._enabled = true;
+
+    return this;
+  }
+
+  public disable(): this {
+    if (!this._enabled) return this;
+
+    const resizeObserver = this._resizeObserver;
+    if (resizeObserver) {
+      resizeObserver.disconnect();
+      this._resizeObserver = null;
+    } else {
+      window.removeEventListener("resize", this._onResize);
+    }
+
+    this._enabled = false;
+
+    return this;
+  }
+
+  private _onResize = () => {
+    void this._flicking.resize();
+  };
+
+  // eslint-disable-next-line @typescript-eslint/member-ordering
+  private _skipFirstResize = (() => {
+    let isFirstResize = true;
+
+    return (() => {
+      if (isFirstResize) {
+        isFirstResize = false;
+        return;
+      }
+      this._onResize();
+    });
+  })();
+}
+
+export default AutoResizer;

package/src/core/VirtualManager.ts

@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+import Flicking from "../Flicking";
+import { range } from "../utils";
+import { CLASS } from "../const/external";
+
+import VirtualPanel from "./panel/VirtualPanel";
+
+export interface VirtualOptions {
+  renderPanel: (panel: VirtualPanel, index: number) => string;
+  initialPanelCount: number;
+  cache?: boolean;
+  panelClass?: string;
+}
+
+/**
+ * A manager class to add / remove virtual panels
+ */
+class VirtualManager {
+  private _flicking: Flicking;
+
+  private _renderPanel: (panel: VirtualPanel, index: number) => string;
+  private _initialPanelCount: number;
+  private _cache: boolean;
+  private _panelClass: string;
+
+  private _elements: Array<{ nativeElement: HTMLElement; visible: boolean }>;
+
+  public get elements() { return this._elements; }
+
+  // Options
+  /**
+   * A rendering function for the panel element's innerHTML
+   * @ko 패널 엘리먼트의 innerHTML을 렌더링하는 함수
+   * @type {function}
+   * @param {VirtualPanel} panel Instance of the panel<ko>패널 인스턴스</ko>
+   * @param {number} index Index of the panel<ko>패널 인덱스</ko>
+   * @default "() => {}"
+   */
+  public get renderPanel() { return this._renderPanel; }
+  /**
+   * Initial panel count to render
+   * @ko 최초로 렌더링할 패널의 개수
+   * @readonly
+   * @type {number}
+   * @default -1
+   */
+  public get initialPanelCount() { return this._initialPanelCount; }
+  /**
+   * Whether to cache rendered panel's innerHTML
+   * @ko 렌더링된 패널의 innerHTML 정보를 캐시할지 여부
+   * @type {boolean}
+   * @default false
+   */
+  public get cache() { return this._cache; }
+  /**
+   * The class name that will be applied to rendered panel elements
+   * @ko 렌더링되는 패널 엘리먼트에 적용될 클래스 이름
+   * @type {string}
+   * @default "flicking-panel"
+   */
+  public get panelClass() { return this._panelClass; }
+
+  public set renderPanel(val: VirtualOptions["renderPanel"]) {
+    this._renderPanel = val;
+    this._flicking.renderer.panels.forEach((panel: VirtualPanel) => panel.uncacheRenderResult());
+  }
+
+  public set cache(val: NonNullable<VirtualOptions["cache"]>) { this._cache = val; }
+  public set panelClass(val: NonNullable<VirtualOptions["panelClass"]>) { this._panelClass = val; }
+
+  public constructor(flicking: Flicking, options: VirtualOptions | null) {
+    this._flicking = flicking;
+
+    this._renderPanel = options?.renderPanel ?? (() => "");
+    this._initialPanelCount = options?.initialPanelCount ?? -1;
+    this._cache = options?.cache ?? false;
+    this._panelClass = options?.panelClass ?? CLASS.DEFAULT_VIRTUAL;
+
+    this._elements = [];
+  }
+
+  public init() {
+    const flicking = this._flicking;
+
+    if (!flicking.virtualEnabled) return;
+
+    if (!flicking.renderExternal) {
+      this._initVirtualElements();
+    }
+
+    const virtualElements = flicking.camera.children;
+    this._elements = virtualElements.map(el => ({ nativeElement: el, visible: true }));
+  }
+
+  public show(index: number) {
+    const el = this._elements[index];
+    const nativeEl = el.nativeElement;
+
+    el.visible = true;
+
+    if (nativeEl.style.display) {
+      nativeEl.style.display = "";
+    }
+  }
+
+  public hide(index: number) {
+    const el = this._elements[index];
+    const nativeEl = el.nativeElement;
+
+    el.visible = false;
+    nativeEl.style.display = "none";
+  }
+
+  /**
+   * Add new virtual panels at the end of the list
+   * @ko 새로운 가상 패널들을 리스트의 끝에 추가합니다
+   * @param {number} count The number of panels to add<ko>추가할 패널의 개수</ko>
+   * @returns {Array<VirtualPanel>} The new panels added<ko>새롭게 추가된 패널들</ko>
+   */
+  public append(count: number = 1): VirtualPanel[] {
+    const flicking = this._flicking;
+
+    return this.insert(flicking.panels.length, count);
+  }
+
+  /**
+   * Add new virtual panels at the start of the list
+   * @ko 새로운 가상 패널들을 리스트의 시작에 추가합니다
+   * @param {number} count The number of panels to add<ko>추가할 패널의 개수</ko>
+   * @returns {Array<VirtualPanel>} The new panels added<ko>새롭게 추가된 패널들</ko>
+   */
+  public prepend(count: number = 1): VirtualPanel[] {
+    return this.insert(0, count);
+  }
+
+  /**
+   * Add new virtual panels at the given index
+   * @ko 새로운 가상 패널들을 주어진 인덱스에 추가합니다
+   * @param {number} count The number of panels to add<ko>추가할 패널의 개수</ko>
+   * @returns {Array<VirtualPanel>} The new panels added<ko>새롭게 추가된 패널들</ko>
+   */
+  public insert(index: number, count: number = 1): VirtualPanel[] {
+    if (count <= 0) return [];
+
+    const flicking = this._flicking;
+
+    return flicking.renderer.batchInsert({ index, elements: range(count), hasDOMInElements: false }) as VirtualPanel[];
+  }
+
+  /**
+   * Remove panels at the given index
+   * @ko 주어진 인덱스에서 패널들을 삭제합니다
+   * @param {number} count The number of panels to remove<ko>삭제할 패널의 개수</ko>
+   * @returns {Array<VirtualPanel>} The panels removed<ko>삭제된 패널들</ko>
+   */
+  public remove(index: number, count: number): VirtualPanel[] {
+    if (count <= 0) return [];
+
+    const flicking = this._flicking;
+
+    return flicking.renderer.batchRemove({ index, deleteCount: count, hasDOMInElements: false }) as VirtualPanel[];
+  }
+
+  private _initVirtualElements() {
+    const flicking = this._flicking;
+    const cameraElement = flicking.camera.element;
+    const panelsPerView = flicking.panelsPerView;
+    const fragment = document.createDocumentFragment();
+
+    const newElements = range(panelsPerView + 1).map(idx => {
+      const panelEl = document.createElement("div");
+      panelEl.className = this._panelClass;
+      panelEl.dataset.elementIndex = idx.toString();
+      return panelEl;
+    });
+
+    newElements.forEach(el => {
+      fragment.appendChild(el);
+    });
+
+    cameraElement.appendChild(fragment);
+  }
+}
+
+export default VirtualManager;

package/src/core/index.ts

@@ -5,11 +5,13 @@
 import Viewport from "./Viewport";
 import FlickingError from "./FlickingError";
 import AnchorPoint from "./AnchorPoint";
+import VirtualManager from "./VirtualManager";
 
 export {
   Viewport,
   FlickingError,
-  AnchorPoint
+  AnchorPoint,
+  VirtualManager
 };
 
 export * from "./panel";

package/src/core/panel/ExternalPanel.ts

@@ -3,29 +3,37 @@
  * egjs projects are licensed under the MIT license
  */
 import Panel, { PanelOptions } from "./Panel";
+import ExternalElementProvider from "./provider/ExternalElementProvider";
 
-export interface ExternalPanelOptions<T> extends PanelOptions {
-  externalComponent: T;
+export interface ExternalPanelOptions extends PanelOptions {
+  elementProvider: ExternalElementProvider;
 }
 
 /**
- * An slide data component that holds information of a single HTMLElement
+ * A slide data component that holds information of a single HTMLElement
  * @ko 슬라이드 데이터 컴포넌트로, 단일 HTMLElement의 정보를 갖고 있습니다
  */
-abstract class ExternalPanel<T = any> extends Panel {
-  protected _externalComponent: T;
-
-  /**
-   * @param {object} options An options object<ko>옵션 오브젝트</ko>
-   * @param {HTMLElement} [options.el] A `HTMLElement` panel's referencing<ko>패널이 참조하는 `HTMLElement`</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>
-   */
-  public constructor(options: ExternalPanelOptions<T>) {
+class ExternalPanel extends Panel {
+  protected _elProvider: ExternalElementProvider;
+
+  public get rendered() { return this._elProvider.rendered; }
+
+  public constructor(options: ExternalPanelOptions) {
     super(options);
 
-    this._externalComponent = options.externalComponent;
+    this._elProvider = options.elementProvider;
+  }
+
+  public markForShow() {
+    this._elProvider.show(this._flicking);
+
+    return super.markForShow();
+  }
+
+  public markForHide() {
+    this._elProvider.hide(this._flicking);
+
+    return super.markForHide();
   }
 }