vscroll - npm Package Compare versions

Comparing version 1.0.0-rc.8 to 1.0.0

dist/esm2015/index.js

@@ -5,7 +5,6 @@ import { Workflow } from './workflow';
 import { INVALID_DATASOURCE_PREFIX } from './scroller';
-import { Item } from './classes/item';
 import { AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps } from './classes/adapter/props';
 import { Direction } from './inputs/index';
 // export entities
-export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, Item, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
+export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
 //# sourceMappingURL=index.js.map

dist/esm2015/version.js

 export default {
   name: 'vscroll',
-  version: '1.0.0-rc.8'
+  version: '1.0.0'
 };
 //# sourceMappingURL=version.js.map

dist/esm5/index.js

@@ -5,7 +5,6 @@ import { Workflow } from './workflow';
 import { INVALID_DATASOURCE_PREFIX } from './scroller';
-import { Item } from './classes/item';
 import { AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps } from './classes/adapter/props';
 import { Direction } from './inputs/index';
 // export entities
-export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, Item, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
+export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
 //# sourceMappingURL=index.js.map

dist/esm5/version.js

 export default {
   name: 'vscroll',
-  version: '1.0.0-rc.8'
+  version: '1.0.0'
 };
 //# sourceMappingURL=version.js.map

dist/typings/classes/item.d.ts

 import { Routines } from './domRoutines';
 import { Direction } from '../inputs/index';
-import { ItemAdapter } from '../interfaces/index';
-export declare class Item<Data = unknown> {
+import { Item as _Item, ItemAdapter } from '../interfaces/index';
+export declare class Item<Data = unknown> implements _Item<Data> {
   nodeId: string;
@@ -6,0 +6,0 @@ routines: Routines;

dist/typings/index.d.ts

@@ -5,7 +5,6 @@ import { Workflow } from './workflow';
 import { INVALID_DATASOURCE_PREFIX } from './scroller';
-import { Item } from './classes/item';
 import { AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps } from './classes/adapter/props';
 import { Direction } from './inputs/index';
-import { IDatasource, IDatasourceConstructed, IReactivePropConfig, IAdapterConfig, ItemAdapter, IAdapter } from './interfaces/index';
-export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, Item, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
-export { IDatasource, IDatasourceConstructed, IReactivePropConfig, IAdapterConfig, ItemAdapter as IAdapterItem, IAdapter, };
+import { IDatasource, IDatasourceConstructed, IReactivePropConfig, IAdapterConfig, ItemAdapter, IAdapter, Item } from './interfaces/index';
+export { Workflow, makeDatasource, packageInfo, INVALID_DATASOURCE_PREFIX, AdapterPropName, EMPTY_ITEM, getDefaultAdapterProps, Direction, };
+export { IDatasource, IDatasourceConstructed, IReactivePropConfig, IAdapterConfig, ItemAdapter as IAdapterItem, IAdapter, Item, };

dist/typings/interfaces/index.d.ts

 import { ObservableLike, DatasourceGet, IDatasourceOptional, IDatasource, IDatasourceConstructed } from './datasource';
 import { OnDataChanged, WorkflowParams, ScrollerWorkflow, ScrollerParams, WorkflowGetter, WorkflowError, InterruptParams, StateMachineMethods, StateMachineParams } from './workflow';
+import { Item } from './item';
 import { IReactivePropConfig, IReactivePropsConfig, IReactivePropsStore, IAdapterConfig, IAdapterProp, ItemAdapter, ItemsPredicate, ItemsUpdater, ItemsProcessor, BufferUpdater, IPackage, IPackages, IBufferInfo, IAdapterInput, AdapterAppendOptions, AdapterPrependOptions, AdapterRemoveOptions, AdapterClipOptions, AdapterInsertOptions, AdapterReplaceOptions, AdapterUpdateOptions, AdapterFixOptions, AdapterMethodResult, IAdapter } from './adapter';
@@ -8,2 +9,2 @@ import { Settings, DevSettings } from './settings';
 import { ValidatedValue, IValidator, ICommonProp, ICommonProps, IValidatedCommonProps, IValidatedData } from './validation';
-export { ObservableLike, DatasourceGet, IDatasourceOptional, IDatasource, IDatasourceConstructed, OnDataChanged, WorkflowParams, ScrollerWorkflow, ScrollerParams, WorkflowGetter, WorkflowError, InterruptParams, StateMachineMethods, StateMachineParams, IReactivePropConfig, IReactivePropsConfig, IReactivePropsStore, IAdapterConfig, IAdapterProp, ItemAdapter, AdapterMethodResult, IAdapter, ItemsPredicate, ItemsUpdater, ItemsProcessor, BufferUpdater, IPackage, IPackages, IBufferInfo, IAdapterInput, AdapterAppendOptions, AdapterPrependOptions, AdapterRemoveOptions, AdapterClipOptions, AdapterInsertOptions, AdapterReplaceOptions, AdapterUpdateOptions, AdapterFixOptions, Settings, DevSettings, ScrollEventData, ScrollState, State, ProcessName, ProcessClass, ProcessPayload, ProcessSubject, AdapterProcessMap, IBaseProcess, IBaseAdapterProcess, ValidatedValue, IValidator, ICommonProp, ICommonProps, IValidatedCommonProps, IValidatedData, };
+export { ObservableLike, DatasourceGet, IDatasourceOptional, IDatasource, IDatasourceConstructed, OnDataChanged, WorkflowParams, ScrollerWorkflow, ScrollerParams, WorkflowGetter, WorkflowError, InterruptParams, StateMachineMethods, StateMachineParams, Item, IReactivePropConfig, IReactivePropsConfig, IReactivePropsStore, IAdapterConfig, IAdapterProp, ItemAdapter, AdapterMethodResult, IAdapter, ItemsPredicate, ItemsUpdater, ItemsProcessor, BufferUpdater, IPackage, IPackages, IBufferInfo, IAdapterInput, AdapterAppendOptions, AdapterPrependOptions, AdapterRemoveOptions, AdapterClipOptions, AdapterInsertOptions, AdapterReplaceOptions, AdapterUpdateOptions, AdapterFixOptions, Settings, DevSettings, ScrollEventData, ScrollState, State, ProcessName, ProcessClass, ProcessPayload, ProcessSubject, AdapterProcessMap, IBaseProcess, IBaseAdapterProcess, ValidatedValue, IValidator, ICommonProp, ICommonProps, IValidatedCommonProps, IValidatedData, };

package.json

 {
   "name": "vscroll",
-  "version": "1.0.0-rc.8",
+  "version": "1.0.0",
   "description": "Virtual scroll engine",
@@ -31,3 +31,4 @@ "main": "dist/bundles/vscroll.umd.js",
     "test": "npm run lint && npm run jest",
-    "prepare": "npm run test && npm run build"
+    "prepublishOnly": "npm run test",
+    "prepack": "npm run build"
   },
@@ -34,0 +35,0 @@ "dependencies": {

README.md

@@ -58,3 +58,3 @@ [![Build Status](https://travis-ci.com/dhilt/vscroll.svg?branch=main)](https://travis-ci.com/dhilt/vscroll)
 
-This is a simple data object that provides information about a consumer. It is not critical to omit this, but if the result solution is going to be published as a separate 3d-party library ("consumer"), the name and the version of the result package should be passed as follows:
+A simple data object that provides information about a consumer. It is not critical to omit this, but if the result solution is going to be published as a separate 3d-party library ("consumer"), the name and the version of the result package should be passed as follows:
 
@@ -76,3 +76,3 @@ ```js
 
-It should be wrapped with another container with constrained height and overflow scroll/auto. And it also must have two special padding elements marked with special attributes for the virtualization purpose.
+This element should be wrapped with another container with constrained height and overflow scroll/auto. And it also must have two special padding elements marked with special attributes for the virtualization purpose.
 
@@ -123,6 +123,21 @@ ```html
 
-This option also makes the [Adapter API](#adapter-api) available via `datasource.adapter` property. It provides massive functionality to assess and manipulate data at runtime the VScroll engine deals with. 
+This option also makes the [Adapter API](#adapter-api) available via `datasource.adapter` property after the Datasource is instantiated. It provides massive functionality to assess and manipulate Scroller's data at runtime.
 
-### Run
+Using TypeScript, the above example should be written as follows:
 
+```typescript
+interface Data {
+  id: number;
+  text: string;
+  ...
+}
+
+const Datasource = VScroll.makeDatasource();
+const datasource = new Datasource<Data>(...);
+```
+
+This obliges the Datasource.get method to deal with _Data_ items and also provides strong typing for Adapter API props and methods.
+
+### 4. Run
+
 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.
@@ -132,6 +147,7 @@
 run: items => {
+  // assume currentItems contains a list of items currently presented in the UI
   if (!items.length && !currentItems.length) {
     return;
   }
-  displayNewItemsOverTheOldOnes(items, currentItems);
+  displayNewItemsInsteadCurrentOnes(items, currentItems);
   currentItems = items;
@@ -141,12 +157,21 @@ }
 
-This is the most complex and environment-specific part of the `vscroll` API. Its implementation 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.
+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:
 
-There are some requirements on how new items should be processed by `run` callback:
- - as the result of the `run` callback invocation, 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 reference to DOM element for this purpose: `currentItems[].element`;
+|Name|Type|Description|
+|:--|:--|:----|
+|element|_HTMLElement_|HTML element associated with the item|
+|$index|_number_|Integer index of the item in the Datasource. Correlates with the first argument of the Datasource.get method|
+|data|_Data_|Data (contents) of the item. This is what the Datasource.get passes to the Scroller via success-callback as an array of data-items typed as Data[]|
+|invisible|_boolean_|A flag that determines whether the item should be hidden (if _true_) or visible (if _false_) when the _run_ method is called|
+|get|_()&nbsp;=>&nbsp;ItemAdapter&lt;Data&gt;_|A shortcut method returning { element, $index, data } object|
+
+`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 from top to bottom;
- - new items elements should have "data-sid" attribute, which value should be taken from `items[].nodeId`;
+ - 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;
- - `items[].data` contains data that the Datasource passes to Scroller via `get` API; this data should be used during new items templating.
+ - new items elements should have "data-sid" attribute, which value should reflect `items[].$index`;
 
@@ -157,26 +182,27 @@ ## Live
 
-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`.
+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.
 
-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.
-
 ## Adapter API
 
-Adapter API is a powerful feature of the `vscroll` engine. Please refer to the ngx-ui-scroll [Adapter API doc](https://github.com/dhilt/ngx-ui-scroll#adapter-api) as it can be applied to `vscroll` direct usage with only one important difference: all RxJs entities replace tiny custom [Reactive](https://github.com/dhilt/vscroll/blob/main/src/classes/reactive.ts) ones. It means, for example, `eof$` has no "subscribe" method, but "on":
+Adapter API is a powerful feature of the `vscroll` engine. Please refer to ngx-ui-scroll [Adapter API doc](https://github.com/dhilt/ngx-ui-scroll#adapter-api) as it can be applied to `vscroll` case with only one important difference: vscroll does not have RxJs entities, it has [Reactive](https://github.com/dhilt/vscroll/blob/main/src/classes/reactive.ts) ones instead. It means, for example, `eof$` has no "subscribe" method, but "on":
 
 ```js
-myDatasource.adapter.bof$.on(value => {
-  if (value) {
-    console.log('Begin of file has been reached');
-  }
-})
+// ngx-ui-scroll
+myDatasource.adapter.bof$.subscribe(value =>
+  value && console.log('Begin of file is reached')
+);
+// vscroll
+myDatasource.adapter.bof$.on(value =>
+  value && console.log('Begin of file is reached')
+);
 ```
 
-Adapter API becomes available as `Datasource.adapter` property after the Datasource is instantiated via operator "new". In terms of "vscroll" you need to get a Datasource class by calling `makeDatasource` method, then you can instantiate it. `makeDatasource` accepts 1 argument, which is an Adapter custom configuration. Currently this config can only be used to redefine the just mentioned Adapter reactive props. Here's an example of how simple Reactive props can be overridden with RxJs Subject and BehaviorSubject entities: [ui-scroll.datasource.ts](https://github.com/dhilt/ngx-ui-scroll/blob/v2.0.0-rc.1/src/ui-scroll.datasource.ts). 
+Adapter API becomes available as `Datasource.adapter` property after the Datasource is instantiated via operator "new". In terms of "vscroll" you need to get a Datasource class by calling `makeDatasource` method, then you can instantiate it. `makeDatasource` accepts 1 argument, which is an Adapter custom configuration. Currently this config can only be used to redefine the just mentioned Adapter reactive props. Here's an example of how simple Reactive props can be overridden with RxJs Subject and BehaviorSubject entities: [ui-scroll.datasource.ts](https://github.com/dhilt/ngx-ui-scroll/blob/v2.0.0-rc.10/src/ui-scroll.datasource.ts). 
 
-An important note is that the Adapter getting ready breaks onto 2 parts: instantiation (which is synchronous with the Datasource instantiation) and initialization (which occurs during the Workflow, which is asynchronous to the Datasource instantiating). Adapter gets all necessary props and methods during the first phase, but this starts work only when the second phase is done. Practically this means 
+An important note is that the Adapter getting ready breaks onto 2 parts: instantiation (which is synchronous with the Datasource instantiation) and initialization (which occurs during the Workflow instantiating). Adapter gets all necessary props and methods during the first phase, but this starts work only when the second phase is done. Practically this means 
  - you may arrange any Adapter reactive subscriptions in your app/consumer right after the Datasource is instantiated, 
  - some of the initial (default) values can be unusable, like `Adapter.bufferInfo.minIndex` = NaN (because Scroller's Buffer is empty before the very first `Datasource.get` call),
- - Adapter methods do nothing when called before phase 2, they immediately resolve some default "good" value (`{ immediately: true, success: true, ... }`).
+ - Adapter methods do nothing when called before phase 2, they immediately resolve some default "good" value (`{ immediate: true, success: true, ... }`).
 
-If there is some logic that could potentially run before Adapter initialization and you don't want this to happen, the following approach can be applied:
+If there is some logic that could potentially run before the Adapter initialization and you don't want this to happen, the following approach can be applied:
 
@@ -183,0 +209,0 @@ ```

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

3222033

increased by0.11%

Number of package files

335

increased by1.52%

Lines of code

27193

increased by0.03%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

227

increased by12.94%

No dependency changes