@egjs/flicking 4.12.1-beta.5 → 4.13.0

package/dist/flicking.pkgd.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
 */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
@@ -1094,6 +1094,9 @@ version: 4.12.1-beta.5
     };
     // 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) {
@@ -1405,41 +1408,53 @@ version: 4.12.1-beta.5
      * 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;
             }
           }
@@ -1491,7 +1506,6 @@ version: 4.12.1-beta.5
         configurable: true
       });
       __proto.enable = function () {
-        var _this = this;
         var flicking = this._flicking;
         var viewport = flicking.viewport;
         if (this._enabled) {
@@ -1499,32 +1513,55 @@ version: 4.12.1-beta.5
         }
         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;
@@ -9984,6 +10021,18 @@ version: 4.12.1-beta.5
         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) {
@@ -11275,16 +11324,18 @@ version: 4.12.1-beta.5
           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;
@@ -11325,6 +11376,7 @@ version: 4.12.1-beta.5
         _this._useResizeObserver = useResizeObserver;
         _this._resizeDebounce = resizeDebounce;
         _this._maxResizeDebounce = maxResizeDebounce;
+        _this._observePanelResize = observePanelResize;
         _this._useFractionalSize = useFractionalSize;
         _this._externalRenderer = externalRenderer;
         _this._renderExternal = renderExternal;
@@ -11409,6 +11461,19 @@ version: 4.12.1-beta.5
         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
         /**
@@ -12282,6 +12347,9 @@ version: 4.12.1-beta.5
         // OTHERS
         set: function (val) {
           this._autoResize = val;
+          if (!this._initialized) {
+            return;
+          }
           if (val) {
             this._autoResizer.enable();
           } else {
@@ -12304,13 +12372,38 @@ version: 4.12.1-beta.5
         },
         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.
@@ -12392,6 +12485,30 @@ version: 4.12.1-beta.5
         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)
@@ -12850,7 +12967,7 @@ version: 4.12.1-beta.5
                 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];
@@ -13023,7 +13140,7 @@ version: 4.12.1-beta.5
       __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$1(this, {
           align: this._align
@@ -13033,7 +13150,7 @@ version: 4.12.1-beta.5
         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();
       };
@@ -13115,7 +13232,7 @@ version: 4.12.1-beta.5
        * Flicking.VERSION;  // ex) 4.0.0
        * ```
        */
-      Flicking.VERSION = "4.12.1-beta.5";
+      Flicking.VERSION = "4.13.0";
       return Flicking;
     }(Component);