@egjs/flicking 4.2.4 → 4.4.0

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();
   }
 }
 

package/src/core/panel/Panel.ts

@@ -3,26 +3,36 @@
  * egjs projects are licensed under the MIT license
  */
 import Flicking from "../../Flicking";
-import { getProgress, getStyle, isString, parseAlign } from "../../utils";
+import { 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 {
   index: number;
   align: LiteralUnion<ValueOf<typeof ALIGN>> | number;
   flicking: Flicking;
+  elementProvider: ElementProvider;
 }
 
-abstract class Panel {
+/**
+ * A slide data component that holds information of a single HTMLElement
+ * @ko 슬라이드 데이터 컴포넌트로, 단일 HTMLElement의 정보를 갖고 있습니다
+ */
+class Panel {
   // Internal States
   protected _flicking: Flicking;
+  protected _elProvider: ElementProvider;
   protected _index: number;
   protected _pos: number;
   protected _size: number;
   protected _height: number;
   protected _margin: { prev: number; next: number };
   protected _alignPos: number; // Actual align pos
+  protected _rendered: boolean;
   protected _removed: boolean;
+  protected _loading: boolean;
   protected _toggleDirection: ValueOf<typeof DIRECTION>;
   protected _toggled: boolean;
   protected _togglePosition: number;
@@ -37,7 +47,12 @@ abstract class Panel {
    * @type {HTMLElement}
    * @readonly
    */
-  abstract get element(): HTMLElement;
+  public get element() { return this._elProvider.element; }
+  /**
+   * @internal
+   * @readonly
+   */
+  public get elementProvider() { return this._elProvider; }
   /**
    * Index of the panel
    * @ko 패널의 인덱스
@@ -108,7 +123,14 @@ abstract class Panel {
    * @type {boolean}
    * @readonly
    */
-  public abstract get rendered();
+  public get rendered() { 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; }
   /**
    * Panel element's range of the bounding box
    * @ko 패널 엘리먼트의 Bounding box 범위
@@ -221,6 +243,8 @@ abstract class Panel {
     return visibleSize / size;
   }
 
+  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
@@ -229,7 +253,7 @@ abstract class Panel {
    */
   public get align() { return this._align; }
 
-  // Options Getter
+  // Options Setter
   public set align(val: PanelOptions["align"]) { this._align = val; }
 
   /**
@@ -237,18 +261,23 @@ abstract class Panel {
    * @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>
    */
   public constructor({
     index,
     align,
-    flicking
+    flicking,
+    elementProvider
   }: PanelOptions) {
     this._index = index;
     this._flicking = flicking;
+    this._elProvider = elementProvider;
 
     this._align = align;
 
     this._removed = false;
+    this._rendered = true;
+    this._loading = false;
     this._resetInternalStates();
   }
 
@@ -256,13 +285,19 @@ abstract class Panel {
    * Mark panel element to be appended on the camera element
    * @internal
    */
-  public abstract markForShow();
+  public markForShow() {
+    this._rendered = true;
+    this._elProvider.show(this._flicking);
+  }
 
   /**
    * Mark panel element to be removed from the camera element
    * @internal
    */
-  public abstract markForHide();
+  public markForHide() {
+    this._rendered = false;
+    this._elProvider.hide(this._flicking);
+  }
 
   /**
    * Update size of the panel
@@ -277,16 +312,16 @@ abstract class Panel {
     margin: { prev: number; next: number };
   }): this {
     const el = this.element;
-    const elStyle = getStyle(el);
     const flicking = this._flicking;
     const horizontal = flicking.horizontal;
-    const prevPanel = flicking.renderer.panels[this._index - 1];
 
     if (cached) {
       this._size = cached.size;
       this._margin = { ...cached.margin };
       this._height = cached.height;
     } else {
+      const elStyle = getStyle(el);
+
       this._size = horizontal ? el.offsetWidth : el.offsetHeight;
       this._margin = horizontal
         ? {
@@ -299,10 +334,7 @@ abstract class Panel {
       this._height = horizontal ? el.offsetHeight : this._size;
     }
 
-    this._pos = prevPanel
-      ? prevPanel.range.max + prevPanel.margin.next + this._margin.prev
-      : this._margin.prev;
-
+    this.updatePosition();
     this._updateAlignPos();
 
     return this;
@@ -317,29 +349,11 @@ abstract class Panel {
    * @chainable
    * @return {this}
    */
-  public setSize({
-    width,
-    height
-  }: Partial<{
+  public setSize(size: Partial<{
     width: number | string;
     height: number | string;
   }>): this {
-    const el = this.element;
-
-    if (width != null) {
-      if (isString(width)) {
-        el.style.width = width;
-      } else {
-        el.style.width = `${width}px`;
-      }
-    }
-    if (height != null) {
-      if (isString(height)) {
-        el.style.height = height;
-      } else {
-        el.style.height = `${height}px`;
-      }
-    }
+    setSize(this.element, size);
 
     return this;
   }
@@ -376,7 +390,7 @@ abstract class Panel {
   }
 
   /**
-   * Check whether the given range is fully included in this panel's area
+   * 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>
@@ -395,6 +409,19 @@ abstract class Panel {
     return max >= panelRange.min && min <= panelRange.max;
   }
 
+  /**
+   * 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>
+   */
+  public isVisibleOnRange(min: number, max: number): boolean {
+    const panelRange = this.range;
+
+    return max > panelRange.min && min < panelRange.max;
+  }
+
   /**
    * Move {@link Camera} to this panel
    * @ko {@link Camera}를 이 패널로 이동합니다
@@ -472,28 +499,15 @@ abstract class Panel {
   }
 
   /**
-   * Increase panel's position by the given value
-   * @ko 패널의 위치를 주어진 값만큼 증가시킵니다
    * @internal
-   * @chainable
-   * @param val An integer greater than or equal to 0<ko>0보다 같거나 큰 정수</ko>
-   * @returns {this}
    */
-  public increasePosition(val: number): this {
-    this._moveBy(Math.max(val, 0));
-    return this;
-  }
+  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;
 
-  /**
-   * Decrease panel's position by the given value
-   * @ko 패널의위치를 주어진 값만큼 감소시킵니다
-   * @internal
-   * @chainable
-   * @param val An integer greater than or equal to 0<ko>0보다 같거나 큰 정수</ko>
-   * @returns {this}
-   */
-  public decreasePosition(val: number): this {
-    this._moveBy(-Math.max(val, 0));
     return this;
   }
 
@@ -563,12 +577,6 @@ abstract class Panel {
     return this;
   }
 
-  private _moveBy(val: number): this {
-    this._pos += val;
-
-    return this;
-  }
-
   private _updateAlignPos() {
     this._alignPos = parseAlign(this._align, this._size);
   }

package/src/core/panel/VirtualPanel.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+import { DIRECTION } from "../../const/external";
+import { circulateIndex } from "../../utils";
+
+import Panel, { PanelOptions } from "./Panel";
+import VirtualElementProvider from "./provider/VirtualElementProvider";
+
+interface VirtualPanelOptions extends PanelOptions {
+  elementProvider: VirtualElementProvider;
+}
+
+/**
+ * An slide data component that holds information of a single HTMLElement
+ * @ko 슬라이드 데이터 컴포넌트로, 단일 HTMLElement의 정보를 갖고 있습니다
+ */
+class VirtualPanel extends Panel {
+  protected _elProvider: VirtualElementProvider;
+  protected _cachedInnerHTML: string | null;
+
+  /**
+   * `HTMLElement` that panel's referencing
+   * @ko 패널이 참조하고 있는 `HTMLElement`
+   * @type {HTMLElement}
+   * @readonly
+   */
+  public get element() { return this._elProvider.element; }
+
+  /**
+   * Cached innerHTML by the previous render function
+   * @ko 이전 렌더링에서 캐시된 innerHTML 정보
+   * @type {string|null}
+   * @readonly
+   */
+  public get cachedInnerHTML() { return this._cachedInnerHTML; }
+
+  /**
+   * An number for indexing which element it will be rendered on
+   * @ko 몇 번째 엘리먼트에 렌더링될 것인지를 나타내는 숫자
+   * @type {number}
+   * @readonly
+   */
+  public get elementIndex() {
+    const flicking = this._flicking;
+    const virtualElCount = flicking.panelsPerView + 1;
+    const panelCount = flicking.panelCount;
+    let index = this._index;
+
+    if (this._toggled) {
+      // To prevent element duplication
+      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>
+   */
+  public constructor(options: VirtualPanelOptions) {
+    super(options);
+
+    options.elementProvider.init(this);
+    this._elProvider = options.elementProvider;
+    this._cachedInnerHTML = null;
+  }
+
+  public cacheRenderResult(result: string) {
+    this._cachedInnerHTML = result;
+  }
+
+  public uncacheRenderResult() {
+    this._cachedInnerHTML = null;
+  }
+
+  public render() {
+    const flicking = this._flicking;
+    const { renderPanel, cache } = flicking.virtual;
+
+    const element = this._elProvider.element;
+    const newInnerHTML = this._cachedInnerHTML || renderPanel(this, this._index);
+
+    if (newInnerHTML === element.innerHTML) return;
+
+    element.innerHTML = newInnerHTML;
+
+    if (cache) {
+      this.cacheRenderResult(newInnerHTML);
+    }
+  }
+
+  public increaseIndex(val: number) {
+    this.uncacheRenderResult();
+    return super.increaseIndex(val);
+  }
+
+  public decreaseIndex(val: number) {
+    this.uncacheRenderResult();
+    return super.decreaseIndex(val);
+  }
+}
+
+export default VirtualPanel;

package/src/core/panel/index.ts

@@ -3,17 +3,18 @@
  * egjs projects are licensed under the MIT license
  */
 import Panel, { PanelOptions } from "./Panel";
-import ElementPanel, { ElementPanelOptions } from "./ElementPanel";
 import ExternalPanel, { ExternalPanelOptions } from "./ExternalPanel";
+import VirtualPanel from "./VirtualPanel";
+
+export * from "./provider";
 
 export {
   Panel,
-  ElementPanel,
-  ExternalPanel
+  ExternalPanel,
+  VirtualPanel
 };
 
 export type {
   PanelOptions,
-  ElementPanelOptions,
   ExternalPanelOptions
 };

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

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+import Flicking from "../../../Flicking";
+
+interface ElementProvider {
+  element: HTMLElement;
+  show(flicking: Flicking): void;
+  hide(flicking: Flicking): void;
+}
+
+export default ElementProvider;

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

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2015 NAVER Corp.
+ * egjs projects are licensed under the MIT license
+ */
+import Flicking from "../../../Flicking";
+
+import ElementProvider from "./ElementProvider";
+
+interface ExternalElementProvider extends ElementProvider {
+  rendered: boolean;
+  show(flicking: Flicking): any;
+  hide(flicking: Flicking): any;
+}
+
+export default ExternalElementProvider;