DataSources - cursor-based pagination support

app/src/docs/_examples/dataSources/LazyDataSourceCursor.example.tsx

@@ -0,0 +1,53 @@
+import React, { useState } from 'react';
+import { DataQueryFilter, DataSourceState, useLazyDataSource, useUuiContext } from '@epam/uui-core';
+import { DataSourceViewer } from '@epam/uui-docs';
+import { TApi } from '../../../data';
+import { City } from '@epam/uui-docs';
+
+export default function LazyDataSourceDataExample() {
+    const svc = useUuiContext<TApi>();
+
+    const [value, onValueChange] = useState<DataSourceState>({});
+    const dataSource = useLazyDataSource<City, string, DataQueryFilter<City>>({
+        api: async (req) => {
+            // We emulate server cursor-based API here.
+            // Usually this done at server, and you need to pass cursor as is.
+
+            // The server-side logic might be more complex, as we ignore several cases here:
+            // - we assume the list is sorted by name, and sorting can't change
+            //   To handle this, cursor would need to store field by which the list is sorted.
+            // - we assume that names are unique.
+            //   To handle this, we would need to add item ID to cursor, and make more complex filter, like:
+            //     where (name > cursor.name) OR (name = cursor.name && id > cursor.id)
+            //     order by name, id
+
+            const { cursor, ...request } = req;
+
+            if (cursor) {
+                request.filter = request.filter || {};
+                // fetch only cities with name after the last fetched city alphabetically
+                request.filter.name = { gt: cursor };
+                request.range = { ...request.range, from: 0 };
+            }
+
+            request.sorting = [{ field: 'name', direction: 'asc' }];
+
+            const response = await svc.api.demo.cities(request);
+
+            if (response.items.length > 0) {
+                // store last item's name as cursor
+                response.cursor = response.items[response.items.length - 1].name;
+            }
+
+            return response;
+        },
+    }, []);
+
+    return (
+        <DataSourceViewer
+            value={ value }
+            onValueChange={ onValueChange }
+            dataSource={ dataSource }
+        />
+    );
+}

app/src/docs/dataSources/LazyDataSource.doc.tsx

@@ -20,6 +20,7 @@ export class DataSourcesLazyDataSourceDoc extends BaseDocsBlock {
                 <DocExample title="Child count" path="./_examples/dataSources/LazyDataSourceGetChildCount.example.tsx" />
                 <DocExample title="Filter" path="./_examples/dataSources/LazyDataSourceFilter.example.tsx" />
                 <DocExample title="Flatten search results" path="./_examples/dataSources/LazyDataSourceFlattenSearchResults.example.tsx" />
+                <DocExample title="Using cursor-based pagination" path="./_examples/dataSources/LazyDataSourceCursor.example.tsx" />
             </>
         );
     }

changelog.md

@@ -1,6 +1,7 @@
 # 5.*.* - **.**.2024
 
 **What's New**
+* [Data Sources]: cursor-based pagination support. More details [here](http://uui.epam.com/documents?id=dataSources-lazy-dataSource&mode=doc&category=dataSources&theme=loveship#using_cursor-based_pagination)
 * [TabButton][VerticalTabButton]: decreased paddings, added gaps `3px` between internal items for all sizes according to design
 * [Tag]: changed layout - added gaps between internal items, changed padding
 

public/docs/content/examples-dataSources-LazyDataSourceCursor.json

@@ -0,0 +1,104 @@
+[
+  {
+    "type": "paragraph",
+    "children": [
+      {
+        "text": "Usually, backend uses integer ranges to allow querying part of the lists. E.g.  "
+      },
+      {
+        "text": "/api/items?from=10&count=20",
+        "uui-richTextEditor-code": true
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "children": [
+      {
+        "text": "With cursor-based pagination, backend serializes some state, associated with the next item in the list. Using this info, the next part of the list can be fetched more efficiently."
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "children": [
+      {
+        "text": "You can read more in this article: "
+      },
+      {
+        "type": "link",
+        "url": "https://medium.com/@nimmikrishnab/cursor-based-pagination-37f5fae9f482",
+        "target": "_blank",
+        "children": [
+          {
+            "text": "Cursor-based Pagination"
+          }
+        ]
+      },
+      {
+        "text": ""
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "children": [
+      {
+        "text": "To use this pattern, you need to return the latest cursor value in response to the "
+      },
+      {
+        "text": "api",
+        "uui-richTextEditor-code": true
+      },
+      {
+        "text": " callback. This cursor will be passed to the "
+      },
+      {
+        "text": "api",
+        "uui-richTextEditor-code": true
+      },
+      {
+        "text": " request, called to fetch the next part of this list."
+      }
+    ]
+  },
+  {
+    "type": "paragraph",
+    "children": [
+      {
+        "text": "Note that:"
+      }
+    ]
+  },
+  {
+    "type": "unordered-list",
+    "children": [
+      {
+        "type": "list-item",
+        "children": [
+          {
+            "type": "list-item-child",
+            "children": [
+              {
+                "text": "absence of cursor in response doesn't imply the end of the list. End of the list is detected when there are fewer items returned, than was requested"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "list-item",
+        "children": [
+          {
+            "type": "list-item-child",
+            "children": [
+              {
+                "text": "with hierarchical lists, the root and all child sub-lists has its own cursor, and they are tracked separately."
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+]

public/docs/docsGenOutput/docsGenOutput.d.ts

@@ -421,7 +421,6 @@ type Autogenerated_TDocsGenExportedTypeRef = '@epam/uui-core:AcceptDropParams' |
 '@epam/uui:TextModsOverride' |
 '@epam/uui:TextPlaceholderProps' |
 '@epam/uui:TextProps' |
-'@epam/uui:TextSettings' |
 '@epam/uui:TimePickerBodyProps' |
 '@epam/uui:TimePickerModsOverride' |
 '@epam/uui:TimePickerProps' |