@egjs/flicking 4.7.3 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@egjs/flicking",
-	"version": "4.7.3",
+	"version": "4.9.0",
 	"description": "Everyday 30 million people experience. It's reliable, flexible and extendable carousel.",
 	"main": "dist/flicking.js",
 	"module": "dist/flicking.esm.js",
@@ -109,7 +109,7 @@
 		"html-to-react": "^1.4.5",
 		"http-serve": "^1.0.1",
 		"husky": "^1.3.1",
-		"jsdoc-to-mdx": "^1.0.5",
+		"jsdoc-to-mdx": "^1.1.2",
 		"karma-typescript-es6-transform": "^5.5.2",
 		"node-sass": "^7.0.1",
 		"npm-run-all": "^4.1.5",

package/src/Flicking.ts

@@ -78,6 +78,7 @@ export interface FlickingOptions {
   iOSEdgeSwipeThreshold: number;
   preventClickOnDrag: boolean;
   disableOnInit: boolean;
+  changeOnHold: boolean;
 
   // PERFORMANCE
   renderOnlyVisible: boolean;
@@ -89,6 +90,7 @@ export interface FlickingOptions {
   useResizeObserver: boolean;
   resizeDebounce: number;
   maxResizeDebounce: number;
+  useFractionalSize: boolean;
   externalRenderer: ExternalRenderer | null;
 
   // @deprecated
@@ -154,6 +156,7 @@ class Flicking extends Component<FlickingEvents> {
   private _iOSEdgeSwipeThreshold: FlickingOptions["iOSEdgeSwipeThreshold"];
   private _preventClickOnDrag: FlickingOptions["preventClickOnDrag"];
   private _disableOnInit: FlickingOptions["disableOnInit"];
+  private _changeOnHold: FlickingOptions["changeOnHold"];
 
   private _renderOnlyVisible: FlickingOptions["renderOnlyVisible"];
 
@@ -162,6 +165,7 @@ class Flicking extends Component<FlickingEvents> {
   private _useResizeObserver: FlickingOptions["useResizeObserver"];
   private _resizeDebounce: FlickingOptions["resizeDebounce"];
   private _maxResizeDebounce: FlickingOptions["maxResizeDebounce"];
+  private _useFractionalSize: FlickingOptions["useFractionalSize"];
   private _externalRenderer: FlickingOptions["externalRenderer"];
   private _renderExternal: FlickingOptions["renderExternal"];
 
@@ -570,6 +574,15 @@ class Flicking extends Component<FlickingEvents> {
    * @default false
    */
   public get disableOnInit() { return this._disableOnInit; }
+  /**
+   * Change active panel index on mouse/touch hold while animating.
+   * `index` of the `willChange`/`willRestore` event will be used as new index.
+   * @ko 애니메이션 도중 마우스/터치 입력시 현재 활성화된 패널의 인덱스를 변경합니다.
+   * `willChange`/`willRestore` 이벤트의 `index`값이 새로운 인덱스로 사용될 것입니다.
+   * @type {boolean}
+   * @default false
+   */
+  public get changeOnHold() { return this._changeOnHold; }
   // PERFORMANCE
   /**
    * Whether to render visible panels only. This can dramatically increase performance when there're many panels
@@ -654,6 +667,17 @@ class Flicking extends Component<FlickingEvents> {
    * @default 100
    */
   public get maxResizeDebounce() { return this._maxResizeDebounce; }
+  /**
+   * By enabling this, Flicking will calculate all internal size with CSS width computed with getComputedStyle.
+   * This can prevent 1px offset issue in some cases where panel size has the fractional part.
+   * All sizes will have the original size before CSS {@link https://developer.mozilla.org/en-US/docs/Web/CSS/transform transform} is applied on the element.
+   * @ko 이 옵션을 활성화할 경우, Flicking은 내부의 모든 크기를 {@link https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect getBoundingClientRect}를 이용하여 계산합니다.
+   * 이를 통해, 패널 크기에 소수점을 포함할 경우에 발생할 수 있는 일부 1px 오프셋 이슈를 해결 가능합니다.
+   * 모든 크기는 CSS {@link https://developer.mozilla.org/en-US/docs/Web/CSS/transform transform}이 엘리먼트에 적용되기 이전의 크기를 사용할 것입니다.
+   * @type {boolean}
+   * @default false
+   */
+  public get useFractionalSize() { return this._useFractionalSize; }
   /**
    * This is an option for the frameworks(React, Vue, Angular, ...). Don't set it as it's automatically managed by Flicking.
    * @ko 프레임워크(React, Vue, Angular, ...)에서만 사용하는 옵션으로, 자동으로 설정되므로 따로 사용하실 필요 없습니다!
@@ -720,6 +744,7 @@ class Flicking extends Component<FlickingEvents> {
   }
 
   public set disableOnInit(val: FlickingOptions["disableOnInit"]) { this._disableOnInit = val; }
+  public set changeOnHold(val: FlickingOptions["changeOnHold"]) { this._changeOnHold = val; }
   // PERFORMANCE
   public set renderOnlyVisible(val: FlickingOptions["renderOnlyVisible"]) { this._renderOnlyVisible = val; }
   // OTHERS
@@ -794,6 +819,7 @@ class Flicking extends Component<FlickingEvents> {
     iOSEdgeSwipeThreshold = 30,
     preventClickOnDrag = true,
     disableOnInit = false,
+    changeOnHold = false,
     renderOnlyVisible = false,
     virtual = null,
     autoInit = true,
@@ -801,6 +827,7 @@ class Flicking extends Component<FlickingEvents> {
     useResizeObserver = true,
     resizeDebounce = 0,
     maxResizeDebounce = 100,
+    useFractionalSize = false,
     externalRenderer = null,
     renderExternal = null
   }: Partial<FlickingOptions> = {}) {
@@ -836,17 +863,19 @@ class Flicking extends Component<FlickingEvents> {
     this._iOSEdgeSwipeThreshold = iOSEdgeSwipeThreshold;
     this._preventClickOnDrag = preventClickOnDrag;
     this._disableOnInit = disableOnInit;
+    this._changeOnHold = changeOnHold;
     this._renderOnlyVisible = renderOnlyVisible;
     this._autoInit = autoInit;
     this._autoResize = autoResize;
     this._useResizeObserver = useResizeObserver;
     this._resizeDebounce = resizeDebounce;
     this._maxResizeDebounce = maxResizeDebounce;
+    this._useFractionalSize = useFractionalSize;
     this._externalRenderer = externalRenderer;
     this._renderExternal = renderExternal;
 
     // Create core components
-    this._viewport = new Viewport(getElement(root));
+    this._viewport = new Viewport(this, getElement(root));
     this._autoResizer = new AutoResizer(this);
     this._renderer = this._createRenderer();
     this._camera = this._createCamera();
@@ -1275,6 +1304,8 @@ class Flicking extends Component<FlickingEvents> {
     camera.updateAlignPos();
     camera.updateRange();
     camera.updateAnchors();
+    camera.updateAdaptiveHeight();
+    camera.updateOffset();
     await renderer.render();
 
     if (control.animating) {

package/src/control/AxesController.ts

@@ -368,7 +368,7 @@ class AxesController {
   };
 
   private _onAxesChange = () => {
-    this._dragged = true;
+    this._dragged = !!this._panInput?.isEnabled();
   };
 
   private _preventClickWhenDragged = (e: MouseEvent) => {

package/src/control/SnapControl.ts

@@ -89,7 +89,7 @@ class SnapControl extends Control {
     const camera = flicking.camera;
     const activeAnchor = camera.findActiveAnchor();
     const anchorAtCamera = camera.findNearestAnchor(camera.position);
-    const state = flicking.control.controller.state;
+    const state = this._controller.state;
 
     if (!activeAnchor || !anchorAtCamera) {
       return Promise.reject(new FlickingError(ERROR.MESSAGE.POSITION_NOT_REACHABLE(position), ERROR.CODE.POSITION_NOT_REACHABLE));
@@ -111,10 +111,13 @@ class SnapControl extends Control {
       targetAnchor = this._findSnappedAnchor(position, anchorAtCamera);
     } else if (absPosDelta >= flicking.threshold && absPosDelta > 0) {
       // Move to the adjacent panel
-      targetAnchor = this._findAdjacentAnchor(posDelta, anchorAtCamera);
+      targetAnchor = this._findAdjacentAnchor(position, posDelta, anchorAtCamera);
     } else {
       // Restore to active panel
-      targetAnchor = anchorAtCamera;
+      return this.moveToPanel(activeAnchor.panel, {
+        duration,
+        axesEvent
+      });
     }
 
     this._triggerIndexChangeEvent(targetAnchor.panel, position, axesEvent);
@@ -190,9 +193,18 @@ class SnapControl extends Control {
     }
   }
 
-  private _findAdjacentAnchor(posDelta: number, anchorAtCamera: AnchorPoint): AnchorPoint {
+  private _findAdjacentAnchor(position: number, posDelta: number, anchorAtCamera: AnchorPoint): AnchorPoint {
     const flicking = getFlickingAttached(this._flicking);
     const camera = flicking.camera;
+
+    if (camera.circularEnabled) {
+      const anchorIncludePosition = camera.findAnchorIncludePosition(position);
+
+      if (anchorIncludePosition && anchorIncludePosition.position !== anchorAtCamera.position) {
+        return anchorIncludePosition;
+      }
+    }
+
     const adjacentAnchor = (posDelta > 0 ? camera.getNextAnchor(anchorAtCamera) : camera.getPrevAnchor(anchorAtCamera)) ?? anchorAtCamera;
 
     return adjacentAnchor;

package/src/control/StrictControl.ts

@@ -194,6 +194,7 @@ class StrictControl extends Control {
     const axesRange = this._controller.range;
     const indexRange = this._indexRange;
     const cameraRange = camera.range;
+    const state = this._controller.state;
 
     const clampedPosition = clamp(camera.clampToReachablePosition(position), axesRange[0], axesRange[1]);
     const anchorAtPosition = camera.findAnchorIncludePosition(clampedPosition);
@@ -203,8 +204,11 @@ class StrictControl extends Control {
     }
 
     const prevPos = activePanel.position;
+    const posDelta = flicking.animating
+      ? state.delta
+      : position - camera.position;
 
-    const isOverThreshold = Math.abs(position - prevPos) >= flicking.threshold;
+    const isOverThreshold = Math.abs(posDelta) >= flicking.threshold;
     const adjacentAnchor = (position > prevPos)
       ? camera.getNextAnchor(anchorAtPosition)
       : camera.getPrevAnchor(anchorAtPosition);

package/src/control/states/AnimatingState.ts

@@ -32,10 +32,16 @@ class AnimatingState extends State {
 
   public onHold(ctx: Parameters<State["onHold"]>[0]): void {
     const { flicking, axesEvent, transitTo } = ctx;
+    const targetPanel = this._targetPanel;
+    const control = flicking.control;
 
     this._delta = 0;
     flicking.control.updateInput();
 
+    if (flicking.changeOnHold && targetPanel) {
+      control.setActive(targetPanel, control.activePanel, axesEvent.isTrusted);
+    }
+
     const holdStartEvent = new ComponentEvent(EVENTS.HOLD_START, { axesEvent });
     flicking.trigger(holdStartEvent);
 

package/src/core/FlickingError.ts

@@ -10,7 +10,7 @@ import { setPrototypeOf } from "../utils";
  * @ko Flicking 내부에서 알려진 오류 발생시 throw되는 에러
  * @property {number} code Error code<ko>에러 코드</ko>
  * @property {string} message Error message<ko>에러 메시지</ko>
- * @see {@link Constants.ERROR_CODE ERROR_CODE}
+ * @see {@link ERROR_CODE ERROR_CODE}
  * @example
  * ```ts
  * import Flicking, { FlickingError, ERROR_CODES } from "@egjs/flicking";

package/src/core/Viewport.ts

@@ -2,13 +2,15 @@
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
-import { getStyle, isString } from "../utils";
+import Flicking from "../Flicking";
+import { getElementSize, getStyle, isString } from "../utils";
 
 /**
  * A component that manages viewport size
  * @ko 뷰포트 크기 정보를 담당하는 컴포넌트
  */
 class Viewport {
+  private _flicking: Flicking;
   private _el: HTMLElement;
   private _width: number;
   private _height: number;
@@ -57,7 +59,8 @@ class Viewport {
   /**
    * @param el A viewport element<ko>뷰포트 엘리먼트</ko>
    */
-  public constructor(el: HTMLElement) {
+  public constructor(flicking: Flicking, el: HTMLElement) {
+    this._flicking = flicking;
     this._el = el;
     this._width = 0;
     this._height = 0;
@@ -120,9 +123,25 @@ class Viewport {
   public resize() {
     const el = this._el;
     const elStyle = getStyle(el);
+    const {
+      useFractionalSize
+    } = this._flicking;
+
+    this._width = getElementSize({
+      el,
+      horizontal: true,
+      useFractionalSize,
+      useOffset: false,
+      style: elStyle
+    });
+    this._height = getElementSize({
+      el,
+      horizontal: false,
+      useFractionalSize,
+      useOffset: false,
+      style: elStyle
+    });
 
-    this._width = el.clientWidth;
-    this._height = el.clientHeight;
     this._padding = {
       left: elStyle.paddingLeft ? parseFloat(elStyle.paddingLeft) : 0,
       right: elStyle.paddingRight ? parseFloat(elStyle.paddingRight) : 0,

package/src/core/panel/Panel.ts

@@ -3,7 +3,7 @@
  * egjs projects are licensed under the MIT license
  */
 import Flicking from "../../Flicking";
-import { getProgress, getStyle, parseAlign, setSize } from "../../utils";
+import { getElementSize, getProgress, getStyle, parseAlign, setSize } from "../../utils";
 import { ALIGN, DIRECTION } from "../../const/external";
 import { LiteralUnion, ValueOf } from "../../type/internal";
 
@@ -313,7 +313,10 @@ class Panel {
   }): this {
     const el = this.element;
     const flicking = this._flicking;
-    const horizontal = flicking.horizontal;
+    const {
+      horizontal,
+      useFractionalSize
+    } = flicking;
 
     if (cached) {
       this._size = cached.size;
@@ -322,7 +325,14 @@ class Panel {
     } else {
       const elStyle = getStyle(el);
 
-      this._size = horizontal ? el.offsetWidth : el.offsetHeight;
+      this._size = getElementSize({
+        el,
+        horizontal,
+        useFractionalSize,
+        useOffset: true,
+        style: elStyle
+      });
+
       this._margin = horizontal
         ? {
           prev: parseFloat(elStyle.marginLeft || "0"),
@@ -331,7 +341,16 @@ class Panel {
           prev: parseFloat(elStyle.marginTop || "0"),
           next: parseFloat(elStyle.marginBottom || "0")
         };
-      this._height = horizontal ? el.offsetHeight : this._size;
+
+      this._height = horizontal
+        ? getElementSize({
+          el,
+          horizontal: false,
+          useFractionalSize,
+          useOffset: true,
+          style: elStyle
+        })
+        : this._size;
     }
 
     this.updatePosition();

package/src/utils.ts

@@ -300,6 +300,48 @@ export const range = (end: number): number[] => {
   return arr;
 };
 
+export const getElementSize = ({
+  el,
+  horizontal,
+  useFractionalSize,
+  useOffset,
+  style
+}: {
+  el: HTMLElement;
+  horizontal: boolean;
+  useFractionalSize: boolean;
+  useOffset: boolean;
+  style: CSSStyleDeclaration;
+}): number => {
+  if (useFractionalSize) {
+    const baseSize = parseFloat(horizontal ? style.width : style.height);
+    const isBorderBoxSizing = style.boxSizing === "border-box";
+    const border = horizontal
+      ? parseFloat(style.borderLeftWidth || "0") + parseFloat(style.borderRightWidth || "0")
+      : parseFloat(style.borderTopWidth || "0") + parseFloat(style.borderBottomWidth || "0");
+
+    if (isBorderBoxSizing) {
+      return useOffset
+        ? baseSize
+        : baseSize - border;
+    } else {
+      const padding = horizontal
+        ? parseFloat(style.paddingLeft || "0") + parseFloat(style.paddingRight || "0")
+        : parseFloat(style.paddingTop || "0") + parseFloat(style.paddingBottom || "0");
+
+      return useOffset
+        ? baseSize + padding + border
+        : baseSize + padding;
+    }
+  } else {
+    const sizeStr = horizontal ? "Width" : "Height";
+
+    return useOffset
+      ? el[`offset${sizeStr}`]
+      : el[`client${sizeStr}`];
+  }
+};
+
 export const setPrototypeOf = Object.setPrototypeOf || ((obj, proto) => {
   obj.__proto__ = proto;
   return obj;