@logimaxx/kviews.js 1.2.4 → 1.3.1

package/dist/kviews.js

@@ -1,7 +1,7 @@
 /*!
  * KViews - Class-based API data binding library
- * Version: 1.2.4
- * Built: 2026-06-10T14:41:16.731Z
+ * Version: 1.3.1
+ * Built: 2026-06-29T17:09:29.460Z
  */
 var KViews = (() => {
   var __defProp = Object.defineProperty;
@@ -40,6 +40,7 @@ var KViews = (() => {
     createOverlay: () => createOverlay,
     createURL: () => createURL,
     dbg: () => dbg,
+    deepEqual: () => deepEqual,
     deepmerge: () => deepmerge,
     default: () => index_default,
     error: () => error,
@@ -89,6 +90,36 @@ var KViews = (() => {
     }
     throw new Error("Invalid options", options);
   }
+  function deepEqual(a, b) {
+    if (a === b) {
+      return true;
+    }
+    if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+      return false;
+    }
+    if (Array.isArray(a) || Array.isArray(b)) {
+      if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+        return false;
+      }
+      for (let i = 0; i < a.length; i++) {
+        if (!deepEqual(a[i], b[i])) {
+          return false;
+        }
+      }
+      return true;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) {
+      return false;
+    }
+    for (const key of keysA) {
+      if (!Object.prototype.hasOwnProperty.call(b, key) || !deepEqual(a[key], b[key])) {
+        return false;
+      }
+    }
+    return true;
+  }
   function deepmerge(target, source, optionsArgument) {
     function defaultArrayMerge(target2, source2, optionsArgument2) {
       let destination = target2.slice();
@@ -906,6 +937,29 @@ var KViews = (() => {
         url.parameters[`page[${type}][limit]`] = pageSize;
       }
     }
+    /**
+     * Read pagination params already present in a collection URL.
+     *
+     * @param {import('../URL.js').URL} url - Collection URL
+     * @param {{ type?: string }} [context]
+     * @returns {{ offset?: number, pageSize?: number }}
+     */
+    extractListQueryFromUrl(url, context = {}) {
+      const { type } = context;
+      const result = {};
+      if (!url || !url.parameters || !type) {
+        return result;
+      }
+      const limitKey = `page[${type}][limit]`;
+      const offsetKey = `page[${type}][offset]`;
+      if (url.parameters.hasOwnProperty(limitKey)) {
+        result.pageSize = url.parameters[limitKey];
+      }
+      if (url.parameters.hasOwnProperty(offsetKey)) {
+        result.offset = url.parameters[offsetKey];
+      }
+      return result;
+    }
     /**
      * Serialize plain item data for a create (POST) request.
      *
@@ -1220,6 +1274,32 @@ var KViews = (() => {
       }
       url.parameters[this.limitParam] = pageSize;
     }
+    /**
+     * @param {import('../URL.js').URL} url
+     * @param {object} [context]
+     * @returns {{ offset?: number, pageSize?: number }}
+     */
+    extractListQueryFromUrl(url) {
+      const result = {};
+      if (!url || !url.parameters) {
+        return result;
+      }
+      if (url.parameters.hasOwnProperty(this.limitParam)) {
+        result.pageSize = url.parameters[this.limitParam];
+      } else if (url.parameters.hasOwnProperty("pageSize")) {
+        result.pageSize = url.parameters.pageSize;
+      }
+      if (this.paginationStyle === "page" && url.parameters.hasOwnProperty(this.pageParam)) {
+        const page = url.parameters[this.pageParam] * 1;
+        const pageSize = result.pageSize != null ? result.pageSize * 1 : null;
+        if (pageSize) {
+          result.offset = (page - 1) * pageSize;
+        }
+      } else if (url.parameters.hasOwnProperty(this.offsetParam)) {
+        result.offset = url.parameters[this.offsetParam];
+      }
+      return result;
+    }
     /**
      * @param {object|Array} itemData
      * @param {object} [context]
@@ -1882,17 +1962,26 @@ var KViews = (() => {
      */
     loadFromDataSource() {
       let loaders = [];
-      const overlay = createOverlay(this);
-      this.views.forEach((itemView) => {
-        if (itemView.el) {
-          let $el = $(itemView.el);
-          let loader = overlay.clone();
-          loader.insertBefore(itemView.el).width($el.width()).height($el.height());
-          loaders.push(loader);
-        }
-      });
+      const showLoader = this.showLoader !== false;
+      if (showLoader) {
+        const overlay = createOverlay(this);
+        this.views.forEach((itemView) => {
+          if (itemView.el) {
+            let $el = $(itemView.el);
+            let loader = overlay.clone();
+            loader.insertBefore(itemView.el).width($el.width()).height($el.height());
+            loaders.push(loader);
+          }
+        });
+      }
+      const removeLoaders = () => {
+        loaders.forEach((loader) => {
+          loader.remove();
+        });
+      };
       return new Promise((resolve, reject) => {
         if (!this.url) {
+          removeLoaders();
           reject(new Error("No valid URL provided"));
           return;
         }
@@ -1900,13 +1989,16 @@ var KViews = (() => {
         let urlString = this.url.toString ? this.url.toString() : this.url;
         this.storage.read(this, urlString, {}).then((resp) => {
           let data = resp.data;
-          this.loadFromRemoteDoc(data).render();
+          const parsedData = this._parseRemoteDoc(data);
+          if (!this._remoteDataEquals(parsedData)) {
+            this._applyParsedRemoteData(parsedData);
+            this.render();
+          }
           this._trigger("load", this);
-          loaders.forEach((loader) => {
-            loader.remove();
-          });
+          removeLoaders();
           resolve(this);
         }).catch((error2) => {
+          removeLoaders();
           dbg("fail to load item resource", this.url, error2);
           if (error2 instanceof Error && error2.jqXHR) {
             this.fail(error2.jqXHR, error2.textStatus || "error", error2.errorThrown || error2);
@@ -1983,13 +2075,12 @@ var KViews = (() => {
       return returnView ? view : this;
     }
     /**
-     * Load from a remote API document (format determined by adapter).
-     *
+     * Parse a remote API document into canonical item data.
      * @param {object} data - Raw HTTP response body
-     * @returns {Item} This instance for chaining
+     * @returns {object} Parsed resource data
+     * @private
      */
-    loadFromRemoteDoc(data) {
-      dbg("Load from remote doc", data);
+    _parseRemoteDoc(data) {
       if (this.collection && !this.collection.type) {
         const inferredType = this.adapter.inferItemType(data);
         if (inferredType) {
@@ -1997,11 +2088,97 @@ var KViews = (() => {
         }
       }
       this.adapter.validateItemRemoteDoc(data, { collection: this.collection });
-      const parsedData = this.adapter.parseItemResponse(data, { collection: this.collection });
+      return this.adapter.parseItemResponse(data, { collection: this.collection });
+    }
+    /**
+     * Apply parsed remote data to this item.
+     * @param {object} parsedData
+     * @private
+     */
+    _applyParsedRemoteData(parsedData) {
       Object.assign(this, parsedData);
       if (this.url) {
         this.url = createURL(this.url);
       }
+    }
+    /**
+     * Compare current item state with parsed remote data.
+     * @param {object} parsedData
+     * @returns {boolean}
+     * @private
+     */
+    _remoteDataEquals(parsedData) {
+      if (this.id == null && (!this.attributes || Object.keys(this.attributes).length === 0)) {
+        return false;
+      }
+      if (String(this.id ?? "") !== String(parsedData.id ?? "")) {
+        return false;
+      }
+      if ((this.type ?? null) !== (parsedData.type ?? null)) {
+        return false;
+      }
+      if (!deepEqual(this.attributes ?? {}, parsedData.attributes ?? {})) {
+        return false;
+      }
+      return deepEqual(
+        this._normalizeRelationshipsForCompare(this.relationships),
+        this._normalizeRelationshipsForCompare(parsedData.relationships)
+      );
+    }
+    /**
+     * Normalize relationships to plain comparable objects.
+     * @param {object} relationships
+     * @returns {object}
+     * @private
+     */
+    _normalizeRelationshipsForCompare(relationships) {
+      if (!relationships || typeof relationships !== "object") {
+        return {};
+      }
+      const normalized = {};
+      Object.keys(relationships).sort().forEach((name) => {
+        normalized[name] = this._normalizeRelationshipValueForCompare(relationships[name]);
+      });
+      return normalized;
+    }
+    /**
+     * @param {*} rel
+     * @returns {*}
+     * @private
+     */
+    _normalizeRelationshipValueForCompare(rel) {
+      if (rel == null) {
+        return null;
+      }
+      if (Array.isArray(rel)) {
+        return rel.map((item) => this._normalizeRelationshipValueForCompare(item));
+      }
+      if (typeof rel !== "object") {
+        return rel;
+      }
+      const normalized = {
+        id: rel.id ?? null,
+        type: rel.type ?? null,
+        attributes: rel.attributes ?? {}
+      };
+      if (rel.relationships) {
+        normalized.relationships = this._normalizeRelationshipsForCompare(rel.relationships);
+      }
+      return normalized;
+    }
+    /**
+     * Load from a remote API document (format determined by adapter).
+     *
+     * @param {object} data - Raw HTTP response body
+     * @returns {Item} This instance for chaining
+     */
+    loadFromRemoteDoc(data) {
+      dbg("Load from remote doc", data);
+      const parsedData = this._parseRemoteDoc(data);
+      if (this._remoteDataEquals(parsedData)) {
+        return this;
+      }
+      this._applyParsedRemoteData(parsedData);
       return this;
     }
     /**
@@ -2554,8 +2731,9 @@ var KViews = (() => {
     }
     /**
      * Render the collection view
+     * @private
      */
-    render() {
+    _render() {
       dbg("Render _collectionView", this.collection);
       if (this.collection && this.collection.navtype === "page") {
         this.reset();
@@ -2873,6 +3051,10 @@ var KViews = (() => {
         configurable: true
       });
       let options = Object.assign({}, opts);
+      const explicitListQuery = {
+        pageSize: options.hasOwnProperty("pageSize"),
+        offset: options.hasOwnProperty("offset")
+      };
       Object.assign(this, options);
       if (options.hasOwnProperty("paging") && $(options.paging).length) {
         this.paging = new Paging($(options.paging)[0], this);
@@ -2899,6 +3081,9 @@ var KViews = (() => {
         throw new Error("Invalid navigations type. Should be page or scroll");
       }
       this.adapter = resolveAdapter(opts.adapter);
+      if (this.url) {
+        this._syncListQueryFromUrl(this.url, explicitListQuery);
+      }
       this.storage = opts.hasOwnProperty("storage") ? opts.storage : new Storage(
         (() => {
           const storageOpts = Object.assign({}, opts.ajaxOpts || {});
@@ -3079,10 +3264,31 @@ var KViews = (() => {
           this.deleteUrl = typeof this.deleteUrl == "string" ? createURL(this.deleteUrl) : this.deleteUrl ?? createURL(this.url);
           this.updateUrl = typeof this.updateUrl == "string" ? createURL(this.updateUrl) : this.updateUrl ?? createURL(this.url);
           this.insertUrl = typeof this.insertUrl == "string" ? createURL(this.insertUrl) : this.insertUrl ?? createURL(this.url);
+          if (this.adapter) {
+            this._syncListQueryFromUrl(this.url);
+          }
           break;
       }
       return this;
     }
+    /**
+     * Apply pagination params from URL query string to collection state.
+     * @private
+     * @param {import('./URL.js').URL} url
+     * @param {{ pageSize?: boolean, offset?: boolean }} [explicit] - Options explicitly set at init
+     */
+    _syncListQueryFromUrl(url, explicit = {}) {
+      if (!url || !this.adapter || typeof this.adapter.extractListQueryFromUrl !== "function") {
+        return;
+      }
+      const fromUrl = this.adapter.extractListQueryFromUrl(url, { type: this.type });
+      if (fromUrl.pageSize != null && !explicit.pageSize) {
+        this.setPageSize(fromUrl.pageSize);
+      }
+      if (fromUrl.offset != null && !explicit.offset) {
+        this.offset = fromUrl.offset * 1;
+      }
+    }
     /**
      * Receive remote data
      * 
@@ -3172,7 +3378,7 @@ var KViews = (() => {
         this.loadItem(item);
       });
       if (this.view) {
-        this.view.render();
+        this.view._render();
       } else {
         dbg("collection does not have a view ", this);
       }
@@ -3204,7 +3410,7 @@ var KViews = (() => {
     clear() {
       this.items = [];
       if (this.view) {
-        this.view.render();
+        this.view._render();
       }
       this._trigger("update", this);
       return this;
@@ -3214,7 +3420,7 @@ var KViews = (() => {
      */
     render() {
       if (this.view) {
-        this.view.render();
+        this.view._render();
       }
       this._trigger("afterrender", this);
       return this;
@@ -3235,15 +3441,21 @@ var KViews = (() => {
      * @private
      */
     loadFromDataSource() {
-      const overlay = createOverlay(this);
       let loader = null;
-      if (this.view && this.view.el) {
+      const showLoader = this.showLoader !== false;
+      if (showLoader && this.view && this.view.el) {
+        const overlay = createOverlay(this);
         loader = $(overlay).clone().insertBefore(this.view.el).width($(this.view.el).width()).height($(this.view.el).height());
       }
+      const removeLoader = () => {
+        if (loader) {
+          $(loader).remove();
+        }
+      };
       this._trigger("beforeload", this);
       return new Promise((resolve, reject) => {
         if (!this.url) {
-          loader.remove();
+          removeLoader();
           reject(new Error("No valid URL provided"));
           return;
         }
@@ -3259,9 +3471,7 @@ var KViews = (() => {
           }
           this.receiveRemoteData(res.data);
           this._trigger("load", this);
-          if (loader) {
-            $(loader).remove();
-          }
+          removeLoader();
           if (this.paging) {
             this.paging.render();
           }
@@ -3269,15 +3479,15 @@ var KViews = (() => {
         }).catch((error2) => {
           if (error2 instanceof Error && error2.jqXHR) {
             this.fail(error2.jqXHR, error2.textStatus || "error", error2.errorThrown || error2);
-            loader.remove();
+            removeLoader();
             reject(error2);
           } else if (error2 && error2.jqXHR) {
             this.fail(error2.jqXHR, error2.textStatus, error2.errorThrown);
-            loader.remove();
+            removeLoader();
             reject(error2);
           } else {
             this.fail(null, "error", error2);
-            loader.remove();
+            removeLoader();
             reject(error2);
           }
         });