@egjs/flicking 4.4.2 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@egjs/flicking",
-	"version": "4.4.2",
+	"version": "4.5.0",
 	"description": "Everyday 30 million people experience. It's reliable, flexible and extendable carousel.",
 	"main": "dist/flicking.js",
 	"module": "dist/flicking.esm.js",
@@ -22,7 +22,7 @@
 		"jsdoc:watch": "npm-watch jsdoc",
 		"docs:build": "jsdoc-to-mdx -c ./jsdoc-to-mdx.json",
 		"docs:version": "node ./config/docs-version-up",
-		"docs:release": "npm run docs:build && npm run docs:version && cd docs && npm run build && cd ..",
+		"docs:release": "npm run docs:build && npm run docs:version && npm run build --prefix docs",
 		"demo:prebuild-version": "cpx 'dist/**/*' docs/build/release/$npm_package_version/dist --clean",
 		"demo:prebuild-latest": "cpx 'dist/**/*' docs/build/release/latest/dist --clean",
 		"demo:deploy": "npm run docs:release && npm run build && npm run demo:prebuild-version && npm run demo:prebuild-latest && gh-pages -d docs/build/ --add --remote upstream",
@@ -79,6 +79,7 @@
 		"@rollup/plugin-replace": "^2.4.1",
 		"@types/fs-extra": "^9.0.11",
 		"@types/node": "^14.14.35",
+		"@types/resize-observer-browser": "^0.1.6",
 		"@typescript-eslint/eslint-plugin": "^4.18.0",
 		"@typescript-eslint/eslint-plugin-tslint": "^4.18.0",
 		"@typescript-eslint/parser": "^4.18.0",
@@ -121,7 +122,7 @@
 		"tslib": "^2.1.0",
 		"tslint": "^5.12.1",
 		"ttypescript": "^1.5.12",
-		"typescript": "^4.2.3",
+		"typescript": "^3.9.10",
 		"typescript-transform-paths": "^2.2.3"
 	},
 	"dependencies": {

package/src/Flicking.ts

@@ -11,9 +11,9 @@ import { Panel } from "./core/panel";
 import { VanillaElementProvider } from "./core/panel/provider";
 import VirtualManager, { VirtualOptions } from "./core/VirtualManager";
 import { Control, SnapControl, SnapControlOptions, FreeControl, StrictControl, FreeControlOptions, StrictControlOptions } from "./control";
-import { BoundCamera, Camera, CircularCamera, LinearCamera } from "./camera";
+import { Camera } from "./camera";
 import { Renderer, VanillaRenderer, ExternalRenderer, RendererOptions, NormalRenderingStrategy, VirtualRenderingStrategy } from "./renderer";
-import { EVENTS, ALIGN, MOVE_TYPE, DIRECTION } from "./const/external";
+import { EVENTS, ALIGN, MOVE_TYPE, DIRECTION, CIRCULAR_FALLBACK } from "./const/external";
 import * as ERROR from "./const/error";
 import { findIndex, getElement, includes, parseElement } from "./utils";
 import { HoldStartEvent, HoldEndEvent, MoveStartEvent, SelectEvent, MoveEvent, MoveEndEvent, WillChangeEvent, WillRestoreEvent, NeedPanelEvent, VisibleChangeEvent, ReachEdgeEvent, ReadyEvent, AfterResizeEvent, BeforeResizeEvent, ChangedEvent, RestoredEvent, PanelChangeEvent } from "./type/event";
@@ -52,6 +52,7 @@ export interface FlickingOptions {
   defaultIndex: number;
   horizontal: boolean;
   circular: boolean;
+  circularFallback: LiteralUnion<ValueOf<typeof CIRCULAR_FALLBACK>>;
   bound: boolean;
   adaptive: boolean;
   panelsPerView: number;
@@ -120,6 +121,7 @@ class Flicking extends Component<FlickingEvents> {
   private _defaultIndex: FlickingOptions["defaultIndex"];
   private _horizontal: FlickingOptions["horizontal"];
   private _circular: FlickingOptions["circular"];
+  private _circularFallback: FlickingOptions["circularFallback"];
   private _bound: FlickingOptions["bound"];
   private _adaptive: FlickingOptions["adaptive"];
   private _panelsPerView: FlickingOptions["panelsPerView"];
@@ -218,7 +220,7 @@ class Flicking extends Component<FlickingEvents> {
    * @default false
    * @readonly
    */
-  public get circularEnabled() { return this._camera.controlParams.circular; }
+  public get circularEnabled() { return this._camera.circularEnabled; }
   /**
    * Whether the `virtual` option is enabled.
    * The {@link Flicking#virtual virtual} option can't be enabled when  {@link Flicking#panelsPerView panelsPerView} is less or equal than zero.
@@ -348,6 +350,18 @@ class Flicking extends Component<FlickingEvents> {
    * @default false
    */
   public get circular() { return this._circular; }
+  /**
+   * Set panel control mode for the case when circular cannot be enabled.
+   * "linear" will set the view's range from the top of the first panel to the top of the last panel.
+   * "bound" will prevent the view from going out of the first/last panel, so it won't show empty spaces before/after the first/last panel.
+   * @ko 순환 모드 사용 불가능시 사용할 패널 조작 범위 설정 방식을 변경합니다.
+   * "linear" 사용시 시점이 첫번째 엘리먼트 위에서부터 마지막 엘리먼트 위까지 움직일 수 있도록 설정합니다.
+   * "bound" 사용시 시점이 첫번째 엘리먼트와 마지막 엘리먼트의 끝과 끝 사이에서 움직일 수 있도록 설정합니다.
+   * @see CIRCULAR_FALLBACK
+   * @type {string}
+   * @default "linear"
+   */
+  public get circularFallback() { return this._circularFallback; }
   /**
    * Prevent the view(camera element) from going out of the first/last panel, so it won't show empty spaces before/after the first/last panel
    * Only can be enabled when `circular=false`
@@ -718,6 +732,7 @@ class Flicking extends Component<FlickingEvents> {
     defaultIndex = 0,
     horizontal = true,
     circular = false,
+    circularFallback = CIRCULAR_FALLBACK.LINEAR,
     bound = false,
     adaptive = false,
     panelsPerView = -1,
@@ -755,6 +770,7 @@ class Flicking extends Component<FlickingEvents> {
     this._defaultIndex = defaultIndex;
     this._horizontal = horizontal;
     this._circular = circular;
+    this._circularFallback = circularFallback;
     this._bound = bound;
     this._adaptive = adaptive;
     this._panelsPerView = panelsPerView;
@@ -1358,19 +1374,14 @@ class Flicking extends Component<FlickingEvents> {
   }
 
   private _createCamera(): Camera {
-    const cameraOption = { align: this._align };
-
-    if (this._circular) {
-      if (this._bound) {
-        // eslint-disable-next-line no-console
-        console.warn("\"circular\" and \"bound\" option cannot be used together, ignoring bound.");
-      }
-      return new CircularCamera(cameraOption);
-    } else if (this._bound) {
-      return new BoundCamera(cameraOption);
-    } else {
-      return new LinearCamera(cameraOption);
+    if (this._circular && this._bound) {
+      // eslint-disable-next-line no-console
+      console.warn("\"circular\" and \"bound\" option cannot be used together, ignoring bound.");
     }
+
+    return new Camera({
+      align: this._align
+    });
   }
 
   private _createRenderer(): Renderer {

package/src/camera/Camera.ts

@@ -9,8 +9,10 @@ import FlickingError from "../core/FlickingError";
 import Panel from "../core/panel/Panel";
 import AnchorPoint from "../core/AnchorPoint";
 import * as ERROR from "../const/error";
-import { ALIGN, DIRECTION, EVENTS } from "../const/external";
-import { checkExistence, clamp, find, getFlickingAttached, getProgress, includes, parseAlign, toArray } from "../utils";
+import { ALIGN, CIRCULAR_FALLBACK, DIRECTION, EVENTS } from "../const/external";
+import { checkExistence, find, getFlickingAttached, getProgress, includes, parseAlign, toArray } from "../utils";
+
+import { CameraMode, BoundCameraMode, CircularCameraMode, LinearCameraMode } from "./mode";
 
 export interface CameraOptions {
   align: FlickingOptions["align"];
@@ -20,21 +22,24 @@ export interface CameraOptions {
  * A component that manages actual movement inside the viewport
  * @ko 뷰포트 내에서의 실제 움직임을 담당하는 컴포넌트
  */
-abstract class Camera {
+class Camera {
   // Options
-  protected _align: FlickingOptions["align"];
+  private _align: FlickingOptions["align"];
 
   // Internal states
-  protected _flicking: Flicking | null;
-  protected _el: HTMLElement;
-  protected _transform: string;
-  protected _position: number;
-  protected _alignPos: number;
-  protected _offset: number;
-  protected _range: { min: number; max: number };
-  protected _visiblePanels: Panel[];
-  protected _anchors: AnchorPoint[];
-  protected _needPanelTriggered: { prev: boolean; next: boolean };
+  private _flicking: Flicking | null;
+  private _mode: CameraMode;
+  private _el: HTMLElement;
+  private _transform: string;
+  private _position: number;
+  private _alignPos: number;
+  private _offset: number;
+  private _circularOffset: number;
+  private _circularEnabled: boolean;
+  private _range: { min: number; max: number };
+  private _visiblePanels: Panel[];
+  private _anchors: AnchorPoint[];
+  private _needPanelTriggered: { prev: boolean; next: boolean };
 
   // Internal states getter
   /**
@@ -72,7 +77,23 @@ abstract class Camera {
    * @default 0
    * @readonly
    */
-  public get offset() { return this._offset; }
+  public get offset() { 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
+   * @readonly
+   */
+  public get circularEnabled() { return this._circularEnabled; }
+  /**
+   * A current camera mode
+   * @type {CameraMode}
+   * @readonly
+   */
+  public get mode() { return this._mode; }
   /**
    * A range that Camera's {@link Camera#position position} can reach
    * @ko Camera의 {@link Camera#position position}이 도달 가능한 범위
@@ -118,7 +139,7 @@ abstract class Camera {
    * @type {ControlParams}
    * @readonly
    */
-  public get controlParams() { return { range: this._range, position: this._position, circular: false }; }
+  public get controlParams() { 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 현재 카메라가 도달 가능한 범위의 최소 혹은 최대점을 넘어섰는지를 나타냅니다
@@ -220,22 +241,6 @@ abstract class Camera {
     this._align = align;
   }
 
-  /**
-   * 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}
-   */
-  public abstract updateRange(): this;
-
   /**
    * Initialize Camera
    * @ko Camera를 초기화합니다
@@ -255,6 +260,8 @@ abstract class Camera {
     this._el = viewportEl.firstElementChild as HTMLElement;
     this._checkTranslateSupport();
 
+    this._updateMode();
+
     return this;
   }
 
@@ -279,13 +286,21 @@ abstract class Camera {
    * @return {this}
    */
   public lookAt(pos: number): void {
+    const flicking = getFlickingAttached(this._flicking);
     const prevPos = this._position;
 
     this._position = pos;
+    const toggled = this._togglePanels(prevPos, pos);
     this._refreshVisiblePanels();
     this._checkNeedPanel();
     this._checkReachEnd(prevPos, pos);
     this.applyTransform();
+
+    if (toggled) {
+      void flicking.renderer.render().then(() => {
+        this.updateOffset();
+      });
+    }
   }
 
   /**
@@ -297,7 +312,19 @@ abstract class Camera {
    * @return {AnchorPoint | null} The previous {@link AnchorPoint}<ko>이전 {@link AnchorPoint}</ko>
    */
   public getPrevAnchor(anchor: AnchorPoint): AnchorPoint | null {
-    return this._anchors[anchor.index - 1] || null;
+    if (!this._circularEnabled || anchor.index !== 0) {
+      return this._anchors[anchor.index - 1] || null;
+    } else {
+      const anchors = this._anchors;
+      const rangeDiff = this.rangeDiff;
+      const lastAnchor = anchors[anchors.length - 1];
+
+      return new AnchorPoint({
+        index: lastAnchor.index,
+        position: lastAnchor.position - rangeDiff,
+        panel: lastAnchor.panel
+      });
+    }
   }
 
   /**
@@ -309,7 +336,20 @@ abstract class Camera {
    * @return {AnchorPoint | null} The next {@link AnchorPoint}<ko>다음 {@link AnchorPoint}</ko>
    */
   public getNextAnchor(anchor: AnchorPoint): AnchorPoint | null {
-    return this._anchors[anchor.index + 1] || null;
+    const anchors = this._anchors;
+
+    if (!this._circularEnabled || anchor.index !== anchors.length - 1) {
+      return anchors[anchor.index + 1] || null;
+    } else {
+      const rangeDiff = this.rangeDiff;
+      const firstAnchor = anchors[0];
+
+      return new AnchorPoint({
+        index: firstAnchor.index,
+        position: firstAnchor.position + rangeDiff,
+        panel: firstAnchor.panel
+      });
+    }
   }
 
   /**
@@ -335,16 +375,7 @@ abstract class Camera {
    * @return {AnchorPoint | null} The {@link AnchorPoint} that includes the given position<ko>해당 좌표를 포함하는 {@link AnchorPoint}</ko>
    */
   public findAnchorIncludePosition(position: number): AnchorPoint | null {
-    const anchors = this._anchors;
-    const anchorsIncludingPosition = anchors.filter(anchor => anchor.panel.includePosition(position, true));
-
-    return anchorsIncludingPosition.reduce((nearest: AnchorPoint | null, anchor) => {
-      if (!nearest) return anchor;
-
-      return Math.abs(nearest.position - position) < Math.abs(anchor.position - position)
-        ? nearest
-        : anchor;
-    }, null);
+    return this._mode.findAnchorIncludePosition(position);
   }
 
   /**
@@ -396,8 +427,7 @@ abstract class Camera {
    * @return {number} A clamped position<ko>범위 제한된 좌표</ko>
    */
   public clampToReachablePosition(position: number): number {
-    const range = this._range;
-    return clamp(position, range.min, range.max);
+    return this._mode.clampToReachablePosition(position);
   }
 
   /**
@@ -407,13 +437,7 @@ abstract class Camera {
    * @return {boolean} Whether the panel's inside Camera's range<ko>도달 가능한 범위 내에 해당 패널이 존재하는지 여부</ko>
    */
   public canReach(panel: Panel): boolean {
-    const range = this._range;
-
-    if (panel.removed) return false;
-
-    const panelPos = panel.position;
-
-    return panelPos >= range.min && panelPos <= range.max;
+    return this._mode.canReach(panel);
   }
 
   /**
@@ -423,9 +447,38 @@ abstract class Camera {
    * @return Whether the panel element is visible at the current position<ko>현재 위치에서 해당 패널 엘리먼트가 보이는지 여부</ko>
    */
   public canSee(panel: Panel): boolean {
-    const visibleRange = this.visibleRange;
-    // Should not include margin, as we don't declare what the margin is visible as what the panel is visible.
-    return panel.isVisibleOnRange(visibleRange.min, visibleRange.max);
+    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}
+   */
+  public updateRange() {
+    const flicking = getFlickingAttached(this._flicking);
+    const renderer = flicking.renderer;
+    const panels = renderer.panels;
+
+    this._updateMode();
+    this._range = this._mode.getRange();
+
+    if (this._circularEnabled) {
+      panels.forEach(panel => panel.updateCircularToggleDirection());
+    }
+
+    this.updateOffset();
+
+    return this;
   }
 
   /**
@@ -456,14 +509,7 @@ abstract class Camera {
    * @return {this}
    */
   public updateAnchors(): this {
-    const flicking = getFlickingAttached(this._flicking);
-    const panels = flicking.renderer.panels;
-
-    this._anchors = panels.map((panel, index) => new AnchorPoint({
-      index,
-      position: panel.position,
-      panel
-    }));
+    this._anchors = this._mode.getAnchors();
 
     return this;
   }
@@ -503,6 +549,8 @@ abstract class Camera {
       .filter(panel => panel.position + panel.offset < position)
       .reduce((offset, panel) => offset + panel.sizeIncludingMargin, 0);
 
+    this._circularOffset = this._mode.getCircularOffset();
+
     this.applyTransform();
 
     return this;
@@ -529,7 +577,7 @@ abstract class Camera {
     const el = this._el;
     const flicking = getFlickingAttached(this._flicking);
 
-    const actualPosition = this._position - this._alignPos - this._offset;
+    const actualPosition = this._position - this._alignPos - this._offset + this._circularOffset;
 
     el.style[this._transform] = flicking.horizontal
       ? `translate(${-actualPosition}px)`
@@ -538,17 +586,19 @@ abstract class Camera {
     return this;
   }
 
-  protected _resetInternalValues() {
+  private _resetInternalValues() {
     this._position = 0;
     this._alignPos = 0;
     this._offset = 0;
+    this._circularOffset = 0;
+    this._circularEnabled = false;
     this._range = { min: 0, max: 0 };
     this._visiblePanels = [];
     this._anchors = [];
     this._needPanelTriggered = { prev: false, next: false };
   }
 
-  protected _refreshVisiblePanels() {
+  private _refreshVisiblePanels() {
     const flicking = getFlickingAttached(this._flicking);
     const panels = flicking.renderer.panels;
 
@@ -570,7 +620,7 @@ abstract class Camera {
     }
   }
 
-  protected _checkNeedPanel(): void {
+  private _checkNeedPanel(): void {
     const needPanelTriggered = this._needPanelTriggered;
 
     if (needPanelTriggered.prev && needPanelTriggered.next) return;
@@ -621,7 +671,7 @@ abstract class Camera {
     }
   }
 
-  protected _checkReachEnd(prevPos: number, newPos: number): void {
+  private _checkReachEnd(prevPos: number, newPos: number): void {
     const flicking = getFlickingAttached(this._flicking);
     const range = this._range;
 
@@ -637,7 +687,7 @@ abstract class Camera {
     }));
   }
 
-  protected _checkTranslateSupport = () => {
+  private _checkTranslateSupport = () => {
     const transforms = ["webkitTransform", "msTransform", "MozTransform", "OTransform", "transform"];
 
     const supportedStyle = document.documentElement.style;
@@ -654,6 +704,41 @@ abstract class Camera {
 
     this._transform = transformName;
   };
+
+  private _updateMode() {
+    const flicking = getFlickingAttached(this._flicking);
+
+    if (flicking.circular) {
+      const circularMode = new CircularCameraMode(flicking);
+      const canSetCircularMode = circularMode.checkAvailability();
+
+      if (canSetCircularMode) {
+        this._mode = circularMode;
+      } else {
+        const fallbackMode = flicking.circularFallback;
+
+        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);
+    }
+  }
+
+  private _togglePanels(prevPos: number, pos: number): boolean {
+    if (pos === prevPos) return false;
+
+    const flicking = getFlickingAttached(this._flicking);
+    const panels = flicking.renderer.panels;
+    const toggled = panels.map(panel => panel.toggle(prevPos, pos));
+
+    return toggled.some(isToggled => isToggled);
+  }
 }
 
 export default Camera;

package/src/camera/index.ts

@@ -3,17 +3,13 @@
  * egjs projects are licensed under the MIT license
  */
 import Camera, { CameraOptions } from "./Camera";
-import LinearCamera from "./LinearCamera";
-import CircularCamera from "./CircularCamera";
-import BoundCamera from "./BoundCamera";
 
 export {
-  Camera,
-  LinearCamera,
-  CircularCamera,
-  BoundCamera
+  Camera
 };
 
 export type {
   CameraOptions
 };
+
+export * from "./mode";