{"id":18501179,"url":"https://github.com/dhilt/vscroll-native","last_synced_at":"2025-04-09T01:32:10.714Z","repository":{"id":57394143,"uuid":"330051517","full_name":"dhilt/vscroll-native","owner":"dhilt","description":"Virtual scroll module for native javascript applications","archived":false,"fork":false,"pushed_at":"2022-02-04T20:45:19.000Z","size":1233,"stargazers_count":9,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-14T00:53:50.360Z","etag":null,"topics":["infinite-scroll","javascript","scroll","scroller","scrolling","typescript","virtual","virtual-list","virtual-scroll","virtual-scroller","virtualscroll"],"latest_commit_sha":null,"homepage":"https://dhilt.github.io/vscroll-native/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dhilt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-16T00:22:40.000Z","updated_at":"2023-12-20T05:56:41.000Z","dependencies_parsed_at":"2022-09-26T17:00:30.491Z","dependency_job_id":null,"html_url":"https://github.com/dhilt/vscroll-native","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhilt%2Fvscroll-native","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhilt%2Fvscroll-native/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhilt%2Fvscroll-native/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dhilt%2Fvscroll-native/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dhilt","download_url":"https://codeload.github.com/dhilt/vscroll-native/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247609570,"owners_count":20966203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["infinite-scroll","javascript","scroll","scroller","scrolling","typescript","virtual","virtual-list","virtual-scroll","virtual-scroller","virtualscroll"],"created_at":"2024-11-06T13:52:07.763Z","updated_at":"2025-04-09T01:32:10.676Z","avatar_url":"https://github.com/dhilt.png","language":"TypeScript","readme":"[![npm version](https://badge.fury.io/js/vscroll-native.svg)](https://www.npmjs.com/package/vscroll-native)\n\n# vscroll-native\n\nvscroll-native is a JavaScript library built on top of the [vscroll](https://github.com/dhilt/vscroll) library to represent unlimited datasets using virtualization technique. The idea behind virtualization is to increase the performance of large scrollable lists by rendering only a small portion of the dataset, which is visible to the end user at a moment, while the rest of the dataset is emulated with special padding elements that keep the scrollbar parameters consistent, making the UX close to a simple scrollable list without virtualization.\n\n- [Getting](#getting)\n- [Usage](#usage)\n  - [Viewport](#1-viewport)\n  - [Template](#2-template)\n  - [Datasource](#3-datasource)\n- [Adapter](#adapter)\n- [Development](#development)\n \n## Getting\n\n### CDN\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/vscroll-native\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  const scroller = new VScrollNative.Scroller({...});\n\u003c/script\u003e\n```\n\n### NPM\n\n```\nnpm install vscroll-native\n```\n\n```js\nimport { Scroller } from 'vscroll-native';\n\nconst scroller = new Scroller({...});\n```\n\n## Usage\n\nThe `vscroll-native` module exports two entities: `Scroller` and `Datasource`. The virtual scroll engine runs during the `Scroller` class instantiation. The constructor of the `Scroller` class requires 3 arguments packed in a settings object: viewport HTML element, single item HTML template factory and the datasource.\n\n```js\nimport { Scroller, Datasource } from 'vscroll-native';\n\nconst element = document.getElementById('viewport');\n\nconst template = item =\u003e\n  `\u003cdiv class=\"item\"\u003e\u003cspan\u003e${item.data.id}\u003c/span\u003e) ${item.data.text}\u003c/div\u003e`;\n\nconst datasource = new Datasource({\n  get: (index, length, success) =\u003e {\n    const data = [];\n    for (let i = index; i \u003c= index + count - 1; i++) {\n      const item: Data = { id: i, text: 'item #' + i };\n      data.push(item);\n    }\n    success(data);\n  }\n});\n\nnew Scroller({ element, datasource, template });\n```\n\nThis basic example is available at https://dhilt.github.io/vscroll-native/samples/cdn/. Let's clarify what the `Scroller` is and how to instantiate it properly. In terms of the TypeScript the argument object of the `Scroller` constructor has the following type:\n\n```typescript\ninterface IScrollerParams\u003cData = unknown\u003e {\n  element: HTMLElement;\n  template: Template\u003cData\u003e;\n  datasource: IDatasource\u003cData\u003e;\n}\n```\n\n### 1. Viewport\n\nThe first parameter of the `Scroller` is an HTML __element__ that should provide the limited viewport with scrollable contents. It should be present in DOM before instantiating the `Scroller`.\n\n```js\nconst element = document.getElementById('viewport');\n```\n\n```html\n\u003cdiv id=\"viewport\"\u003e\u003c/div\u003e\n```\n\n```css\n#viewport {\n  height: 240px;\n  width: 150px;\n  overflow-y: scroll;\n}\n```\n\nThis is the simplest case with the default elements structure that is managed by the Scroller automatically.\n\n### 2. Template\n\nThe second parameter of the `Scroller` is a factory of single item __template__. This is a function that should return a string that will be used by the Scroller to render items in the visible part of the viewport.\n\n```js\nconst template = ({ data }) =\u003e\n  `\u003cdiv class=\"item\"\u003e\u003cspan\u003e${data.id}\u003c/span\u003e) ${data.text}\u003c/div\u003e`;\n```\n\nThe argument of the `template` factory is an item object containing data to be present to the end user. With TypeScript it can be written as follows:\n\n```typescript\nimport { Template } from 'vscroll-native';\n\ninterface Data {\n  id: number;\n  text: string;\n}\n\nconst template: Template\u003cData\u003e = ({ data }) =\u003e\n  `\u003cdiv class=\"item\"\u003e\u003cspan\u003e${data.id}\u003c/span\u003e) ${data.text}\u003c/div\u003e`;\n```\n\n### 3. Datasource\n\nThe third parameter of the `Scroller` is a special __datasource__ object, providing dataset items in runtime. There are two ways of how it can be defined. First, as an object literal of `IDatasource` type:\n\n```typescript\nimport { IDatasource } from 'vscroll-native';\n\nconst datasource: IDatasource\u003cData\u003e = { get, settings };\n```\n\nSecond, as an instance of `Datasource` class, whose constructor requires an object of `IDatasource` type:\n\n```typescript\nimport { Datasource } from 'vscroll-native';\n\nconst datasource = new Datasource\u003cData\u003e({ get, settings });\n```\n\nThe second way makes the Adapter API available via `datasource.adapter` property after the Datasource is instantiated (see [Adapter](#adapter) section). In both cases we need to arrange the object of `IDatasource` type:\n\n```typescript\ninterface IDatasource\u003cData = unknown\u003e {\n  get: DatasourceGet\u003cData\u003e;\n  settings?: Settings\u003cData\u003e;\n  devSettings?: DevSettings;\n}\n```\n\nThe `settings` parameter is optional (as well as `devSettings`), please refer to ngx-ui-scroll documentation to get more information about it: https://github.com/dhilt/ngx-ui-scroll#settings.\n\nThe `get` parameter is the main point of the App-Scroller integration. It should provide a portion of dataset by index and count:\n\n```typescript\nconst get = \u003cData = unknown\u003e(\n  index: number, count: number, success: (data: Data[]) =\u003e void\n) =\u003e \n  success(Array.from({ length: count }).map((i, j) =\u003e\n    ({ id: index + j, text: 'item #' + (index + j) })\n  ));\n```\n\nThis is the simplest example of the synchronous `Datasource.get` implementation, where items are generated at runtime and passed to the Scroller via `success` callback. There are two additional signatures for asynchronous implementations: promise-based and observable-based.\n\n```js\nconst get = (index, count) =\u003e new Promise((resolve, reject) =\u003e {\n  makeAjaxCall(index, count)\n    .then(data =\u003e resolve(data))\n    .catch(error =\u003e reject(error))\n});\n// should be equivalent to \n// const get = (index, count) =\u003e makeAjaxCall(index, count);\n```\n\n```js\nimport { Observable } from 'rxjs';\n\nconst get = (index, count) =\u003e new Observable(subscriber =\u003e {\n  makeAjaxCall(index, count)\n    .then(data =\u003e subscriber.next(data))\n    .catch(error =\u003e subscriber.error(error))\n    .finally(() =\u003e subscriber.complete())\n});\n```\n\n## Adapter\n\n`Adapter` is a special entity providing massive functionality to assess and manipulate Scroller's data/parameters at runtime. It is available if the `Datasource` is created via operator `new`.\n\n```js\nimport { Datasource, Scroller } from 'vscroll-native';\n\nconst ds = new Datasource({ ... });\n\nds.adapter.init$.once(() =\u003e console.log('Adapter works, the second output'));\n\nnew Scroller({ datasource: ds, ... });\n\nconsole.log('Scroller works, the first output');\n```\n\nNote, that the adapter subscriptions become available right after instantiating the `Datasource`, but they start work only after the `Scroller` instantiation.\n\nPlease refer to the ngx-ui-scroll documentation for more information on the Adapter API: https://github.com/dhilt/ngx-ui-scroll#adapter-api. An important difference should be taken into account, this is how the reactive props are implemented:\n - ngx-ui-scroll Adapter implements RxJs subjects,\n - vscroll-native Adapter implements [Reactive](https://github.com/dhilt/vscroll/blob/main/src/classes/reactive.ts) entities.\n\nThe vscroll-native demo contains some basic examples of the Adapter usage: https://dhilt.github.io/vscroll-native/.\n\n\n## Development\n\nThe `vscroll-native` module is built on top of the [vscroll](https://github.com/dhilt/vscroll) solution and can be treated as a `vscroll` wrapper or consumer. It is designed to demonstrate how the `vscroll` solution may work in non-specific environment. The sources of the `vscroll-native` module are relatively small (https://github.com/dhilt/vscroll-native/tree/main/src); they do\n\n  - instantiate the virtual scrolling Workflow (main entity of the vscroll module),\n  - advance DOM manipulations in accordance with the Workflow requirements,\n  - provide some infrastructure logic such as internal Workflow instance storage and external Scroller class.\n\nThe issues, requests and ideas that are not targeting these particular points should be addressed to the [vscroll](https://github.com/dhilt/vscroll) repository.\n\nThe most important point of the development of the vscroll-native module is the DOM-related logic. Another important area is [the demo app](https://github.com/dhilt/vscroll-native/tree/main/demo) development. Also, [the tests]((https://github.com/dhilt/vscroll-native/tree/main/tests)) are very poor and need extension.\n\nThere are some npm scripts:\n\n  - `npm start`, runs the demo app over the vscroll-native sources at 5000 port\n  - `npm run build`, builds the vscroll-native distributive\n  - `npm run build-app`, builds the demo app distributive\n  - `npm test`, performs linter and tests in a single run\n  - `npm run jest`, runs tests in a watch mode\n\n______\n\n\n2022 \u0026copy; [Denis Hilt](https://github.com/dhilt)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhilt%2Fvscroll-native","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdhilt%2Fvscroll-native","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdhilt%2Fvscroll-native/lists"}