issue-225 virtual remove documentation & demo

Author: dhilt

README.md

@@ -181,9 +181,9 @@ Below is the list of invocable methods of the Adapter API with description and l
 |[append](https://dhilt.github.io/ngx-ui-scroll/#/adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;any[],<br>&nbsp;&nbsp;eof?:&nbsp;boolean<br>}) <br><br> (items:&nbsp;any&nbsp;&vert;&nbsp;any[], eof?:&nbsp;boolean) &#42;<br><sub>&#42; old signature, deprecated</sub>|Adds items to the end of the uiScroll dataset. If eof parameter is not set, items will be added and rendered immediately, they will be placed right after the last item in the uiScroll buffer. If eof parameter is set to true, items will be added and rendered only if the end of the dataset is reached; otherwise, these items will be virtualized. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#/adapter#bof-eof) demo. |
 |[prepend](https://dhilt.github.io/ngx-ui-scroll/#/adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;any[],<br>&nbsp;&nbsp;bof?:&nbsp;boolean<br>}) <br><br> (items:&nbsp;any&nbsp;&vert;&nbsp;any[], bof?:&nbsp;boolean) &#42;<br><sub>&#42; old signature, deprecated</sub>|Adds items to the beginning of the uiScroll dataset. If bof parameter is not set, items will be added and rendered immediately, they will be placed right before the first item in the uiScroll buffer. If bof parameter is set to true, items will be added and rendered only if the beginning of the dataset is reached; otherwise, these items will be virtualized. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#/adapter#bof-eof) demo. |
 |[check](https://dhilt.github.io/ngx-ui-scroll/#/adapter#check-size)| |Checks if any of current items changed it's size and runs a procedure to provide internal consistency and new items fetching if needed. |
-|[remove](https://dhilt.github.io/ngx-ui-scroll/#/adapter#remove)|(options: {<br>&nbsp;&nbsp;predicate:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;increase?:&nbsp;boolean<br>}) <br><br> type&nbsp;ItemsPredicate&nbsp;=<br>&nbsp;&nbsp;(item: ItemAdapter)&nbsp;=><br>&nbsp;&nbsp;&nbsp;&nbsp;boolean|Removes items from current buffer. Predicate is a function to be applied to every item presently in the buffer. Predicate must return boolean value. If predicate's return value is true, the item will be removed. By default, indexes of the items following the deleted ones are decremented. Instead, if _increase_ is set to _true_, indexes of the items before the removed ones will be increased. <sub>_Note!_ Current implementation allows to remove only a continuous series of items per call. If you want to remove, say, 5 and 7 items, you should call the remove method twice. Removing a series of items from 5 to 7 could be done in a single call.</sub> |
+|[remove](https://dhilt.github.io/ngx-ui-scroll/#/adapter#remove)|(options: {<br>&nbsp;&nbsp;predicate?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;indexes?:&nbsp;number[],<br>&nbsp;&nbsp;increase?:&nbsp;boolean<br>}) <br><br>(func:&nbsp;ItemsPredicate) &#42;<br><sub>&#42; old signature, deprecated</sub><br><br> type&nbsp;ItemsPredicate&nbsp;=<br>&nbsp;&nbsp;(item: ItemAdapter)&nbsp;=><br>&nbsp;&nbsp;&nbsp;&nbsp;boolean|Removes items form buffer and/or virtually. Predicate is a function to be applied to every item presently in the buffer. Predicate must return a boolean value. If predicate's return value is true, the item will be removed. Alternatively, if _indexes_ array is passed, the items whose indexes match the list will be removed. Only one of the _predicate_ and _indexes_ options is allowed. In case of _indexes_, the deletion is performed also virtually. By default, indexes of the items following the deleted ones are decremented. Instead, if _increase_ is set to _true_, indexes of the items before the removed ones will be increased. |
 |[clip](https://dhilt.github.io/ngx-ui-scroll/#/adapter#clip)|(options: {<br>&nbsp;&nbsp;forwardOnly?:&nbsp;boolean,<br>&nbsp;&nbsp;backwardOnly?:&nbsp;boolean<br>})|Removes out-of-viewport items on demand. The direction in which invisible items should be clipped can be specified by passing an options object. If no options is passed (or both properties are set to _true_), clipping will occur in both directions. |
-|[insert](https://dhilt.github.io/ngx-ui-scroll/#/adapter#insert)|(options: {<br>&nbsp;&nbsp;items:&nbsp;any[],<br>&nbsp;&nbsp;before?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;after?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;decrease?:&nbsp;boolean<br>})|Inserts items _before_ or _after_ the one that satisfies the predicate condition. Only one of _before_ and _after_ options is allowed. Indexes increase by default. Decreasing strategy can be enabled via _decrease_ option. |
+|[insert](https://dhilt.github.io/ngx-ui-scroll/#/adapter#insert)|(options: {<br>&nbsp;&nbsp;items:&nbsp;any[],<br>&nbsp;&nbsp;before?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;after?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;decrease?:&nbsp;boolean<br>})|Inserts items _before_ or _after_ the one that presents in the buffer and satisfies the predicate condition. Only one of the _before_ and _after_ options is allowed. Indexes increase by default. Decreasing strategy can be enabled via _decrease_ option. |
 
 Along with the documented API there are some undocumented features that can be treated as experimental. They are not tested enough and might change over time. Some of them can be found on the [experimental tab](https://dhilt.github.io/ngx-ui-scroll/#/experimental) of the demo app.
 

demo/app/samples/adapter/remove.component.html

@@ -15,38 +15,57 @@
   </div>
   <div description>
     <p>
-      <em>Adapter.remove</em> method allows to remove items from current buffer.
+      <em>Adapter.remove</em> method allows to remove items from current buffer or/and virtually.
       The argument of this method is an object of the following type:
     </p>
     <pre>{{argumentsDescription}}</pre>
     <p>
       The <em>predicate</em> option is a function applying to each item in the buffer.
       If the return value is true, the item will be removed.
-      Only a continuous series of items can be removed at a time.
-      So, if you need to remove items 1, 2, 3 and 5,
-      you need to call this method twice: once for 1, 2, 3 and then for 5.
-    </p>
-    <p>
       The argument of the predicate has <em>ItemAdapter</em> type, and
       in this demo we have two versions of <em>predicate</em> using for
       removing by id and by index:
     </p>
     <pre>{{predicateDescription}}</pre>
     <p>
-      Indexes are adjusted each time we perform a removing from the buffer.
+      Only a continuous series of items can be removed at a time using <em>predicate</em>.
+      So, if you need to remove items 1, 2, 3 and 5,
+      you need to call this method twice: once for 1, 2, 3 and then for 5.
+    </p>
+    <p>
+      Instead of <em>predicate</em> running over buffered items,
+      it is possible to remove items by <em>indexes</em>.
+      It has no sequence limitation.
+      This method works with both buffered and virtual items.
+      For example, if we have [1..10] buffered items (they are rendered)
+      and [11..100] virtual items (emulated via forward padding element
+      which size corresponds to 90 virtual items) and the we perform
+      <em>Adapter.remove(&#123; indexes: [100] &#125;)</em>, we'll have
+      the following:
+    </p>
+    <ul>
+      <li>buffer is not affected</li>
+      <li>the visible part of the viewport remains the same</li>
+      <li>
+        size of the forward padding is reduced by the size of the 100th item,
+        so the scrollable area becomes slightly smaller
+      </li>
+    </ul>
+    <p>
+      Indexes are adjusted each time we perform a removing via Adapter.
       It is impossible to remove item with id = 5 twice,
       because there is only one item with id = 5.
       But we may remove item with index = 5 as many times
-      as many items we have after this index. Indexes decrease by default.
+      as many items we have after this index. 
     </p>
     <p>
-      The second option is <em>increase</em>.
-      It is for changing the default indexes adjustment strategy.
-      By setting it to <em>true</em>, we tell the <em>uiScroll</em>
+      Indexes decrease by default, and the next option (<em>increase</em>)
+      allows to change the default indexes adjustment strategy.
+      By setting <em>increase</em> to <em>true</em>, we tell the <em>uiScroll</em>
       that we want to increase indexes of the items before the removed one(s).
     </p>
     <p>
-      The very important thing is to synchronize our datasource with the changes
+      The very important thing is to synchronize the datasource with the changes
       we are making over the <em>uiScroll</em> buffer via <em>Adapter.remove</em>.
       Generally this is the App component responsibility,
       and in this demo it is done by the <em>removeFromDatasource</em> method.

demo/app/samples/adapter/remove.component.ts

@@ -136,7 +136,8 @@ async removeByIndex(index: number) {
   }];
 
   argumentsDescription = `  AdapterRemoveOptions {
-    predicate: ItemsPredicate;
+    predicate?: ItemsPredicate;
+    indexes?: number[];
     increase?: boolean;
   }`;
   predicateDescription = `  adapter.remove({ predicate: ({ data }) => data.id === id });