Merge pull request #358 from dhilt/issue-357-Allow-force-virtualization-on-append-prepend

Allow force virtualization on append prepend

Author: dhilt

.github/workflows/ci.yml

@@ -14,10 +14,7 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [16.x]
+    runs-on: ubuntu-22.04
     steps:
       - name: Dispatched?
         if: ${{ github.event_name == 'workflow_dispatch' }}
@@ -26,12 +23,12 @@ jobs:
           echo "Build reason: ${{ github.event.inputs.cause }}"
 
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 20
 
       - run: npm run ci:lib
       - run: npm run build:lib
@@ -40,14 +37,14 @@ jobs:
       - run: npm run ci:tests
       - run: npm test
 
-      - uses: actions/upload-artifact@master
+      - uses: actions/upload-artifact@v4
         with:
           name: demo-dist
           path: dist/demo
 
   deploy:
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
       - name: Set env BRANCH
         run: echo "BRANCH=$(echo $GITHUB_REF | cut -d'/' -f 3)" >> $GITHUB_ENV
@@ -66,11 +63,11 @@ jobs:
 
       - name: Checkout
         if: env.NEED == 'true'
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Download dist
         if: env.NEED == 'true'
-        uses: actions/download-artifact@master
+        uses: actions/download-artifact@v4
         with:
           name: demo-dist
           path: dist-demo-app
@@ -80,4 +77,4 @@ jobs:
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
-          folder: dist-demo-app
+          folder: dist-demo-app

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Denis Hilt (https://github.com/dhilt)
+Copyright (c) 2025 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

README.md

@@ -220,8 +220,8 @@ Below is the list of invocable methods of the Adapter API with description and l
 |[resume](https://dhilt.github.io/ngx-ui-scroll/#adapter#pause-resume)| |Resumes the Scroller if it was paused. |
 |[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. |
 |[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. |
-|[append](https://dhilt.github.io/ngx-ui-scroll/#adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;eof?:&nbsp;boolean<br>&nbsp;&nbsp;decrease?:&nbsp;boolean<br>})|Adds _items_ to the end of the Scroller's buffer/dataset. If _eof_ flag is not set, items will be inserted right after the last buffered item and rendered immediately. If _eof_ is _true_, rendering will occur only if the right border of the buffer matches the right border of the dataset (end-of-file is reached); otherwise, items will be virtualized as appended to the end of the dataset. Indexes increase by default. If _decrease_ is set to true, indexes are decremented. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#adapter#bof-eof). |
-|[prepend](https://dhilt.github.io/ngx-ui-scroll/#adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;bof?:&nbsp;boolean<br>&nbsp;&nbsp;increase?:&nbsp;boolean<br>})|Adds _items_ to the beginning of the Scroller's buffer/dataset. If _bof_ flag is not set, items will be inserted right before the first buffered item and rendered immediately. If _bof_ is _true_, rendering will occur only if the left border of the buffer matches the left border of the dataset (begin-of-file is reached); otherwise, items will be virtualized as prepended to the beginning of the dataset. Indexes decrease by default. If _increase_ is set to true, indexes are incremented. Note, by historical reasons, _items_ are being reversed during prepending, so if you need to have "initial" order, you may reverse the _items_ array before prepend, or use Adapter.insert API instead. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#adapter#bof-eof). |
+|[append](https://dhilt.github.io/ngx-ui-scroll/#adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;eof?:&nbsp;boolean,<br>&nbsp;&nbsp;virtualize?:&nbsp;boolean<br>&nbsp;&nbsp;decrease?:&nbsp;boolean<br>})|Adds _items_ to the end of the Scroller's buffer. If neither _eof_ nor _virtualize_ flag is set, items are inserted and rendered after the last item in the DOM. If _eof_ is _true_, rendering occurs only when the right border of the buffer aligns with the right border of the dataset (end-of-file is reached). Otherwise, items are added to the dataset but not rendered (they are virtualized). Setting the _virtualize_ flag enables hard virtualization: new _items_ will be rendered even if EOF has been reached. Indexes increase by default. If _decrease_ is set to true, indexes are decremented. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#adapter#bof-eof). |
+|[prepend](https://dhilt.github.io/ngx-ui-scroll/#adapter#append-prepend)|(options: {<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;bof?:&nbsp;boolean,<br>&nbsp;&nbsp;virtualize?:&nbsp;boolean<br>&nbsp;&nbsp;increase?:&nbsp;boolean<br>})|Adds _items_ to the beginning of the Scroller's buffer. If neither _bof_ nor _virtualize_ flag is set, items are inserted and rendered before the first item in the DOM. If _bof_ is true, rendering occurs only when the left border of the buffer aligns with the left border of the dataset (begin-of-file is reached). Otherwise, items are added to the dataset but not rendered (they are virtualized). Setting the _virtualize_ flag enables hard virtualization: new items will be rendered even if BOF has been reached. Indexes decrease by default. If _increase_ is set to true, indexes are decremented. For historical reasons, items are reversed when performing the prepend operation. To maintain the original order when prepending items, you can either reverse the array before calling Adapter.prepend, or use the Adapter.insert method instead. See also [bof/eof](https://dhilt.github.io/ngx-ui-scroll/#adapter#bof-eof). |
 |[insert](https://dhilt.github.io/ngx-ui-scroll/#adapter#insert)|(options: {<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;before?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;after?:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;beforeIndex?:&nbsp;number,<br>&nbsp;&nbsp;afterIndex?:&nbsp;number,<br>&nbsp;&nbsp;decrease?:&nbsp;boolean<br>})|Inserts _items_ into the buffer or virtually. Only one of the _before_, _after_, _beforeIndex_ and _afterIndex_ options is allowed. If _before_ or _after_ option is used, the Scroller will try to insert items before or after the item that presents in the buffer and satisfies the predicate condition. If _beforeIndex_ or _afterIndex_ option is used, the Scroller will try to insert items by index. If the index to insert is out of the buffer but still belongs to the known datasource boundaries, then the _items_ will be virtualized. Indexes increase by default. Decreasing strategy can be enabled via _decrease_ option. |
 |[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> 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_, the indexes of the items before the removed ones are incremented. |
 |[replace](https://dhilt.github.io/ngx-ui-scroll/#adapter#replace)|(options: {<br>&nbsp;&nbsp;predicate:&nbsp;ItemsPredicate,<br>&nbsp;&nbsp;items:&nbsp;MyItem[],<br>&nbsp;&nbsp;fixRight?:&nbsp;boolean<br>})|Replaces items that continuously match the _predicate_ with an array of new _items_. Indexes are maintained on the assumption that the left border of the dataset is fixed. To release the left border and fix the right one the _fixRight_ option should be set to _true_. |
@@ -287,4 +287,4 @@ Any support and participation are welcome, so feel free to <a href="https://gith
 
 __________
 
-2024 &copy; dhilt
+2025 &copy; dhilt

demo/angular.json

@@ -74,5 +74,8 @@
         }
       }
     }
+  },
+  "cli": {
+    "analytics": false
   }
 }

demo/app/samples/adapter/append-prepend-sync.component.html

@@ -1,51 +1,33 @@
 <ng-template #itemTemplate let-item="item" let-index="index">
   <span class="index">{{ index }})</span> {{ item.text }}
 </ng-template>
-
-<app-demo
-  [datasource]="datasource"
-  [context]="demoContext"
-  [sources]="sources"
-  [itemTemplate]="itemTemplate"
->
+<app-demo [datasource]="datasource" [context]="demoContext" [sources]="sources" [itemTemplate]="itemTemplate">
   <div actions>
     <button (click)="doPrepend()">Prepend</button>&nbsp;
-    <input
-      [ngModel]="inputPrepend"
-      (change)="onInputChanged(true, $any($event.target))"
-      size="2"
-    />
+    <input [ngModel]="inputPrepend" (change)="onInputChanged(true, $any($event.target))" size="2" />
     &nbsp;items
-    {{ increasePrepend ? 'increasingly' : 'decreasingly' }} &nbsp;<input
-      type="checkbox"
-      [(ngModel)]="increasePrepend"
-    />
+    {{ increasePrepend ? 'increasingly' : 'decreasingly' }} &nbsp;<input type="checkbox" [(ngModel)]="increasePrepend" />
     <br />
     <button (click)="doAppend()">Append</button>&nbsp;
-    <input
-      [ngModel]="inputAppend"
-      (change)="onInputChanged(false, $any($event.target))"
-      size="2"
-    />
+    <input [ngModel]="inputAppend" (change)="onInputChanged(false, $any($event.target))" size="2" />
     &nbsp;items
-    {{ decreaseAppend ? 'decreasingly' : 'increasingly' }} &nbsp;<input
-      type="checkbox"
-      [(ngModel)]="decreaseAppend"
-    />
+    {{ decreaseAppend ? 'decreasingly' : 'increasingly' }} &nbsp;<input type="checkbox" [(ngModel)]="decreaseAppend" />
   </div>
-
   <div description>
     <p>
-      Along with <em>items</em> parameter both append and prepend methods have
-      <em>eof</em>/<em>bof</em> parameter which is optional and which prevents
-      rendering of new items when the end of the dataset (if we are speaking of
-      <em>append</em>) or beginning of the dataset (<em>prepend</em> case) is
-      not reached. See also
-      <a
-        [routerLink]="['/', adapterScope.id]"
-        fragment="{{ adapterPropsScope.map.bofEof.id }}"
-        >bof/eof demo</a
-      >.
+      The <em>append</em> and <em>prepend</em> methods have parameters
+      responsible for the virtualization of inserted items:
+      <em>eof</em>/<em>bof</em> and <em>virtualize</em>.
+      Only one of these parameters can be used at a time
+      (setting both to <em>true</em> simultaneously will reset both values to <em>false</em>).
+    </p>
+    <p>
+      If <em>eof</em>/<em>bof</em> is set to <em>true</em>,
+      the items added via the <em>append</em>/<em>prepend</em> methods will be virtualized
+      and will not appear in the DOM if, at the time of insertion,
+      we are not at the beginning (in the case of prepend-bof)
+      or at the end (in the case of append-eof) of the list.
+      See also <a [routerLink]="['/', adapterScope.id]" fragment="{{ adapterPropsScope.map.bofEof.id }}">bof/eof demo</a>.
     </p>
     <p>
       For example, if we call <em>{{ prependCallSample }}</em> when the
@@ -57,13 +39,16 @@
       default item size. The same works for <em>{{ appendCallSample }}</em> call
       adjusted for forward direction and forward padding element.
     </p>
+    <p>
+      If <em>virtualize</em> is set to <em>true</em>, the added rows will be virtualized in any case,
+      even if we are at the beginning or end of the list.
+    </p>
     <p>
       Indexes increase by default when <em>Adapter.append</em> and decrease by
       default when <em>Adapter.prepend</em>. The indexing strategy can be
       changed by <em>decrease</em>/<em>increase</em> params. They are boolean
       and set to <em>false</em> by default. For example, if we call
-      <em>{{ prependIncreaseCallSample }}</em
-      >, the topmost index remains unchanged, prepended items start with the
+      <em>{{ prependIncreaseCallSample }}</em>, the topmost index remains unchanged, prepended items start with the
       topmost index, the rest indexes are incremented.
     </p>
     <p>
@@ -77,18 +62,10 @@
       <em>Datasource.get</em> and doPrepend/doAppend methods to guarantee a
       stable data flow from the App component to the Scroller. Another examples
       of such synchronization could be found in
-      <a
-        [routerLink]="['/', adapterScope.id]"
-        fragment="{{ adapterMethodsScope.map.remove.id }}"
-        >remove</a
-      >
+      <a [routerLink]="['/', adapterScope.id]" fragment="{{ adapterMethodsScope.map.remove.id }}">remove</a>
       and
-      <a
-        [routerLink]="['/', adapterScope.id]"
-        fragment="{{ adapterMethodsScope.map.insert.id }}"
-        >insert</a
-      >
+      <a [routerLink]="['/', adapterScope.id]" fragment="{{ adapterMethodsScope.map.insert.id }}">insert</a>
       demos.
     </p>
   </div>
-</app-demo>
+</app-demo>

demo/app/samples/adapter/append-prepend.component.html

@@ -2,19 +2,14 @@
   <div actions style="display: flex">
     <button (click)="doAppend()">Append</button> /
     <button (click)="doPrepend()">Prepend</button>
-    <input
-      [ngModel]="inputValue"
-      (change)="onInputChanged($any($event.target))"
-      size="2"
-    />
+    <input [ngModel]="inputValue" (change)="onInputChanged($any($event.target))" size="2" />
   </div>
-
   <div description>
     <p>
       Adding items at the end and at the beginning of the Scroller's Buffer is
       possible with
       <em>Adapter.append</em> and <em>Adapter.prepend</em> methods respectively.
-      They have the following object-arguments:
+      These methods accept the following argument objects:
     </p>
     <div class="row">
       <div class="column">
@@ -24,46 +19,42 @@
         <pre>{{ prependArgumentsDescription }}</pre>
       </div>
     </div>
+    <ul>
+      <li><em>items</em> An array of items to add.</li>
+      <li><em>eof</em>/<em>bof</em>/<em>virtualize</em> Virtualization params.</li>
+      <li><em>decrease</em>/<em>increase</em> Influence the index management strategy.</li>
+    </ul>
     <p>
-      The <em>items</em> parameter is an array of items we want to add,
-      <em>eof</em>/<em>bof</em> params provide virtualization,
-      <em>decrease</em>/<em>increase</em> define index strategy. Here we deal
-      with only <em>items</em> parameter, other params are considered in the
-      <a
-        [routerLink]="['/', adapterScope.id]"
-        fragment="{{ adapterMethodsScope.map.appendPrependSync.id }}"
-        >next demo</a
-      >. Both <em>append</em> and <em>prepend</em> methods act in the same way,
+      In this section, we focus on the <em>items</em> parameter.
+      The other options will be considered in the
+      <a [routerLink]="['/', adapterScope.id]" fragment="{{ adapterMethodsScope.map.appendPrependSync.id }}">next demo</a>.
+      Both <em>append</em> and <em>prepend</em> methods work similarly,
       so let's discuss <em>prepend</em>.
     </p>
     <p>
-      In this demo we have 20 items on start, 5 of them (95-99) are invisible on
-      the backward direction. By pushing "Prepend" button we want to add 4
-      (which is the input value) new items to the top of the list. After they
-      are prepended, they become visible when scrolling up. The Scroller
-      accurately injects prepended items into its Buffer consisting of 95-114
-      rows initially, so 1-4 new items temporary take place of items with
-      indexes 91-94.
+      In this demo we have 20 items on start. The first 5 items (indices 95–99)
+      are invisible because they are outside the visible part of the viewport.
+      When you click the “Prepend” button, 4 new items (as specified in the input)
+      are added to the top of the list. These prepended items become visible as you scroll upward.
+      The Scroller seamlessly injects these new items into its buffer,
+      so the buffer indices change from 95–114 to 91–114.
     </p>
     <p>
-      But if we scroll away and make '90s items invisible and removed from the
-      viewport, and then scroll back, we will realise that nothing changes:
-      "new" items are gone and the old 91-94 items returned to initial position.
-      The point is that the changes we provide via <em>Adapter</em> over the
-      internal Scroller's Buffer don't affect the external
-      <em>Datasource</em> we implemented on the Component level. This is the end
-      app developer responsibility to take care of the data consistency during
-      manual updates such as append, prepend, insert, remove, etc: the
-      <em>Datasource.get</em> must provide correct data, while the Scroller
-      maintains indexes.
-      <a
-        [routerLink]="['/', adapterScope.id]"
-        fragment="{{ adapterMethodsScope.map.appendPrependSync.id }}"
-        >The next sample</a
-      >
-      provides one of the approach of consistent
-      <em>Datasource</em> implementation with <em>Adapter.append</em> and
-      <em>Adapter.prepend</em> methods usage.
+      However, if you scroll away — causing the items with indices in the 90s
+      to become invisible and be removed from the DOM — and then scroll back,
+      you’ll notice that the “new” items are gone and the original items (91–94)
+      have returned to their places. This behavior occurs because changes
+      made via the <em>Adapter</em> only affect the Scroller’s internal buffer,
+      not the external <em>Datasource</em> managed at the App Component level.
+    </p>
+    <p>
+      It is the responsibility of the end app developer to maintain data consistency
+      when performing manual updates (such as append, prepend, insert, remove operations).
+      The <em>Datasource.get</em> method must always return the correct data,
+      while the Scroller manages the indexes.
+      The <a [routerLink]="['/', adapterScope.id]" fragment="{{ adapterMethodsScope.map.appendPrependSync.id }}">next sample</a>
+      demonstrates an approach for consistent <em>Datasource</em> implementation
+      synchronized with the use of the <em>Adapter.append</em> and <em>Adapter.prepend</em> methods.
     </p>
   </div>
-</app-demo>
+</app-demo>

demo/app/samples/adapter/append-prepend.component.ts

@@ -123,11 +123,13 @@ async doAppend() {
   prependArgumentsDescription = `  AdapterPrependOptions {
     items: unknown[];
     bof?: boolean;
+    virtualize?: boolean;
     increase?: boolean;
   }`;
   appendArgumentsDescription = `  AdapterAppendOptions {
     items: unknown[];
     eof?: boolean;
+    virtualize?: boolean;
     decrease?: boolean;
   }`;