@logimaxx/kviews.js 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -7,10 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`showLoader`** option on `Item` and `Collection` — set to `false` to skip the loading overlay during `loadFromRemote()` (default: `true`).
+
 ### Changed
 
+- **`Item.loadFromRemote()`** — on an already loaded item, views re-render only when fetched data differs from the current state; the `load` event still fires when the request completes.
+- **`Item.loadFromRemoteDoc()`** — skips updating internal fields when parsed data equals the current item state.
 - npm package name is **`@logimaxx/kviews.js`** (renamed from `@logimaxx/kviews`). Install with `npm install @logimaxx/kviews.js`.
 
+### Fixed
+
+- **`Item.perform_update()`** — failed PATCH requests now reject with the original storage/HTTP error instead of masking it with `ReferenceError: patchData is not defined`.
+
 ## [1.2.1]
 
 ### Changed

package/README.md

@@ -222,7 +222,7 @@ With jQuery, `$.fn.kviews.baseUrl`, `basePath`, and `defaultHeaders` mirror the
 
 ### Collection
 
-- `loadFromRemote()` - Load data from API
+- `loadFromRemote()` - Load data from API (optional loading overlay via `showLoader`, default `true`)
 - `append(itemData)` - Add new item
 - `render()` - Render collection
 - `on(event, callback)` - Event listeners
@@ -230,7 +230,7 @@ With jQuery, `$.fn.kviews.baseUrl`, `basePath`, and `defaultHeaders` mirror the
 
 ### Item
 
-- `loadFromRemote()` - Load item from API
+- `loadFromRemote()` - Load item from API (re-renders only when data changed; optional overlay via `showLoader`)
 - `update(data)` - Update item
 - `delete()` - Delete item
 - `render()` - Render item

package/dist/index.js

@@ -31,6 +31,36 @@ function parseOptions(options) {
   }
   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();
@@ -848,6 +878,29 @@ var JsonApiAdapter = class {
       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.
    *
@@ -1162,6 +1215,32 @@ var PlainRestAdapter = class {
     }
     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]
@@ -1824,17 +1903,26 @@ var Item = class _Item {
    */
   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;
       }
@@ -1842,13 +1930,16 @@ var Item = class _Item {
       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);
@@ -1925,13 +2016,12 @@ var Item = class _Item {
     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) {
@@ -1939,11 +2029,97 @@ var Item = class _Item {
       }
     }
     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;
   }
   /**
@@ -2263,7 +2439,7 @@ var Item = class _Item {
         }
         resolve(this);
       }).catch((error2) => {
-        dbg("Update NOK", this.updateUrl, patchData, error2);
+        dbg("Update NOK", this.updateUrl, payload.body, error2);
         if (error2 instanceof Error && error2.jqXHR) {
           reject(error2);
         } else if (error2.jqXHR) {
@@ -2496,8 +2672,9 @@ var CollectionView = class {
   }
   /**
    * Render the collection view
+   * @private
    */
-  render() {
+  _render() {
     dbg("Render _collectionView", this.collection);
     if (this.collection && this.collection.navtype === "page") {
       this.reset();
@@ -2815,6 +2992,10 @@ var Collection = class {
       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);
@@ -2841,6 +3022,9 @@ var Collection = class {
       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 || {});
@@ -3021,10 +3205,31 @@ var Collection = class {
         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
    * 
@@ -3114,7 +3319,7 @@ var Collection = class {
       this.loadItem(item);
     });
     if (this.view) {
-      this.view.render();
+      this.view._render();
     } else {
       dbg("collection does not have a view ", this);
     }
@@ -3146,7 +3351,7 @@ var Collection = class {
   clear() {
     this.items = [];
     if (this.view) {
-      this.view.render();
+      this.view._render();
     }
     this._trigger("update", this);
     return this;
@@ -3156,7 +3361,7 @@ var Collection = class {
    */
   render() {
     if (this.view) {
-      this.view.render();
+      this.view._render();
     }
     this._trigger("afterrender", this);
     return this;
@@ -3177,15 +3382,21 @@ var Collection = class {
    * @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;
       }
@@ -3201,9 +3412,7 @@ var Collection = class {
         }
         this.receiveRemoteData(res.data);
         this._trigger("load", this);
-        if (loader) {
-          $(loader).remove();
-        }
+        removeLoader();
         if (this.paging) {
           this.paging.render();
         }
@@ -3211,15 +3420,15 @@ var Collection = class {
       }).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);
         }
       });
@@ -4021,6 +4230,7 @@ export {
   createOverlay,
   createURL,
   dbg,
+  deepEqual,
   deepmerge,
   index_default as default,
   error,