@egjs/flicking 4.12.1-beta.5 → 4.13.0

package/core-packages-link.js

@@ -1,11 +1,12 @@
-/**
-
-프레임워크 컴포넌트를 디버깅할 때 코어 바닐라 로직을 수정하면서 확인할 필요가 있을 때,
-이 스크립트를 이용하면 바닐라 로직 수정사항이 프레임워크 컴포넌트 로컬 데모환경에도 반영된다.
+/* eslint-disable */
 
-인자로 프레임워크 컴포넌트 패키지의 루트 디렉토리를 제공하면 된다.
-
-사용 예시: node core-package-link.js react-flicking
+/**
+ * 프레임워크 컴포넌트를 디버깅할 때 코어 바닐라 로직을 수정하면서 확인할 필요가 있을 때,
+ * 이 스크립트를 이용하면 바닐라 로직 수정사항이 프레임워크 컴포넌트 로컬 데모환경에도 반영된다.
+ * 
+ * 인자로 프레임워크 컴포넌트 패키지의 루트 디렉토리를 제공하면 된다.
+ *
+ * 사용 예시: node core-package-link.js react-flicking
  */
 
 const { execSync } = require("child_process");

package/declaration/Flicking.d.ts

@@ -1,5 +1,6 @@
 import Component from "@egjs/component";
 import Viewport from "./core/Viewport";
+import AutoResizer from "./core/AutoResizer";
 import { Panel } from "./core/panel";
 import VirtualManager, { VirtualOptions } from "./core/VirtualManager";
 import { Control } from "./control";
@@ -65,6 +66,7 @@ export interface FlickingOptions {
     autoResize: boolean;
     useResizeObserver: boolean;
     resizeDebounce: number;
+    observePanelResize: boolean;
     maxResizeDebounce: number;
     useFractionalSize: boolean;
     externalRenderer: ExternalRenderer | null;
@@ -115,6 +117,7 @@ declare class Flicking extends Component<FlickingEvents> {
     private _autoResize;
     private _useResizeObserver;
     private _resizeDebounce;
+    private _observePanelResize;
     private _maxResizeDebounce;
     private _useFractionalSize;
     private _externalRenderer;
@@ -127,6 +130,7 @@ declare class Flicking extends Component<FlickingEvents> {
     get camera(): Camera;
     get renderer(): Renderer;
     get viewport(): Viewport;
+    get autoResizer(): AutoResizer;
     get initialized(): boolean;
     get circularEnabled(): boolean;
     get virtualEnabled(): boolean;
@@ -174,6 +178,7 @@ declare class Flicking extends Component<FlickingEvents> {
     get autoInit(): boolean;
     get autoResize(): FlickingOptions["autoResize"];
     get useResizeObserver(): FlickingOptions["useResizeObserver"];
+    get observePanelResize(): FlickingOptions["observePanelResize"];
     get resizeDebounce(): number;
     get maxResizeDebounce(): number;
     get useFractionalSize(): boolean;
@@ -182,6 +187,7 @@ declare class Flicking extends Component<FlickingEvents> {
         renderer: new (options: RendererOptions) => ExternalRenderer;
         rendererOptions: RendererOptions;
     };
+    get optimizeSizeUpdate(): FlickingOptions["optimizeSizeUpdate"];
     set align(val: FlickingOptions["align"]);
     set defaultIndex(val: FlickingOptions["defaultIndex"]);
     set horizontal(val: FlickingOptions["horizontal"]);
@@ -211,7 +217,9 @@ declare class Flicking extends Component<FlickingEvents> {
     set renderOnlyVisible(val: FlickingOptions["renderOnlyVisible"]);
     set autoResize(val: FlickingOptions["autoResize"]);
     set useResizeObserver(val: FlickingOptions["useResizeObserver"]);
-    constructor(root: HTMLElement | string, { align, defaultIndex, horizontal, circular, circularFallback, bound, adaptive, panelsPerView, noPanelStyleOverride, resizeOnContentsReady, nested, needPanelThreshold, preventEventsBeforeInit, deceleration, duration, easing, inputType, moveType, threshold, dragThreshold, interruptable, bounce, iOSEdgeSwipeThreshold, preventClickOnDrag, preventDefaultOnDrag, disableOnInit, changeOnHold, renderOnlyVisible, virtual, autoInit, autoResize, useResizeObserver, resizeDebounce, maxResizeDebounce, useFractionalSize, externalRenderer, renderExternal, optimizeSizeUpdate, }?: Partial<FlickingOptions>);
+    set observePanelResize(val: FlickingOptions["observePanelResize"]);
+    set optimizeSizeUpdate(val: FlickingOptions["optimizeSizeUpdate"]);
+    constructor(root: HTMLElement | string, { align, defaultIndex, horizontal, circular, circularFallback, bound, adaptive, panelsPerView, noPanelStyleOverride, resizeOnContentsReady, nested, needPanelThreshold, preventEventsBeforeInit, deceleration, duration, easing, inputType, moveType, threshold, dragThreshold, interruptable, bounce, iOSEdgeSwipeThreshold, preventClickOnDrag, preventDefaultOnDrag, disableOnInit, changeOnHold, renderOnlyVisible, virtual, autoInit, autoResize, useResizeObserver, resizeDebounce, observePanelResize, maxResizeDebounce, useFractionalSize, externalRenderer, renderExternal, optimizeSizeUpdate }?: Partial<FlickingOptions>);
     init(): Promise<void>;
     destroy(): void;
     prev(duration?: number): Promise<void>;
@@ -222,7 +230,7 @@ declare class Flicking extends Component<FlickingEvents> {
     getPanel(index: number): Panel | null;
     enableInput(): this;
     disableInput(): this;
-    getStatus({ index, position, includePanelHTML, visiblePanelsOnly, }?: Partial<{
+    getStatus({ index, position, includePanelHTML, visiblePanelsOnly }?: Partial<{
         index: boolean;
         position: boolean;
         includePanelHTML: boolean;

package/declaration/core/AutoResizer.d.ts

@@ -8,7 +8,12 @@ declare class AutoResizer {
     get enabled(): boolean;
     constructor(flicking: Flicking);
     enable(): this;
+    observePanels(): this;
+    unobservePanels(): this;
+    observe(element: HTMLElement): this;
+    unobserve(element: HTMLElement): this;
     disable(): this;
+    private _onResizeWrapper;
     private _onResize;
     private _doScheduledResize;
     private _skipFirstResize;

package/dist/flicking.cjs.js

@@ -4,7 +4,7 @@ name: @egjs/flicking
 license: MIT
 author: NAVER Corp.
 repository: https://github.com/naver/egjs-flicking
-version: 4.12.1-beta.5
+version: 4.13.0
 */
 'use strict';
 
@@ -674,6 +674,9 @@ var getProgress = function (pos, prev, next) {
 };
 // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
 var getStyle = function (el) {
+  if (!el) {
+    return {};
+  }
   return window.getComputedStyle(el) || el.currentStyle;
 };
 var setSize = function (el, _a) {
@@ -950,41 +953,53 @@ var Viewport = /*#__PURE__*/function () {
  * Copyright (c) 2015 NAVER Corp.
  * egjs projects are licensed under the MIT license
  */
+/**
+ * A component that detects size change and trigger resize method when the autoResize option is used
+ * @ko autoResize 옵션을 사용할 때 크기 변화를 감지하고 Flicking의 resize를 호출하는 컴포넌트
+ */
 var AutoResizer = /*#__PURE__*/function () {
+  /** */
   function AutoResizer(flicking) {
     var _this = this;
+    this._onResizeWrapper = function () {
+      _this._onResize([]);
+    };
     this._onResize = function (entries) {
       var flicking = _this._flicking;
       var resizeDebounce = flicking.resizeDebounce;
       var maxResizeDebounce = flicking.maxResizeDebounce;
-      if (entries.length) {
-        var resizeEntryInfo = entries[0].contentRect;
+      var resizedViewportElement = flicking.element;
+      // 현재 구현에서 리사이즈 옵저빙 대상은 패널과 뷰포트 2개만 존재.
+      // 아래는 뷰포트만 변경되었을 때 동작해야하는 로직이 있으므로 아래와 같이 조건문을 건다.
+      // 패널 쪽에서는 리사이즈 감지에 resizeObserver를 사용하지 않는 경우가 없으므로 이 조건은 곧 뷰포트만 리사이즈가 된 경우를 의미한다.
+      var isResizedViewportOnly = entries.find(function (e) {
+        return e.target === flicking.element;
+      }) && entries.length === 1;
+      // 참고: resizeObserver를 사용하지 않은 경우에는 entries.length가 0으로 오는데 이 경우에는 그냥 항상 리사이즈가 진행되도록 한다.
+      //   (vw, vh 등을 사용하는 경우 이상 동작이 발생할 여지가 있기 때문이다)
+      if (isResizedViewportOnly) {
+        // resize 이벤트가 발생했으나 이전과 width, height의 변화가 없다면 이후 로직을 진행하지 않는다.
         var beforeSize = {
           width: flicking.viewport.width,
           height: flicking.viewport.height
         };
-        ({
-          width: resizeEntryInfo.width,
-          height: resizeEntryInfo.height
-        });
-        var new_afterSize = {
+        var afterSize = {
           width: getElementSize({
-            el: entries[0].target,
+            el: resizedViewportElement,
             horizontal: true,
             useFractionalSize: _this._flicking.useFractionalSize,
             useOffset: false,
-            style: getStyle(entries[0].target)
+            style: getStyle(resizedViewportElement)
           }),
           height: getElementSize({
-            el: entries[0].target,
+            el: resizedViewportElement,
             horizontal: false,
             useFractionalSize: _this._flicking.useFractionalSize,
             useOffset: false,
-            style: getStyle(entries[0].target)
+            style: getStyle(resizedViewportElement)
           })
         };
-        // resize 이벤트가 발생했으나 이전과 width, height의 변화가 없다면 이후 로직을 진행하지 않는다.
-        if (beforeSize.height === new_afterSize.height && beforeSize.width === new_afterSize.width) {
+        if (beforeSize.height === afterSize.height && beforeSize.width === afterSize.width) {
           return;
         }
       }
@@ -1036,7 +1051,6 @@ var AutoResizer = /*#__PURE__*/function () {
     configurable: true
   });
   __proto.enable = function () {
-    var _this = this;
     var flicking = this._flicking;
     var viewport = flicking.viewport;
     if (this._enabled) {
@@ -1044,32 +1058,55 @@ var AutoResizer = /*#__PURE__*/function () {
     }
     if (flicking.useResizeObserver && !!window.ResizeObserver) {
       var viewportSizeNot0 = viewport.width !== 0 || viewport.height !== 0;
-      var resizeObserver = viewportSizeNot0 ? new ResizeObserver(function (entries) {
-        return _this._skipFirstResize(entries);
-      }) : new ResizeObserver(function (entries) {
-        return _this._onResize(entries);
-      });
-      resizeObserver.observe(flicking.viewport.element);
+      var resizeObserver = viewportSizeNot0 ? new ResizeObserver(this._skipFirstResize) : new ResizeObserver(this._onResize);
       this._resizeObserver = resizeObserver;
+      this.observe(flicking.viewport.element);
+      if (flicking.observePanelResize) {
+        this.observePanels();
+      }
     } else {
-      window.addEventListener("resize", function () {
-        return _this._onResize([]);
-      });
+      window.addEventListener("resize", this._onResizeWrapper);
     }
     this._enabled = true;
     return this;
   };
-  __proto.disable = function () {
+  __proto.observePanels = function () {
+    var _this = this;
+    this._flicking.panels.forEach(function (panel) {
+      _this.observe(panel.element);
+    });
+    return this;
+  };
+  __proto.unobservePanels = function () {
     var _this = this;
+    this._flicking.panels.forEach(function (panel) {
+      _this.unobserve(panel.element);
+    });
+    return this;
+  };
+  __proto.observe = function (element) {
+    var resizeObserver = this._resizeObserver;
+    if (!resizeObserver) return this;
+    resizeObserver.observe(element);
+    return this;
+  };
+  __proto.unobserve = function (element) {
+    var resizeObserver = this._resizeObserver;
+    if (!resizeObserver) return this;
+    resizeObserver.unobserve(element);
+    if (this._flicking.observePanelResize) {
+      this.unobservePanels();
+    }
+    return this;
+  };
+  __proto.disable = function () {
     if (!this._enabled) return this;
     var resizeObserver = this._resizeObserver;
     if (resizeObserver) {
       resizeObserver.disconnect();
       this._resizeObserver = null;
     } else {
-      window.removeEventListener("resize", function () {
-        return _this._onResize([]);
-      });
+      window.removeEventListener("resize", this._onResizeWrapper);
     }
     this._enabled = false;
     return this;
@@ -4867,6 +4904,18 @@ var Renderer = /*#__PURE__*/function () {
     var activePanel = control.activePanel;
     // Update camera & control
     this._updateCameraAndControl();
+    if (flicking.autoResize && flicking.useResizeObserver) {
+      panelsAdded.forEach(function (panel) {
+        if (panel.element) {
+          flicking.autoResizer.observe(panel.element);
+        }
+      });
+      panelsRemoved.forEach(function (panel) {
+        if (panel.element) {
+          flicking.autoResizer.unobserve(panel.element);
+        }
+      });
+    }
     void this.render();
     if (!flicking.animating) {
       if (!activePanel || activePanel.removed) {
@@ -6144,16 +6193,18 @@ var Flicking = /*#__PURE__*/function (_super) {
       useResizeObserver = _9 === void 0 ? true : _9,
       _10 = _b.resizeDebounce,
       resizeDebounce = _10 === void 0 ? 0 : _10,
-      _11 = _b.maxResizeDebounce,
-      maxResizeDebounce = _11 === void 0 ? 100 : _11,
-      _12 = _b.useFractionalSize,
-      useFractionalSize = _12 === void 0 ? false : _12,
-      _13 = _b.externalRenderer,
-      externalRenderer = _13 === void 0 ? null : _13,
-      _14 = _b.renderExternal,
-      renderExternal = _14 === void 0 ? null : _14,
-      _15 = _b.optimizeSizeUpdate,
-      optimizeSizeUpdate = _15 === void 0 ? false : _15;
+      _11 = _b.observePanelResize,
+      observePanelResize = _11 === void 0 ? false : _11,
+      _12 = _b.maxResizeDebounce,
+      maxResizeDebounce = _12 === void 0 ? 100 : _12,
+      _13 = _b.useFractionalSize,
+      useFractionalSize = _13 === void 0 ? false : _13,
+      _14 = _b.externalRenderer,
+      externalRenderer = _14 === void 0 ? null : _14,
+      _15 = _b.renderExternal,
+      renderExternal = _15 === void 0 ? null : _15,
+      _16 = _b.optimizeSizeUpdate,
+      optimizeSizeUpdate = _16 === void 0 ? false : _16;
     var _this = _super.call(this) || this;
     // Internal states
     _this._initialized = false;
@@ -6194,6 +6245,7 @@ var Flicking = /*#__PURE__*/function (_super) {
     _this._useResizeObserver = useResizeObserver;
     _this._resizeDebounce = resizeDebounce;
     _this._maxResizeDebounce = maxResizeDebounce;
+    _this._observePanelResize = observePanelResize;
     _this._useFractionalSize = useFractionalSize;
     _this._externalRenderer = externalRenderer;
     _this._renderExternal = renderExternal;
@@ -6278,6 +6330,19 @@ var Flicking = /*#__PURE__*/function (_super) {
     enumerable: false,
     configurable: true
   });
+  Object.defineProperty(__proto, "autoResizer", {
+    /**
+     * {@link AutoResizer} instance of the Flicking
+     * @ko 현재 Flicking에 활성화된 {@link AutoResizer} 인스턴스
+     * @internal
+     * @readonly
+     */
+    get: function () {
+      return this._autoResizer;
+    },
+    enumerable: false,
+    configurable: true
+  });
   Object.defineProperty(__proto, "initialized", {
     // Internal States
     /**
@@ -7151,6 +7216,9 @@ var Flicking = /*#__PURE__*/function (_super) {
     // OTHERS
     set: function (val) {
       this._autoResize = val;
+      if (!this._initialized) {
+        return;
+      }
       if (val) {
         this._autoResizer.enable();
       } else {
@@ -7173,13 +7241,38 @@ var Flicking = /*#__PURE__*/function (_super) {
     },
     set: function (val) {
       this._useResizeObserver = val;
-      if (this._autoResize) {
+      if (this._initialized && this._autoResize) {
         this._autoResizer.enable();
       }
     },
     enumerable: false,
     configurable: true
   });
+  Object.defineProperty(__proto, "observePanelResize", {
+    /**
+     * Whether to use {@link https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver ResizeObserver} to observe the size of the panel element
+     * This is only available when `useResizeObserver` is enabled.
+     * This option garantees that the resize event is triggered when the size of the panel element is changed.
+     * @ko 이 옵션을 활성화할 경우, {@link https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver ResizeObserver}를 사용하여 패널 엘리먼트의 크기를 추적합니다.
+     * 이 옵션은 `useResizeObserver` 옵션이 활성화된 경우에만 사용할 수 있습니다.
+     * 이 옵션은 패널 엘리먼트의 크기가 변경될 경우 resize 이벤트가 발생하도록 보장합니다.
+     */
+    get: function () {
+      return this._observePanelResize;
+    },
+    set: function (val) {
+      this._observePanelResize = val;
+      if (this._initialized && this._autoResize) {
+        if (val) {
+          this._autoResizer.observePanels();
+        } else {
+          this._autoResizer.unobservePanels();
+        }
+      }
+    },
+    enumerable: false,
+    configurable: true
+  });
   Object.defineProperty(__proto, "resizeDebounce", {
     /**
      * Delays size recalculation from `autoResize` by the given time in milisecond.
@@ -7261,6 +7354,30 @@ var Flicking = /*#__PURE__*/function (_super) {
     enumerable: false,
     configurable: true
   });
+  Object.defineProperty(__proto, "optimizeSizeUpdate", {
+    /**
+     * This option works only when autoResize is set to true.
+     * By default, autoResize listens to changes in both the viewport's width and height, updating all panel sizes accordingly.
+     * When optimizeSizeUpdate is enabled, the update behavior is optimized based on the flicking direction:
+     * If direction is "horizontal", only changes in width will trigger panel size updates.
+     * If direction is "vertical", only changes in height will do so.
+     * This option is useful when panel heights vary and unwanted flickering occurs due to frequent size recalculations during flicking. Enabling optimizeSizeUpdate prevents unnecessary updates and helps maintain visual stability.
+     * @ko optimizeSizeUpdate는 autoResize가 true일 때만 동작합니다.
+     * 기본적으로 autoResize는 뷰포트의 width와 height 변화를 모두 감지하여 패널들의 사이즈를 업데이트합니다.
+     * 이 옵션을 활성화하면 플리킹 방향에 따라 필요한 차원(horizontal → width, vertical → height)에 대해서만 사이즈를 업데이트합니다.
+     * 내부 패널의 높이가 서로 다를 때, 플리킹 중 과도한 리사이징으로 인한 깜빡임 현상을 줄이는 데 유용합니다.
+     * @type {boolean}
+     * @default false
+     */
+    get: function () {
+      return this._optimizeSizeUpdate;
+    },
+    set: function (val) {
+      this._optimizeSizeUpdate = val;
+    },
+    enumerable: false,
+    configurable: true
+  });
   /**
    * Initialize Flicking and move to the default index
    * This is automatically called on Flicking's constructor when `autoInit` is true(default)
@@ -7719,7 +7836,7 @@ var Flicking = /*#__PURE__*/function (_super) {
             if (!(this.horizontal && viewport.width !== prevWidth || !this.horizontal && viewport.height !== prevHeight)) return [3 /*break*/, 2];
             return [4 /*yield*/, renderer.forceRenderAllPanels()];
           case 1:
-            _a.sent(); // Render all panel elements, to update sizes
+            _a.sent();
             _a.label = 2;
           case 2:
             return [3 /*break*/, 5];
@@ -7892,7 +8009,7 @@ var Flicking = /*#__PURE__*/function (_super) {
   __proto._createCamera = function () {
     if (this._circular && this._bound) {
       // eslint-disable-next-line no-console
-      console.warn('"circular" and "bound" option cannot be used together, ignoring bound.');
+      console.warn("\"circular\" and \"bound\" option cannot be used together, ignoring bound.");
     }
     return new Camera(this, {
       align: this._align
@@ -7902,7 +8019,7 @@ var Flicking = /*#__PURE__*/function (_super) {
     var externalRenderer = this._externalRenderer;
     if (this._virtual && this._panelsPerView <= 0) {
       // eslint-disable-next-line no-console
-      console.warn('"virtual" and "panelsPerView" option should be used together, ignoring virtual.');
+      console.warn("\"virtual\" and \"panelsPerView\" option should be used together, ignoring virtual.");
     }
     return externalRenderer ? externalRenderer : this._renderExternal ? this._createExternalRenderer() : this._createVanillaRenderer();
   };
@@ -7984,7 +8101,7 @@ var Flicking = /*#__PURE__*/function (_super) {
    * Flicking.VERSION;  // ex) 4.0.0
    * ```
    */
-  Flicking.VERSION = "4.12.1-beta.5";
+  Flicking.VERSION = "4.13.0";
   return Flicking;
 }(Component);