vscroll 1.6.0-beta.1 → 1.6.0-beta.2

package/README.md

@@ -69,7 +69,7 @@ interface WorkflowParams<ItemData> {
   element: HTMLElement;
   datasource: IDatasource<ItemData>;
   run: OnDataChanged<ItemData>;
-  Routines?: CustomRoutinesClass;
+  Routines?: RoutinesClassType;
 }
 ```
 
@@ -153,7 +153,7 @@ For more solid understanding the concept of the Datasource with examples, please
 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: (newItems) => {
+const run = newItems => {
   // assume oldItems contains a list of items that are currently present in the UI
   if (!newItems.length && !oldItems.length) {
     return;
@@ -186,37 +186,49 @@ There are some requirements on how the items should be processed by `run` call:
 
 ### 5. Routines
 
-A special class allowing to override the default behavior related to the DOM. All DOM-specific operations are implemented as the [DOM Routines class](https://github.com/dhilt/vscroll/blob/v1.5.0/src/classes/domRoutines.ts) methods inside core. When the `Routines` class setting is passed among the Workflow arguments, its methods override the base class methods. The Routines methods description can be taken from  the [IRoutines interface](https://github.com/dhilt/vscroll/blob/v1.5.0/src/interfaces/routines.ts) sources. For example, there is a method that throws an error if its argument is not an HTML element:
+A special class allowing to override the default behavior related to the DOM. All DOM-specific operations are implemented as the [DOM Routines class](https://github.com/dhilt/vscroll/blob/v1.5.0/src/classes/domRoutines.ts) methods inside core. When the `Routines` class setting is passed among the Workflow arguments, it replaces the core Routines. The custom Routines class must extend the core class, which can be taken from the VScroll imports:
+
+```js
+import { Routines, Workflow } from 'vscroll';
+
+class CustomRoutines extends Routines { ... }
+
+new Workflow({
+  // consumer, element, datasource, run,
+  Routines: CustomRoutines
+})
+```
+
+The Routines methods description can be taken from the [IRoutines interface](https://github.com/dhilt/vscroll/blob/v1.5.0/src/interfaces/routines.ts) sources. For example, there is a method that calculates the scroller's offset:
 
 ```typescript
-checkElement(element: HTMLElement): void {
-  if (!element) {
-    throw new Error('HTML element is not defined');
-  }
+getOffset(): number {
+  const get = (element: HTMLElement) =>
+    (this.settings.horizontal ? element.offsetLeft : element.offsetTop) || 0;
+  return get(this.element) - (!this.settings.window ? get(this.viewport) : 0);
 }
 ```
 
-With the `Routines` class setting it can be overridden as follows:
+If we have a table layout case where we need to specify the offset of the table header, the base method can be overridden as follows:
 
 ```js
-new Workflow({ 
-  consumer, element, datasource, run,
-  Routines: class {
-    checkElement(element) {
-      if (!element || typeof element.querySelector !== 'function') {
-        throw new Error('Fatal: expecting HTML element');
-      }
+new Workflow({
+  // consumer, element, datasource, run,
+  Routines: class extends Routines {
+    getOffset(element) {
+      return document.querySelector('#viewport thead')?.offsetHeight || 0;
     }
   }
 });
 ```
 
-Another example is the table layout case where we need to specify the offset of the table header:
+It's worth noting that thanks to the extending, we can use parent methods and have access to the correct context after the engine instantiates the Routines:
 
 ```js
-const Routines = class {
-  getOffset() {
-    return document.querySelector('#viewport thead')?.offsetHeight || 0;
+class CustomRoutines extends Routines {
+  onInit(...args) {
+    console.log('Routines settings:', this.settings);
+    super.onInit(...args);
   }
 }
 ```

package/dist/bundles/vscroll.esm5.js

@@ -1,6 +1,6 @@
 /**
  * vscroll (https://github.com/dhilt/vscroll) FESM5
- * Version: 1.6.0-beta.1 (2023-11-26T02:11:26.673Z)
+ * Version: 1.6.0-beta.2 (2023-12-02T15:09:23.845Z)
  * Author: Denis Hilt
  * License: MIT
  */
@@ -345,7 +345,7 @@ var reactiveConfigStorage = new Map();
 
 var core = {
   name: 'vscroll',
-  version: '1.6.0-beta.1'
+  version: '1.6.0-beta.2'
 };
 
 var getBox = function (id) {
@@ -554,14 +554,14 @@ var onBoolean = function (value) {
 };
 var onObject = function (value) {
   var errors = [];
-  if (Object.prototype.toString.call(value) !== '[object Object]') {
+  if (!value || Object.prototype.toString.call(value) !== '[object Object]') {
     errors.push(ValidatorType.object);
   }
   return { value: value, isSet: true, isValid: !errors.length, errors: errors };
 };
 var onHtmlElement = function (value) {
   var errors = [];
-  if (!(value instanceof Element) && !(value instanceof HTMLDocument)) {
+  if (!(value instanceof Element) && !(value instanceof Document)) {
     errors.push(ValidatorType.element);
   }
   return { value: value, isSet: true, isValid: !errors.length, errors: errors };
@@ -854,29 +854,29 @@ var validate = function (context, params) {
   return data;
 };
 
-var _a$3;
-var OBJECT$1 = VALIDATORS.OBJECT, FUNC_WITH_X_AND_MORE_ARGUMENTS$1 = VALIDATORS.FUNC_WITH_X_AND_MORE_ARGUMENTS;
+var _a$4;
+var OBJECT$2 = VALIDATORS.OBJECT, FUNC_WITH_X_AND_MORE_ARGUMENTS$1 = VALIDATORS.FUNC_WITH_X_AND_MORE_ARGUMENTS;
 var DatasourceProps;
 (function (DatasourceProps) {
   DatasourceProps["get"] = "get";
   DatasourceProps["settings"] = "settings";
   DatasourceProps["devSettings"] = "devSettings";
 })(DatasourceProps || (DatasourceProps = {}));
-var DATASOURCE = (_a$3 = {},
-  _a$3[DatasourceProps.get] = {
+var DATASOURCE = (_a$4 = {},
+  _a$4[DatasourceProps.get] = {
     validators: [FUNC_WITH_X_AND_MORE_ARGUMENTS$1(2)],
     mandatory: true
   },
-  _a$3[DatasourceProps.settings] = {
-    validators: [OBJECT$1]
+  _a$4[DatasourceProps.settings] = {
+    validators: [OBJECT$2]
   },
-  _a$3[DatasourceProps.devSettings] = {
-    validators: [OBJECT$1]
+  _a$4[DatasourceProps.devSettings] = {
+    validators: [OBJECT$2]
   },
-  _a$3);
+  _a$4);
 
-var _a$2, _b$2, _c$1;
-var NUMBER = VALIDATORS.NUMBER, INTEGER$1 = VALIDATORS.INTEGER, INTEGER_UNLIMITED$1 = VALIDATORS.INTEGER_UNLIMITED, MORE_OR_EQUAL = VALIDATORS.MORE_OR_EQUAL, BOOLEAN$1 = VALIDATORS.BOOLEAN, ELEMENT = VALIDATORS.ELEMENT, FUNC = VALIDATORS.FUNC, OR$1 = VALIDATORS.OR, ENUM = VALIDATORS.ENUM;
+var _a$3, _b$2, _c$1;
+var NUMBER = VALIDATORS.NUMBER, INTEGER$1 = VALIDATORS.INTEGER, INTEGER_UNLIMITED$1 = VALIDATORS.INTEGER_UNLIMITED, MORE_OR_EQUAL = VALIDATORS.MORE_OR_EQUAL, BOOLEAN$1 = VALIDATORS.BOOLEAN, ELEMENT$1 = VALIDATORS.ELEMENT, FUNC$1 = VALIDATORS.FUNC, OR$1 = VALIDATORS.OR, ENUM = VALIDATORS.ENUM;
 var Settings$1;
 (function (Settings) {
   Settings["adapter"] = "adapter";
@@ -908,14 +908,14 @@ var DevSettings;
   DevSettings["dismissOverflowAnchor"] = "dismissOverflowAnchor";
   DevSettings["directionPriority"] = "directionPriority";
 })(DevSettings || (DevSettings = {}));
-var MIN = (_a$2 = {},
-  _a$2[Settings$1.itemSize] = 1,
-  _a$2[Settings$1.bufferSize] = 1,
-  _a$2[Settings$1.padding] = 0.01,
-  _a$2[DevSettings.throttle] = 0,
-  _a$2[DevSettings.initDelay] = 0,
-  _a$2[DevSettings.initWindowDelay] = 0,
-  _a$2);
+var MIN = (_a$3 = {},
+  _a$3[Settings$1.itemSize] = 1,
+  _a$3[Settings$1.bufferSize] = 1,
+  _a$3[Settings$1.padding] = 0.01,
+  _a$3[DevSettings.throttle] = 0,
+  _a$3[DevSettings.initDelay] = 0,
+  _a$3[DevSettings.initWindowDelay] = 0,
+  _a$3);
 var SETTINGS = (_b$2 = {},
   _b$2[Settings$1.adapter] = {
     validators: [BOOLEAN$1],
@@ -958,7 +958,7 @@ var SETTINGS = (_b$2 = {},
     defaultValue: false
   },
   _b$2[Settings$1.viewportElement] = {
-    validators: [OR$1([ELEMENT, FUNC])],
+    validators: [OR$1([ELEMENT$1, FUNC$1])],
     defaultValue: null
   },
   _b$2[Settings$1.inverse] = {
@@ -966,7 +966,7 @@ var SETTINGS = (_b$2 = {},
     defaultValue: false
   },
   _b$2[Settings$1.onBeforeClip] = {
-    validators: [FUNC],
+    validators: [FUNC$1],
     defaultValue: null
   },
   _b$2[Settings$1.sizeStrategy] = {
@@ -1057,23 +1057,23 @@ var ProcessStatus;
   ProcessStatus["error"] = "error";
 })(ProcessStatus || (ProcessStatus = {}));
 
-var _a$1, _b$1, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
-var INTEGER = VALIDATORS.INTEGER, INTEGER_UNLIMITED = VALIDATORS.INTEGER_UNLIMITED, BOOLEAN = VALIDATORS.BOOLEAN, OBJECT = VALIDATORS.OBJECT, ITEM_LIST = VALIDATORS.ITEM_LIST, FUNC_WITH_X_ARGUMENTS = VALIDATORS.FUNC_WITH_X_ARGUMENTS, FUNC_WITH_X_AND_MORE_ARGUMENTS = VALIDATORS.FUNC_WITH_X_AND_MORE_ARGUMENTS, FUNC_WITH_X_TO_Y_ARGUMENTS = VALIDATORS.FUNC_WITH_X_TO_Y_ARGUMENTS, ONE_OF_MUST = VALIDATORS.ONE_OF_MUST, ONE_OF_CAN = VALIDATORS.ONE_OF_CAN, OR = VALIDATORS.OR;
+var _a$2, _b$1, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+var INTEGER = VALIDATORS.INTEGER, INTEGER_UNLIMITED = VALIDATORS.INTEGER_UNLIMITED, BOOLEAN = VALIDATORS.BOOLEAN, OBJECT$1 = VALIDATORS.OBJECT, ITEM_LIST = VALIDATORS.ITEM_LIST, FUNC_WITH_X_ARGUMENTS$1 = VALIDATORS.FUNC_WITH_X_ARGUMENTS, FUNC_WITH_X_AND_MORE_ARGUMENTS = VALIDATORS.FUNC_WITH_X_AND_MORE_ARGUMENTS, FUNC_WITH_X_TO_Y_ARGUMENTS = VALIDATORS.FUNC_WITH_X_TO_Y_ARGUMENTS, ONE_OF_MUST = VALIDATORS.ONE_OF_MUST, ONE_OF_CAN = VALIDATORS.ONE_OF_CAN, OR = VALIDATORS.OR;
 var AdapterNoParams;
 (function (AdapterNoParams) {
 })(AdapterNoParams || (AdapterNoParams = {}));
 var NO_METHOD_PARAMS = {};
-var RESET_METHOD_PARAMS = (_a$1 = {},
-  _a$1[DatasourceProps.get] = {
+var RESET_METHOD_PARAMS = (_a$2 = {},
+  _a$2[DatasourceProps.get] = {
     validators: [FUNC_WITH_X_AND_MORE_ARGUMENTS(2)]
   },
-  _a$1[DatasourceProps.settings] = {
-    validators: [OBJECT]
+  _a$2[DatasourceProps.settings] = {
+    validators: [OBJECT$1]
   },
-  _a$1[DatasourceProps.devSettings] = {
-    validators: [OBJECT]
+  _a$2[DatasourceProps.devSettings] = {
+    validators: [OBJECT$1]
   },
-  _a$1);
+  _a$2);
 var AdapterReloadParams;
 (function (AdapterReloadParams) {
   AdapterReloadParams["reloadIndex"] = "reloadIndex";
@@ -1131,7 +1131,7 @@ var AdapterRemoveParams;
 })(AdapterRemoveParams || (AdapterRemoveParams = {}));
 var REMOVE_METHOD_PARAMS = (_e = {},
   _e[AdapterRemoveParams.predicate] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1), ONE_OF_MUST([AdapterRemoveParams.indexes])]
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1), ONE_OF_MUST([AdapterRemoveParams.indexes])]
   },
   _e[AdapterRemoveParams.indexes] = {
     validators: [ITEM_LIST, ONE_OF_MUST([AdapterRemoveParams.predicate])]
@@ -1171,12 +1171,12 @@ var INSERT_METHOD_PARAMS = (_g = {},
     mandatory: true
   },
   _g[AdapterInsertParams.before] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1), ONE_OF_MUST([
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1), ONE_OF_MUST([
         AdapterInsertParams.after, AdapterInsertParams.beforeIndex, AdapterInsertParams.afterIndex
       ])]
   },
   _g[AdapterInsertParams.after] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1), ONE_OF_MUST([
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1), ONE_OF_MUST([
         AdapterInsertParams.before, AdapterInsertParams.beforeIndex, AdapterInsertParams.afterIndex
       ])]
   },
@@ -1207,7 +1207,7 @@ var REPLACE_METHOD_PARAMS = (_h = {},
     mandatory: true
   },
   _h[AdapterReplaceParams.predicate] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1)],
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1)],
     mandatory: true
   },
   _h[AdapterReplaceParams.fixRight] = {
@@ -1222,7 +1222,7 @@ var AdapterUpdateParams;
 })(AdapterUpdateParams || (AdapterUpdateParams = {}));
 var UPDATE_METHOD_PARAMS = (_j = {},
   _j[AdapterUpdateParams.predicate] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1)],
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1)],
     mandatory: true
   },
   _j[AdapterUpdateParams.fixRight] = {
@@ -1253,10 +1253,10 @@ var FIX_METHOD_PARAMS = (_k = {},
     validators: [FUNC_WITH_X_TO_Y_ARGUMENTS(1, 2)]
   },
   _k[AdapterFixParams.scrollToItem] = {
-    validators: [FUNC_WITH_X_ARGUMENTS(1)]
+    validators: [FUNC_WITH_X_ARGUMENTS$1(1)]
   },
   _k[AdapterFixParams.scrollToItemOpt] = {
-    validators: [OR([BOOLEAN, OBJECT])]
+    validators: [OR([BOOLEAN, OBJECT$1])]
   },
   _k);
 var AdapterMethods = (_l = {},
@@ -1286,6 +1286,37 @@ var ADAPTER_METHODS = (_m = {},
   _m[AdapterProcess.fix] = FIX_METHOD_PARAMS,
   _m);
 
+var _a$1;
+var ELEMENT = VALIDATORS.ELEMENT, OBJECT = VALIDATORS.OBJECT, FUNC = VALIDATORS.FUNC, FUNC_WITH_X_ARGUMENTS = VALIDATORS.FUNC_WITH_X_ARGUMENTS;
+var WorkflowProps;
+(function (WorkflowProps) {
+  WorkflowProps["consumer"] = "consumer";
+  WorkflowProps["element"] = "element";
+  WorkflowProps["datasource"] = "datasource";
+  WorkflowProps["run"] = "run";
+  WorkflowProps["Routines"] = "Routines";
+})(WorkflowProps || (WorkflowProps = {}));
+var WORKFLOW = (_a$1 = {},
+  _a$1[WorkflowProps.consumer] = {
+    validators: [OBJECT]
+  },
+  _a$1[WorkflowProps.element] = {
+    validators: [ELEMENT],
+    mandatory: true
+  },
+  _a$1[WorkflowProps.datasource] = {
+    validators: [OBJECT],
+    mandatory: true
+  },
+  _a$1[WorkflowProps.run] = {
+    validators: [FUNC_WITH_X_ARGUMENTS(1)],
+    mandatory: true
+  },
+  _a$1[WorkflowProps.Routines] = {
+    validators: [FUNC]
+  },
+  _a$1);
+
 var Settings = /** @class */ (function () {
   function Settings(settings, devSettings, instanceIndex) {
     this.parseInput(settings, SETTINGS);
@@ -2536,7 +2567,7 @@ var Render = /** @class */ (function (_super) {
     return _super !== null && _super.apply(this, arguments) || this;
   }
   Render.run = function (scroller) {
-    var workflow = scroller.workflow, _a = scroller.state, cycle = _a.cycle, render = _a.render, scroll = _a.scroll, viewport = scroller.viewport, routines = scroller.routines;
+    var workflow = scroller.workflow, _a = scroller.state, cycle = _a.cycle, render = _a.render, scroll = _a.scroll, fetch = _a.fetch, viewport = scroller.viewport, routines = scroller.routines;
     scroller.logger.stat('before new items render');
     if (scroll.positionBeforeAsync === null) {
       scroll.positionBeforeAsync = viewport.scrollPosition;
@@ -2557,7 +2588,7 @@ var Render = /** @class */ (function (_super) {
           payload: { error: 'Can\'t associate item with element' }
         });
       }
-    });
+    }, { items: fetch.items.map(function (i) { return i.get(); }) });
   };
   Render.doRender = function (scroller) {
     var _a = scroller.state, fetch = _a.fetch, render = _a.render, viewport = scroller.viewport, buffer = scroller.buffer, logger = scroller.logger;
@@ -3187,7 +3218,7 @@ var Routines = /** @class */ (function () {
     return parent;
   };
   Routines.prototype.onInit = function (settings) {
-    console.log('routines on-init');
+    console.log('routines on-init (original)');
     if (settings.windowViewport) {
       if ('scrollRestoration' in history) {
         history.scrollRestoration = 'manual';
@@ -3207,6 +3238,9 @@ var Routines = /** @class */ (function () {
   Routines.prototype.findItemElement = function (id) {
     return this.findElementBySelector(this.element, "[data-sid=\"".concat(id, "\"]"));
   };
+  Routines.prototype.findItemChildBySelector = function (id, selector) {
+    return this.findElementBySelector(this.element, "[data-sid=\"".concat(id, "\"] ").concat(selector));
+  };
   Routines.prototype.getScrollPosition = function () {
     if (this.settings.window) {
       return this.settings.horizontal ? window.pageXOffset : window.pageYOffset;
@@ -3302,7 +3336,8 @@ var Routines = /** @class */ (function () {
     this.checkElement(element);
     element.scrollIntoView(argument);
   };
-  Routines.prototype.render = function (cb) {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  Routines.prototype.render = function (cb, params) {
     var timeoutId = setTimeout(function () { return cb(); });
     return function () { return clearTimeout(timeoutId); };
   };
@@ -5195,6 +5230,23 @@ var Scroller = /** @class */ (function () {
     var packageInfo = scroller ? scroller.state.packageInfo : { consumer: consumer, core: core };
     element = scroller ? scroller.routines.element : element;
     workflow = scroller ? scroller.workflow : workflow;
+    // In general, custom Routines must extend the original Routines. If not, we provide implicit extending.
+    // This is undocumented feature. It should be removed in vscroll v2.
+    if (CustomRoutines && !(CustomRoutines.prototype instanceof Routines)) {
+      var __Routines_1 = /** @class */ (function (_super) {
+        __extends(__Routines, _super);
+        function __Routines() {
+          return _super !== null && _super.apply(this, arguments) || this;
+        }
+        return __Routines;
+      }(Routines));
+      Object.getOwnPropertyNames(CustomRoutines.prototype)
+        .filter(function (method) { return method !== 'constructor'; })
+        .forEach(function (method) {
+        return __Routines_1.prototype[method] = CustomRoutines === null || CustomRoutines === void 0 ? void 0 : CustomRoutines.prototype[method];
+      });
+      CustomRoutines = __Routines_1;
+    }
     this.workflow = workflow;
     this.settings = new Settings(datasource.settings, datasource.devSettings, ++instanceCount);
     this.logger = new Logger(this, packageInfo, datasource.adapter);
@@ -5467,9 +5519,13 @@ var runStateMachine = function (_a) {
 };
 
 var Workflow = /** @class */ (function () {
-  function Workflow(_a) {
-    var element = _a.element, datasource = _a.datasource, consumer = _a.consumer, run = _a.run, Routines = _a.Routines;
+  function Workflow(params) {
     var _this = this;
+    var element = params.element, datasource = params.datasource, consumer = params.consumer, run = params.run, Routines = params.Routines;
+    var validationResult = validate(params, WORKFLOW);
+    if (!validationResult.isValid) {
+      throw new Error("Invalid Workflow params: ".concat(validationResult.errors.join(', '), "."));
+    }
     this.isInitialized = false;
     this.disposed = false;
     this.initTimer = null;