vscroll 1.4.3 → 1.4.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Denis Hilt (https://github.com/dhilt)
+Copyright (c) 2022 Denis Hilt (https://github.com/dhilt)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -140,17 +140,18 @@ This obliges the Datasource.get method to deal with _Data_ items and also provid
 A callback that is called every time the Workflow decides that the UI needs to be changed. Its argument is a list of items to be present in the UI. This is a consumer responsibility to detect changes and display them in the UI.
 
 ```js
-run: items => {
-  // assume currentItems contains a list of items currently presented in the UI
-  if (!items.length && !currentItems.length) {
+run: (newItems) => {
+  // assume oldItems contains a list of items that are currently present in the UI
+  if (!newItems.length && !oldItems.length) {
     return;
   }
-  displayNewItemsInsteadCurrentOnes(items, currentItems);
-  currentItems = items;
-}
+  // make newItems to be present in the UI instead of oldItems
+  processItems(newItems, oldItems);
+  oldItems = newItems;
+};
 ```
 
-Each item is an instance of the [Item class](https://github.com/dhilt/vscroll/blob/v1.0.0/src/classes/item.ts) implementing the [Item interface](https://github.com/dhilt/vscroll/blob/v1.0.0/src/interfaces/item.ts), whose props can be used for proper implementation of the `run` callback:
+Each item (in both `newItems` and `oldItems` lists) is an instance of the [Item class](https://github.com/dhilt/vscroll/blob/v1.0.0/src/classes/item.ts) implementing the [Item interface](https://github.com/dhilt/vscroll/blob/v1.0.0/src/interfaces/item.ts), whose props can be used for proper implementation of the `run` callback:
 
 |Name|Type|Description|
 |:--|:--|:----|
@@ -162,19 +163,19 @@ Each item is an instance of the [Item class](https://github.com/dhilt/vscroll/bl
 
 `Run` callback is the most complex and environment-specific part of the `vscroll` API, which is fully depends on the environment for which the consumer is being created. Framework specific consumer should rely on internal mechanism of the framework to provide runtime DOM modifications.
 
-There are some requirements on how the `items` should be processed by `run(items)` call:
- - after the `run(items)` callback is completed, there must be `items.length` elements in the DOM between backward and forward padding elements;
- - old items that are not in the list should be removed from DOM; use `currentItems[].element` reference for this purpose;
- - old items that are in the list should  not be removed and recreated, as it may lead to an unwanted shift of the scroll position; just don't touch them;
- - new items elements should be rendered in accordance with `items[].$index` comparable to `$index` of elements that remain: `$index` must increase continuously and the directions of increase must persist across the `run` calls; Scroller maintains `$index` internally, so you only need to properly inject the `items[].element` into the DOM;
- - new elements should be rendered but not visible, and this should be achieved by "fixed" positioning and "left"/"top" coordinates placing the item element out of view; the Workflow will take care of visibility after calculations; an additional attribute `items[].invisible` can be used to determine if a given element should be hidden;
- - new items elements should have "data-sid" attribute, which value should reflect `items[].$index`;
+There are some requirements on how the items should be processed by `run` call:
+ - after the `run` callback is completed, there must be `newItems.length` elements in the DOM between backward and forward padding elements;
+- old items that are not in the new item list should be removed from DOM; use `oldItems[].element` references for this purpose;
+ - old items that are in the list should not be removed and recreated, as it may lead to an unwanted shift of the scroll position; just don't touch them;
+ - new items elements should be rendered in accordance with `newItems[].$index` comparable to `$index` of elements that remain: `$index` must increase continuously and the directions of increase must persist across the `run` calls; Scroller maintains `$index` internally, so you only need to properly inject a set of `newItems[].element` into the DOM;
+ - new elements should be rendered but not visible, and this should be achieved by "fixed" positioning and "left"/"top" coordinates placing the item element out of view; the Workflow will take care of visibility after calculations; an additional attribute `newItems[].invisible` can be used to determine if a given element should be hidden;
+ - new items elements should have "data-sid" attribute, which value should reflect `newItems[].$index`;
 
 ## Live
 
 This repository has a minimal demonstration of the App-consumer implementation considering all of the requirements listed above: https://dhilt.github.io/vscroll/. This is all-in-one HTML demo with `vscroll` taken from CDN. The source code of the demo is [here](https://github.com/dhilt/vscroll/blob/main/demo/index.html). The approach is rough and non-optimized, if you are seeking for more general solution for native JavaScript applications, please take a look at [vscroll-native](https://github.com/dhilt/vscroll-native) project. It is relatively new and has no good documentation, but its [source code](https://github.com/dhilt/vscroll-native/tree/main/src) and [demo](https://github.com/dhilt/vscroll-native/tree/main/demo) may shed light on `vscroll` usage in no-framework environment.
 
-Another example is [ngx-ui-scroll](https://github.com/dhilt/ngx-ui-scroll). Before 2021 `vscroll` was part of `ngx-ui-scroll`, and its [demo page](https://dhilt.github.io/ngx-ui-scroll/#/) contains well-documented samples that can be used to get an idea on the API and functionality offered by `vscroll`. The code of the [UiScrollComponent](https://github.com/dhilt/ngx-ui-scroll/blob/v2.0.0-rc.1/src/ui-scroll.component.ts) clearly demonstrates the `Workflow` instantiation in the context of Angular. Also, since ngx-ui-scroll is the intermediate layer between `vscroll` and the end Application, the Datasource is being provided from the outside. Method `makeDatasource` is used to provide `Datasource` class to the end Application.
+Another example is [ngx-ui-scroll](https://github.com/dhilt/ngx-ui-scroll). Before 2021 `vscroll` was part of `ngx-ui-scroll`, and its [demo page](https://dhilt.github.io/ngx-ui-scroll/#/) contains well-documented samples that can be used to get an idea on the API and functionality offered by `vscroll`. The code of the [UiScrollComponent](https://github.com/dhilt/ngx-ui-scroll/blob/v2.2.0/src/ui-scroll.component.ts) clearly demonstrates the `Workflow` instantiation in the context of Angular. Also, since ngx-ui-scroll is the intermediate layer between `vscroll` and the end Application, the Datasource is being provided from the outside. Method `makeDatasource` is used to provide `Datasource` class to the end Application.
 
 ## Adapter API
 
@@ -223,4 +224,4 @@ VScroll will receive its own Adapter API documentation later, but for now please
 
  __________
 
-2021 © [Denis Hilt](https://github.com/dhilt)
+2022 © [Denis Hilt](https://github.com/dhilt)

package/dist/bundles/vscroll.esm5.js

@@ -1,6 +1,6 @@
 /**
  * vscroll (https://github.com/dhilt/vscroll) FESM5
- * Version: 1.4.3 (2021-11-30T02:54:00.541Z)
+ * Version: 1.4.4 (2022-01-22T00:43:17.423Z)
  * Author: Denis Hilt
  * License: MIT
  */
@@ -343,7 +343,7 @@ var reactiveConfigStorage = new Map();
 
 var core = {
   name: 'vscroll',
-  version: '1.4.3'
+  version: '1.4.4'
 };
 
 var instanceCount$1 = 0;
@@ -2983,7 +2983,7 @@ var Logger = /** @class */ (function () {
     this.getWorkflowCycleData = function () {
       return settings.instanceIndex + "-" + scroller.state.cycle.count;
     };
-    this.getScrollPosition = function (element) { return scroller.routines.getScrollPosition(element); };
+    this.getScrollPosition = function () { return scroller.routines.getScrollPosition(); };
     this.log(function () {
       return 'vscroll Workflow has been started, ' +
         ("core: " + packageInfo.core.name + " v" + packageInfo.core.version + ", ") +
@@ -3043,7 +3043,7 @@ var Logger = /** @class */ (function () {
   };
   Logger.prototype.prepareForLog = function (data) {
     return data instanceof Event && data.target
-      ? this.getScrollPosition(data.target)
+      ? this.getScrollPosition()
       : data;
   };
   Logger.prototype.logProcess = function (data) {
@@ -3138,64 +3138,63 @@ var Logger = /** @class */ (function () {
 }());
 
 var Routines = /** @class */ (function () {
-  function Routines(settings) {
-    this.horizontal = settings.horizontal;
-    this.window = settings.windowViewport;
-    this.viewport = settings.viewport;
+  function Routines(element, settings) {
+    this.settings = {
+      viewport: settings.viewport,
+      horizontal: settings.horizontal,
+      window: settings.windowViewport
+    };
+    this.element = element;
+    this.viewport = this.getViewportElement();
+    this.onInit(settings);
   }
   Routines.prototype.checkElement = function (element) {
     if (!element) {
       throw new Error('HTML element is not defined');
     }
   };
-  Routines.prototype.getHostElement = function (element) {
-    if (this.window) {
+  Routines.prototype.getViewportElement = function () {
+    if (this.settings.window) {
       return document.documentElement;
     }
-    if (this.viewport) {
-      return this.viewport;
+    if (this.settings.viewport) {
+      return this.settings.viewport;
     }
-    this.checkElement(element);
-    var parent = element.parentElement;
+    this.checkElement(this.element);
+    var parent = this.element.parentElement;
     this.checkElement(parent);
     return parent;
   };
-  Routines.prototype.getScrollEventReceiver = function (element) {
-    if (this.window) {
-      return window;
+  Routines.prototype.onInit = function (settings) {
+    if (settings.windowViewport) {
+      if ('scrollRestoration' in history) {
+        history.scrollRestoration = 'manual';
+      }
     }
-    return this.getHostElement(element);
-  };
-  Routines.prototype.setupScrollRestoration = function () {
-    if ('scrollRestoration' in history) {
-      history.scrollRestoration = 'manual';
+    if (settings.dismissOverflowAnchor) {
+      this.viewport.style.overflowAnchor = 'none';
     }
   };
-  Routines.prototype.dismissOverflowAnchor = function (element) {
-    this.checkElement(element);
-    element.style.overflowAnchor = 'none';
-  };
   Routines.prototype.findElementBySelector = function (element, selector) {
     this.checkElement(element);
     return element.querySelector(selector);
   };
-  Routines.prototype.findPaddingElement = function (element, direction) {
-    return this.findElementBySelector(element, "[data-padding-" + direction + "]");
+  Routines.prototype.findPaddingElement = function (direction) {
+    return this.findElementBySelector(this.element, "[data-padding-" + direction + "]");
   };
-  Routines.prototype.findItemElement = function (element, id) {
-    return this.findElementBySelector(element, "[data-sid=\"" + id + "\"]");
+  Routines.prototype.findItemElement = function (id) {
+    return this.findElementBySelector(this.element, "[data-sid=\"" + id + "\"]");
   };
-  Routines.prototype.getScrollPosition = function (element) {
-    if (this.window) {
-      return window.pageYOffset;
+  Routines.prototype.getScrollPosition = function () {
+    if (this.settings.window) {
+      return this.settings.horizontal ? window.pageXOffset : window.pageYOffset;
     }
-    this.checkElement(element);
-    return element[this.horizontal ? 'scrollLeft' : 'scrollTop'];
+    return this.viewport[this.settings.horizontal ? 'scrollLeft' : 'scrollTop'];
   };
-  Routines.prototype.setScrollPosition = function (element, value) {
+  Routines.prototype.setScrollPosition = function (value) {
     value = Math.max(0, value);
-    if (this.window) {
-      if (this.horizontal) {
+    if (this.settings.window) {
+      if (this.settings.horizontal) {
         window.scrollTo(value, window.scrollY);
       }
       else {
@@ -3203,49 +3202,62 @@ var Routines = /** @class */ (function () {
       }
       return;
     }
-    this.checkElement(element);
-    element[this.horizontal ? 'scrollLeft' : 'scrollTop'] = value;
+    this.viewport[this.settings.horizontal ? 'scrollLeft' : 'scrollTop'] = value;
   };
-  Routines.prototype.getParams = function (element, doNotBind) {
+  Routines.prototype.getElementParams = function (element) {
     this.checkElement(element);
-    if (this.window && doNotBind) {
-      var clientWidth = element.clientWidth, clientHeight = element.clientHeight, clientLeft = element.clientLeft, clientTop = element.clientTop;
-      return {
-        'height': clientHeight,
-        'width': clientWidth,
-        'top': clientTop,
-        'bottom': clientTop + clientHeight,
-        'left': clientLeft,
-        'right': clientLeft + clientWidth,
-        'x': clientLeft,
-        'y': clientTop,
-        'toJSON': function () { return null; },
-      };
-    }
     return element.getBoundingClientRect();
   };
-  Routines.prototype.getSize = function (element, doNotBind) {
-    return this.getParams(element, doNotBind)[this.horizontal ? 'width' : 'height'];
+  Routines.prototype.getWindowParams = function () {
+    var _a = this.viewport, clientWidth = _a.clientWidth, clientHeight = _a.clientHeight, clientLeft = _a.clientLeft, clientTop = _a.clientTop;
+    return {
+      'height': clientHeight,
+      'width': clientWidth,
+      'top': clientTop,
+      'bottom': clientTop + clientHeight,
+      'left': clientLeft,
+      'right': clientLeft + clientWidth,
+      'x': clientLeft,
+      'y': clientTop,
+      'toJSON': function () { return null; },
+    };
+  };
+  Routines.prototype.getSize = function (element) {
+    return this.getElementParams(element)[this.settings.horizontal ? 'width' : 'height'];
+  };
+  Routines.prototype.getScrollerSize = function () {
+    return this.getElementParams(this.element)[this.settings.horizontal ? 'width' : 'height'];
+  };
+  Routines.prototype.getViewportSize = function () {
+    if (this.settings.window) {
+      return this.getWindowParams()[this.settings.horizontal ? 'width' : 'height'];
+    }
+    return this.getSize(this.viewport);
   };
   Routines.prototype.getSizeStyle = function (element) {
     this.checkElement(element);
-    var size = element.style[this.horizontal ? 'width' : 'height'];
+    var size = element.style[this.settings.horizontal ? 'width' : 'height'];
     return parseFloat(size) || 0;
   };
   Routines.prototype.setSizeStyle = function (element, value) {
     this.checkElement(element);
     value = Math.max(0, Math.round(value));
-    element.style[this.horizontal ? 'width' : 'height'] = value + "px";
+    element.style[this.settings.horizontal ? 'width' : 'height'] = value + "px";
   };
-  Routines.prototype.getEdge = function (element, direction, doNotBind) {
-    var params = this.getParams(element, doNotBind);
+  Routines.prototype.getEdge = function (element, direction) {
+    var horizontal = this.settings.horizontal;
+    var params = this.getElementParams(element);
     var isFwd = direction === Direction.forward;
-    return params[isFwd ? (this.horizontal ? 'right' : 'bottom') : (this.horizontal ? 'left' : 'top')];
+    return params[isFwd ? (horizontal ? 'right' : 'bottom') : (horizontal ? 'left' : 'top')];
   };
-  Routines.prototype.getEdge2 = function (element, direction, relativeElement, opposite) {
-    // vertical only ?
-    return element.offsetTop - (relativeElement ? relativeElement.scrollTop : 0) +
-      (direction === (!opposite ? Direction.forward : Direction.backward) ? this.getSize(element) : 0);
+  Routines.prototype.getViewportEdge = function (direction) {
+    var _a = this.settings, window = _a.window, horizontal = _a.horizontal;
+    if (window) {
+      var params = this.getWindowParams();
+      var isFwd = direction === Direction.forward;
+      return params[isFwd ? (horizontal ? 'right' : 'bottom') : (horizontal ? 'left' : 'top')];
+    }
+    return this.getEdge(this.viewport, direction);
   };
   Routines.prototype.makeElementVisible = function (element) {
     this.checkElement(element);
@@ -3257,9 +3269,12 @@ var Routines = /** @class */ (function () {
     this.checkElement(element);
     element.style.display = 'none';
   };
-  Routines.prototype.getOffset = function (element) {
-    this.checkElement(element);
-    return (this.horizontal ? element.offsetLeft : element.offsetTop) || 0;
+  Routines.prototype.getOffset = function () {
+    var _this = this;
+    var get = function (element) {
+      return (_this.settings.horizontal ? element.offsetLeft : element.offsetTop) || 0;
+    };
+    return get(this.element) - (!this.settings.window ? get(this.viewport) : 0);
   };
   Routines.prototype.scrollTo = function (element, argument) {
     this.checkElement(element);
@@ -3273,16 +3288,17 @@ var Routines = /** @class */ (function () {
     var animationFrameId = requestAnimationFrame(function () { return cb(); });
     return function () { return cancelAnimationFrame(animationFrameId); };
   };
-  Routines.prototype.onScroll = function (element, handler) {
-    element.addEventListener('scroll', handler);
-    return function () { return element.removeEventListener('scroll', handler); };
+  Routines.prototype.onScroll = function (handler) {
+    var eventReceiver = this.settings.window ? window : this.viewport;
+    eventReceiver.addEventListener('scroll', handler);
+    return function () { return eventReceiver.removeEventListener('scroll', handler); };
   };
   return Routines;
 }());
 
 var Padding = /** @class */ (function () {
-  function Padding(element, direction, routines) {
-    var found = routines.findPaddingElement(element, direction);
+  function Padding(direction, routines) {
+    var found = routines.findPaddingElement(direction);
     routines.checkElement(found);
     this.element = found;
     this.direction = direction;
@@ -3304,10 +3320,10 @@ var Padding = /** @class */ (function () {
   return Padding;
 }());
 var Paddings = /** @class */ (function () {
-  function Paddings(element, routines, settings) {
+  function Paddings(routines, settings) {
     this.settings = settings;
-    this.forward = new Padding(element, Direction.forward, routines);
-    this.backward = new Padding(element, Direction.backward, routines);
+    this.forward = new Padding(Direction.forward, routines);
+    this.backward = new Padding(Direction.backward, routines);
   }
   Paddings.prototype.byDirection = function (direction, opposite) {
     return direction === Direction.backward
@@ -3359,21 +3375,12 @@ var Paddings = /** @class */ (function () {
 }());
 
 var Viewport = /** @class */ (function () {
-  function Viewport(element, settings, routines, state, logger) {
-    this.element = element;
+  function Viewport(settings, routines, state, logger) {
     this.settings = settings;
     this.routines = routines;
     this.state = state;
     this.logger = logger;
-    this.hostElement = this.routines.getHostElement(this.element);
-    this.scrollEventReceiver = this.routines.getScrollEventReceiver(this.element);
-    if (settings.windowViewport) {
-      this.routines.setupScrollRestoration();
-    }
-    if (settings.dismissOverflowAnchor) {
-      this.routines.dismissOverflowAnchor(this.hostElement);
-    }
-    this.paddings = new Paddings(this.element, this.routines, settings);
+    this.paddings = new Paddings(this.routines, settings);
   }
   Viewport.prototype.reset = function (startIndex) {
     this.setOffset();
@@ -3387,7 +3394,7 @@ var Viewport = /** @class */ (function () {
       this.logger.log(function () { return ['setting scroll position at', value, '[cancelled]']; });
       return value;
     }
-    this.routines.setScrollPosition(this.hostElement, value);
+    this.routines.setScrollPosition(value);
     var position = this.scrollPosition;
     this.logger.log(function () { return __spreadArray([
       'setting scroll position at', position
@@ -3396,7 +3403,7 @@ var Viewport = /** @class */ (function () {
   };
   Object.defineProperty(Viewport.prototype, "scrollPosition", {
     get: function () {
-      return this.routines.getScrollPosition(this.hostElement);
+      return this.routines.getScrollPosition();
     },
     set: function (value) {
       this.setPosition(value);
@@ -3405,10 +3412,10 @@ var Viewport = /** @class */ (function () {
     configurable: true
   });
   Viewport.prototype.getSize = function () {
-    return this.routines.getSize(this.hostElement, true);
+    return this.routines.getViewportSize();
   };
   Viewport.prototype.getScrollableSize = function () {
-    return this.routines.getSize(this.element);
+    return this.routines.getScrollerSize();
   };
   Viewport.prototype.getMaxScrollPosition = function () {
     return this.getScrollableSize() - this.getSize();
@@ -3417,16 +3424,13 @@ var Viewport = /** @class */ (function () {
     return this.getSize() * this.settings.padding;
   };
   Viewport.prototype.getEdge = function (direction) {
-    return this.routines.getEdge(this.hostElement, direction, true);
+    return this.routines.getViewportEdge(direction);
   };
   Viewport.prototype.setOffset = function () {
-    this.offset = this.routines.getOffset(this.element);
-    if (!this.settings.windowViewport) {
-      this.offset -= this.routines.getOffset(this.hostElement);
-    }
+    this.offset = this.routines.getOffset();
   };
   Viewport.prototype.findItemElementById = function (id) {
-    return this.routines.findItemElement(this.element, id);
+    return this.routines.findItemElement(id);
   };
   Viewport.prototype.getEdgeVisibleItem = function (items, direction) {
     var bwd = direction === Direction.backward;
@@ -5124,15 +5128,15 @@ var Scroller = /** @class */ (function () {
       throw new Error(INVALID_DATASOURCE_PREFIX + " " + get.errors[0]);
     }
     var packageInfo = scroller ? scroller.state.packageInfo : { consumer: consumer, core: core };
-    element = scroller ? scroller.viewport.element : element;
+    element = scroller ? scroller.routines.element : element;
     workflow = scroller ? scroller.workflow : workflow;
     this.workflow = workflow;
     this.settings = new Settings(datasource.settings, datasource.devSettings, ++instanceCount);
     this.logger = new Logger(this, packageInfo, datasource.adapter);
-    this.routines = new Routines(this.settings);
+    this.routines = new Routines(element, this.settings);
     this.state = new State(packageInfo, this.settings, scroller ? scroller.state : void 0);
     this.buffer = new Buffer(this.settings, workflow.onDataChanged, this.logger);
-    this.viewport = new Viewport(element, this.settings, this.routines, this.state, this.logger);
+    this.viewport = new Viewport(this.settings, this.routines, this.state, this.logger);
     this.logger.object('vscroll settings object', this.settings, true);
     this.initDatasource(datasource, scroller);
   }
@@ -5427,13 +5431,13 @@ var Workflow = /** @class */ (function () {
       status: ProcessStatus.start
     });
     // set up scroll event listener
-    var _a = this.scroller, scrollEventReceiver = _a.viewport.scrollEventReceiver, routines = _a.routines;
+    var routines = this.scroller.routines;
     var onScrollHandler = function (event) { return _this.callWorkflow({
       process: CommonProcess.scroll,
       status: ProcessStatus.start,
       payload: { event: event }
     }); };
-    this.offScroll = routines.onScroll(scrollEventReceiver, onScrollHandler);
+    this.offScroll = routines.onScroll(onScrollHandler);
   };
   Workflow.prototype.changeItems = function (items) {
     this.propagateChanges(items);