Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

react-infinite-grid-scroller

Package Overview
Dependencies
Maintainers
1
Versions
83
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

react-infinite-grid-scroller - npm Package Compare versions

Comparing version 1.0.5 to 1.1.0

14

package.json
{
"name": "react-infinite-grid-scroller",
"version": "1.0.5",
"description": "Heavy-duty vertical or horizontal infinite scroller",
"version": "1.1.0",
"description": "infinite vertical or horizontal scroll using css grid layout",
"main": "index.js",

@@ -44,4 +44,3 @@ "scripts": {

"react-reverse-portal": "^2.0.1",
"requestidlecallback": "^0.3.0",
"wepack-cli": "^0.0.1-security"
"requestidlecallback": "^0.3.0"
},

@@ -62,4 +61,4 @@ "peerDependencies": {

"@types/react-dom": "^18.0.0",
"@typescript-eslint/eslint-plugin": "^5.48.0",
"@typescript-eslint/parser": "^5.48.0",
"@typescript-eslint/eslint-plugin": "^6.3.0",
"@typescript-eslint/parser": "^6.3.0",
"babel-loader": "^9.1.0",

@@ -73,3 +72,4 @@ "eslint": "^8.31.0",

"webpack-cli": "^5.0.1",
"webpack-sources": "^3.2.1"
"webpack-sources": "^3.2.1",
"wepack-cli": "^0.0.1-security"
},

@@ -76,0 +76,0 @@ "directories": {

# react-infinite-grid-scroller (RIGS)
Heavy-duty vertical or horizontal infinite scroller
[![npm](https://img.shields.io/badge/npm-1.0.5-brightgreen)](https://www.npmjs.com/package/react-infinite-grid-scroller) [![licence](https://img.shields.io/badge/licence-MIT-green)](LICENSE.md)
[![npm](https://img.shields.io/badge/npm-1.1.0-brightgreen)](https://www.npmjs.com/package/react-infinite-grid-scroller) [![licence](https://img.shields.io/badge/licence-MIT-green)](LICENSE.md)

@@ -12,3 +12,3 @@ # Key Features

- single or multiple rows or columns
- dynamically variable virtual list size
- dynamically variable virtual list size; prepend or append
- limited sparse in-memory cache, to preserve content state, with an API

@@ -56,2 +56,4 @@ - repositioning mode when rapidly scrolling (such as by using the scroll thumb)

const lowindex = -50, highindex = 50 // random range values
<div style = { containerstyle }>

@@ -61,3 +63,3 @@ <Scroller

cellWidth = { cellWidth }
startingListSize = { startingListSize } // this constitutes a virtual 0-based array
startingListRange = { [lowindex, highindex] } // this constitutes the virtual list
getItem = { getItem } // a function called by RIGS to obtain a specified user component by index number

@@ -92,29 +94,30 @@ />

|[_**REQUIRED**_]|
|cellHeight|integer: number of pixels for cell height|required. Applied to `height` for 'uniform' layout, 'vertical' orientation. Applied to `max-height` for 'variable' layout, 'vertical' orientation. Approximate, used for `fr` (fractional allocation) for 'horizontal' orientation |
|cellWidth|integer: number of pixels for cell width|required. Applied to `width` for 'uniform' layout, 'horizontal' orientation. Applied to `max-width` for 'variable' layout, 'horizontal' orientation. Approximate, used for `fr` (fractional allocation) for 'vertical' orientation|
|startingListSize|integer: the starting number of items in the virtual list|required. Can be modified at runtime. Constitutes a 0-based virtual array|
|getItem|host-provided function. Parameters: `index` (integer, 0 based), and session `itemID` (integer) for tracking and matching. Arguments provided by system|required. Must return a React component or promise of a component (`React.isValidElement`), or `undefined` = unavailable, or `null` = end-of-list|
|cellHeight:integer| number of pixels for cell height|required. Applied to `height` for 'uniform' layout, 'vertical' orientation. Applied to `max-height` for 'variable' layout, 'vertical' orientation. Approximate, used for `fr` (fractional allocation) for 'horizontal' orientation |
|cellWidth:integer| number of pixels for cell width|required. Applied to `width` for 'uniform' layout, 'horizontal' orientation. Applied to `max-width` for 'variable' layout, 'horizontal' orientation. Approximate, used for `fr` (fractional allocation) for 'vertical' orientation|
|startingListSize:integer| the starting number of items in the virtual list|required. Can be modified at runtime. Constitutes a 0-based virtual array (Internally creates a starting range of [0,startingListSize - 1]. Ignored in the presence of `startingListRange` array|
|startingListRange:[lowindex, highindex] \| []|two part array , or empty array []|lowindex must be <= highindex; both can be positive or negative integers. [] (empty array) creates an empty virtual list|
|getItem(index:integer,itemID:integer):React.FC \| Promise \| undefined \| null|host-provided function. session `itemID` (integer) is for tracking and matching. Arguments provided by system|required. Must return a React component or promise of a component (`React.isValidElement`), or `undefined` = unavailable, or `null` = end-of-list|
|[_**SCROLLER OPTIONS**_]|
|orientation|string: 'vertical' (default) or 'horizontal'|direction of scroll|
|layout|string: 'uniform' (default) or 'variable'|specifies handling of the height or width of cells, depending on orientation. 'uniform' is fixed cellHeight/cellWidth. 'variable' is constrained by cellHeight/cellWidth (maximum) and cellMinHeight/cellMinWidth (minimum)|
|startingIndex|integer: starting index when the scroller first loads|default = 0|
|padding|integer: number of pixels padding the `Cradle`| default = 0|
|orientation:string| 'vertical' (default) or 'horizontal'|direction of scroll|
|layout:string| 'uniform' (default) or 'variable'|specifies handling of the height or width of cells, depending on orientation. 'uniform' is fixed cellHeight/cellWidth. 'variable' is constrained by cellHeight/cellWidth (maximum) and cellMinHeight/cellMinWidth (minimum)|
|startingIndex:integer| starting index when the scroller first loads|default = 0|
|padding:integer| number of pixels padding the `Cradle`| default = 0|
|[_**MORE CELL OPTIONS**_]|
|gap|integer: number of pixels between cells|there is no gap at start or end of rows or columns; default = 0|
|cellMinHeight|integer: default = 25, minimum = 25, maximum = cellHeight|used for 'variable' layout with 'vertical' orientation. Applied to `min-height`|
|cellMinWidth|integer: default = 25, minimum = 25, maximum = cellWidth|used for 'variable' layout with 'horizontal' orientation. Applied to `min-width`|
|gap:integer| number of pixels between cells|there is no gap at start or end of rows or columns; default = 0|
|cellMinHeight:integer| default = 25, minimum = 25, maximum = cellHeight|used for 'variable' layout with 'vertical' orientation. Applied to `min-height`|
|cellMinWidth:integer| default = 25, minimum = 25, maximum = cellWidth|used for 'variable' layout with 'horizontal' orientation. Applied to `min-width`|
|[_**SYSTEM SETTINGS**_]|
|runwaySize|integer: number of rows in the `Cradle` just out of view at head and tail of list|default = 1. minimum = 1. Gives time to assemble cellFrames before display
|cache|string: 'cradle' (default), 'keepload', 'preload'|'cradle' matches the cache to the contents of the `Cradle`. 'keepload' keeps user components in the cache as loaded, up to `cacheMax` (and always `Cradle` user components). 'preload' loads user components up to `cacheMax`, then adjusts cache such that `Cradle` user components are always in the cache|
|cacheMax|integer: at minimum (maintained by system) the number of user components in the `Cradle`|allows optimization of cache size for memory limits and performance|
|useScrollTracker|boolean: default = `true`|allows suppression of system feedback on position within list while in reposition mode, if the host wants to provide alternative feedback based on data from callbacks |
|placeholder|a lightweight React component for `cellFrame`s to load while waiting for the intended `cellFrame` components|optional (replaces default placeholder). parameters are index, listsize, message, error. Arguments set by system|
|usePlaceholder|boolean: default = true|allows suppression of use of default or custom placeholder. Placeholders show messages to the user while user components are fetched, and report errors|
|cacheAPI|requested by user components by being set to null by user; instantiated with a class instance by system|Experimental. If present, parent scroller instantiates the property with its cacheAPI instance, which causes any child scroller given the property to share the parent scroller cache. This currently has no operational effect|
|[_**ADVANCED OBJECTS**_]|
|styles|object: collection of styles for scroller components|optional. These should be "passive" styles like backgroundColor. See below for details|
|placeholderMessages|object: messages presented by the placeholder|optional, to replace default messages. See below for details|
|callbacks|object: collection of functions for feedback, and interactions with scroller components|optional. See below for details|
|technical|object: collection of values used to control system behaviour|use with caution. optional. See below for details|
|scrollerProperties|requested by user components by being set to null by user; instantiated with an object by system|required for nested RIGS; available for all user components. Contains key scroller settings. See below for details|
|runwaySize:integer| number of rows in the `Cradle` just out of view at head and tail of list|default = 1. minimum = 1. Gives time to assemble cellFrames before display
|cache:string| 'cradle' (default), 'keepload', 'preload'|'cradle' matches the cache to the contents of the `Cradle`. 'keepload' keeps user components in the cache as loaded, up to `cacheMax` (and always `Cradle` user components). 'preload' loads user components up to `cacheMax`, then adjusts cache such that `Cradle` user components are always in the cache|
|cacheMax:integer| at minimum (maintained by system) the number of user components in the `Cradle`|allows optimization of cache size for memory limits and performance|
|useScrollTracker:boolean| default = `true`|allows suppression of system feedback on position within list while in reposition mode, if the host wants to provide alternative feedback based on data from callbacks |
|placeholder:React.FC|a lightweight React component for `cellFrame`s to load while waiting for the intended `cellFrame` components|optional (replaces default placeholder). parameters are index, listsize, message, error. Arguments set by system|
|usePlaceholder:boolean| default = true|allows suppression of use of default or custom placeholder. Placeholders show messages to the user while user components are fetched, and report errors|
|cacheAPI:null|requested by user components by being set to null by user; instantiated with a class instance by system|Experimental. If present, parent scroller instantiates the property with its cacheAPI instance, which causes any child scroller given the property to share the parent scroller cache. This currently has no operational effect|
|[_**OBJECT PROPERTIES**_]|
|styles:Object| collection of styles for scroller components|optional. These should be "passive" styles like backgroundColor. See below for details|
|placeholderMessages:Object| messages presented by the placeholder|optional, to replace default messages. See below for details|
|callbacks:Object| collection of functions for feedback, and interactions with scroller components|optional. See below for details|
|technical:Object| collection of values used to control system behaviour|use with caution. optional. See below for details|
|scrollerProperties:null|requested by user components by being set to null by user; instantiated with an object by system|required for nested RIGS; available for all user components. Contains key scroller settings. See below for details|

@@ -184,3 +187,3 @@ Notes: For explicit cache management capability, a unique session `itemID` (integer) is assigned to a user component as soon as it enters the cache. The `itemID` is retired as soon as the user component is removed from the cache. If the same component is re-introduced into the cache, it is assigned a new session-unique `itemID`.

// operations tracking, called when triggered
changeListsizeCallback, // (newlistsize) - triggered when the listsize changes for any reason
changeListSizeCallback, // (newlistsize) - triggered when the listsize changes for any reason
deleteListCallback, // (reason, deleteList) - data about which items have been deleted from the cache

@@ -208,15 +211,15 @@ repositioningFlagCallback, // (flag) - notification of start (true) or end (false) of rapid repositioning

|callback|parameters:datatypes|notes|
|---|---|---|
|callback function(parameters:datatypes)|notes|
|---|---|
|[_**GET FUNCTIONS**_]|
|functionsCallback|functions: object|the object returned contains `Cradle` functions that the host can call directly. This is the API. `functionsCallback` is called once at startup. See below for details|
|functionsCallback(functions: object)|the object returned contains `Cradle` functions that the host can call directly. This is the API. `functionsCallback` is called once at startup. See below for details|
|[_**TRACK INDEXES**_]|
|referenceIndexCallback|index: integer, location: string, cradleState: string|location can be 'setCradleContent', 'updateCradleContent'. Keeps the host up to date on the index number adjacent to the `Cradle` axis, and the state change that triggered the update|
|repositioningIndexCallback|index: integer|the current index during repositioning. Useful for feedback to user when host sets `useScrollTracker` property to false|
|preloadIndexCallback|index: integer|during a preload operation, this stream gives the index number being preloaded|
|itemExceptionCallback|index: integer, itemID: integer, returnvalue: any, location: string, error: Error|triggered whenever getItem does not return a valid React component|
|referenceIndexCallback(index: integer, location: string, cradleState: string)|location can be 'setCradleContent', 'updateCradleContent'. Keeps the host up to date on the index number adjacent to the `Cradle` axis, and the state change that triggered the update|
|repositioningIndexCallback(index: integer)|the current index during repositioning. Useful for feedback to user when host sets `useScrollTracker` property to false|
|preloadIndexCallback(index: integer)|during a preload operation, this stream gives the index number being preloaded|
|itemExceptionCallback(index: integer, itemID: integer, returnvalue: any, location: string, error: Error)|triggered whenever getItem does not return a valid React component|
|[_**TRACK OPERATIONS**_]|
|changeListsizeCallback|newlistsize: integer|notification of a change of list size. Could be from getItem returning null indicating end-of-list, or an API call that results in change of list size|
|deleteListCallback|reason: string, deleteList: array|gives an array of indexes that have been deleted from the cache, and text of the reason|
|repositioningFlagCallback|flag: boolean| called with `true` when repositioning starts, and `false` when repositioning ends. Useful for feedback to user when host sets `useScrollTracker` property to false|
|changeListsizeCallback(newlistsize: integer)|notification of a change of list size. Could be from getItem returning null indicating end-of-list, or an API call that results in change of list size|
|deleteListCallback(reason: string, deleteList: array)|gives an array of indexes that have been deleted from the cache, and text of the reason|
|repositioningFlagCallback(flag: boolean)| called with `true` when repositioning starts, and `false` when repositioning ends. Useful for feedback to user when host sets `useScrollTracker` property to false|

@@ -227,18 +230,22 @@ ### returned API `functions` object

|function|parameters: datatypes|return value: datatype|notes|
|---|---|---|---|
|function(parameters: datatypes):return value: datatype|notes|
|---|---|
|[_**OPERATIONS**_]|
|scrollToIndex|index:integer|_void_|places the requested index item at the top visible row or left visible column of the scroller, depending on orientation|
|setListsize|index:integer|_void_|changes the list size|
|reload|_none_|_void_|clears the cache and reloads the `Cradle` at its current position in the virtual list|
|clearCache|_none_|_void_|clears the cache and the `Cradle` (leaving nothing to display)|
|scrollToIndex(index:integer):_void_|places the requested index item at the top visible row or left visible column of the scroller, depending on orientation|
|setListsize(index:integer):_void_|changes the list size, by adjusting the list range high index. Favour use of `setListRange` instead|
|setListRange(array [lowindex, highindex] \| []):_void_|lowindex must be <= highindex; lowindex and highindex can be positive or negative integers. [] (empty array) creates an empty virtual list|
|prependIndexCount(count:integer):_void_|the number of indexes to expand the start of the virtual list|
|appendIndexCount(count:integer):_void_|the number of indexes to expand the end of the virtual list|
|reload():_void_|clears the cache and reloads the `Cradle` at its current position in the virtual list|
|clearCache():_void_|clears the cache and the `Cradle` (leaving nothing to display)|
|[_**SNAPSHOTS**_]|
|getCacheIndexMap|_none_|map: Map|snapshot of cache index (=key) to itemID (=value) map|
|getCacheItemMap|_none_|map: Map|snapshot of cache itemID (=key) to object (=value) map. Object = {index, component} where component = user component|
|getCradleIndexMap|_none_|map: Map|snapshot of `Cradle` index (=key) to itemID (=value) map|
|getCacheIndexMap():Map|snapshot of cache index (=key) to itemID (=value) map|
|getCacheItemMap():Map|snapshot of cache itemID (=key) to object (=value) map. Object = {index, component} where component = user component|
|getCradleIndexMap(): Map|snapshot of `Cradle` index (=key) to itemID (=value) map|
|getPropertiesSnapshot():object|copy of `scrollerPropertiesRef.current` from scrollerProperties object. See below.|
|[_**CACHE MANAGEMENT**_]|
|insertIndex|index:integer, rangehighindex = integer or null|changeList:array, replaceList:array, removeList:array|can insert a range of indexes. Displaced indexes, and higher indexes, are renumbered. Changes the list size; synchronizes the `Cradle`|
|removeIndex|index:integer, rangehighindex = integer or null|changeList:array, replaceList:array, removeList:array|a range of indexes can be removed. Higher indexes are renumbered. Changes the list size; synchronizes to the `Cradle`|
|moveIndex|toindex:integer, fromindex:integer, fromhighrange = integer or null|processedIndexList:array|a range of indexes can be moved. Displaced and higher indexes are renumbered. Changes the list size; synchronizes to the `Cradle`|
|remapIndexes|changeMap:Map|modifiedIndexList: array,<br />processedIndexList: array,<br />deletedIndexList: array,<br />indexesOfReplacedItemsList: array,<br />deletedOrphanedItemIDList: array,<br />deletedOrphanedIndexList: array,<br />errorEntriesMap: Map,<br />changeMap: Map (same as input parameter)|changeMap is index (=key) to itemID (=value) map. indexes or itemIDs not in the cache are ignored. indexes with values set to `null` are deleted. indexes with values set to `undefined` have their component items replaced. `itemID`s are assigned to the new indexes; synchronizes to the `Cradle`. List size is adjusted as necessary|
|insertIndex(index:integer, rangehighindex: integer \| null):array[changeList:array, replaceList:array, removeList:array]|can insert a range of indexes. Displaced indexes, and higher indexes, are renumbered; virtual list lowindex remains the same. Changes the list size by increasing virtual list highindex; synchronizes the `Cradle`|
|removeIndex(index:integer, rangehighindex:integer \| null):array[changeList:array, replaceList:array, removeList:array]|a range of indexes can be removed. Higher indexes are renumbered; virtual list lowindex remains the same. Changes the list size by decreasing virtual list highindex; synchronizes to the `Cradle`|
|moveIndex(toindex:integer, fromindex:integer, fromhighrange: integer \| null):array[processedIndexList:array]|a range of indexes can be moved. Displaced and higher indexes are renumbered. Changes the list size; synchronizes to the `Cradle`|
|remapIndexes(changeMap:Map):array[<br />modifiedIndexList: array,<br />processedIndexList: array,<br />deletedIndexList: array,<br />indexesOfReplacedItemsList: array,<br />deletedOrphanedItemIDList: array,<br />deletedOrphanedIndexList: array,<br />errorEntriesMap: Map,<br />changeMap: Map] |(return changeMap is the same as input parameter). changeMap is index (=key) to itemID (=value) map. indexes or itemIDs not in the cache are ignored. indexes with values set to `null` are deleted. indexes with values set to `undefined` have their component items replaced. `itemID`s are assigned to the new indexes; synchronizes to the `Cradle`. List size is adjusted as necessary|

@@ -255,16 +262,16 @@ Notes: cache management functions are provided to support drag-n-drop, sorting, and filtering operations.

|property|value|notes|
|property:datatype|value|notes|
|---|---|---|
|showAxis |boolean, default = false |axis can be made visible for debug|
|triggerlineOffset|integer, default = 10| distance from cell head or tail for content shifts above/below axis|
|VIEWPORT_RESIZE_TIMEOUT|integer, default = 250|milliseconds before the Viewport resizing state is cleared|
|ONAFTERSCROLL_TIMEOUT|integer, default = 100|milliseconds after last scroll event before onAfter scroll event is fired|
|IDLECALLBACK_TIMEOUT|integer, default = 175|milliseconds timeout for requestIdleCallback|
|VARIABLE_MEASUREMENTS_TIMEOUT|integer, default = 250|milliseconds to allow setCradleContent changes to render before being measured for 'variable' layout|
|CACHE_PARTITION_SIZE|integer, default = 30|the cache is partitioned for performance reasons|
|MAX_CACHE_OVER_RUN|number, default = 1.5|max streaming cache size over-run (while scrolling) as ratio to cacheMax|
|showAxis:boolean | default = false |axis can be made visible for debug|
|triggerlineOffset:integer| default = 10| distance from cell head or tail for content shifts above/below axis|
|VIEWPORT_RESIZE_TIMEOUT:integer| default = 250|milliseconds before the Viewport resizing state is cleared|
|ONAFTERSCROLL_TIMEOUT:integer| default = 100|milliseconds after last scroll event before onAfter scroll event is fired|
|IDLECALLBACK_TIMEOUT:integer| default = 175|milliseconds timeout for requestIdleCallback|
|VARIABLE_MEASUREMENTS_TIMEOUT:integer| default = 250|milliseconds to allow setCradleContent changes to render before being measured for 'variable' layout|
|CACHE_PARTITION_SIZE:integer| default = 30|the cache is partitioned for performance reasons|
|MAX_CACHE_OVER_RUN:number| default = 1.5|max streaming cache size over-run (while scrolling) as ratio to cacheMax|
### `scrollerProperties` object
Cell components can get access to current RIGS properties, by requesting the scrollerProperties object.
Cell components can get access to dynamically updated parent RIGS properties, by requesting the scrollerProperties object.

@@ -277,3 +284,3 @@ The `scrollerProperties` object is requested by user components by initializing a `scrollerProperties` component property to `null`. The property is then recognized by RIGS and set to the scrollerProperties object by the system on loading of the component to a CellFrame.

{
cellFrameDataRef,
cellFramePropertiesRef,
scrollerPropertiesRef

@@ -285,3 +292,3 @@ }

The `cellFrameDataRef.current` object contains two properties:
The `cellFramePropertiesRef.current` object is instantiated only when a component is instantiated in the cradle. It contains two properties:

@@ -299,6 +306,35 @@ ~~~typescript

It also contains the _crosscount_ property, which is calculated interrnally, and the following properties, which may have been altered from the source values by the scroller:
It also contains _scrollerID_, the internal session id (integer) of the current scroller, for debug purposes.
_runwayRowcount, listsize_
Finally, it contains two objects with bundled properties: _virtualListProps_ and _cradleContentProps_.
_virtualListProps_ is an object with the following properties:
```
{
size, // the length (number of virtual cells) of the virtual list
range, // a two-part array [lowindex,highindex]
lowindex, // the virtual list low index
highindex, // the virtual list high index
baserowblanks, // cell offset count in the first row
endrowblanks, // blank cells at the end of the last row
crosscount, // number of cells perpendicular to the orientation
rowcount, // number of rows in virtual list
rowshift, // row shift from zero to accommodate lowindex
}
```
_cradleContentProps_ is an object with the following properties:
```
{
cradleRowcount, // number of rows in the cradle (including any blank cells)
viewportRowcount, // number of full rows that can be shown in the viewport
runwayRowcount, // calculated current extra leading and trailing cell rows beyond the viewport boundary
SOL, // true or false, at start of virtual list in the cradle
EOL, // true or false, at end of virtual list in the cradle
lowindex, // of cells in the cradle
highindex, // of cells in the cradle
axisReferenceIndex, // the first index of the tail grid
size, // count of cells in the cradle
}
```
# Restoring scroll positions coming out of cache

@@ -305,0 +341,0 @@

Sorry, the diff of this file is too big to display

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc