Key Technologies

RIGS uses these key technologies:

• CSS grid
• React hooks
• React (reverse) portals
• IntersectionObserver
• ResizeObserver
• requestIdleCallback
• react-dnd

Therefore RIGS is best suited for modern browsers.

Architecture

Notes: The Cradle is kept in view of the Viewport, such that the axis is always near the top or left of the Viewport (depending on vertical or horizontal orientation). There are two CSS grids in the Cradle, one on each side of the axis. As CellFrames are added to or removed from the grids, the grid on the top or left expands toward or contracts away from the top or left of the Scrollblock (depending on orientation), and the grid on the bottom or right expands toward or contracts away from the bottom or right of the Scrollblock.

CellFrames display individual user components. CellFrames are created and destroyed on a rolling basis as the Cradle re-configures and moves around the Scrollblock to stay in view, but user components are maintained in the internal cache until they go out of scope. New CellFrames fetch user components from the internal cache (portals in the React virtual DOM) or from the host through the user-supplied getItemPack function, as needed.

Not shown are two triggerlines (0 width or height divs, depending on orientation) which straddle the top or left edge of the Viewport. Whenever one of these triggerlines crosses the Viewport edge (through scrolling), an IntersectionObserver sends an interrupt to the Cradle to update its content and configuration. Triggerlines are located in the last CellFrame of the head grid, unless the scroller is at the very top of its list, in which case the triggerlines are located in the first CellFrame of the tail grid.

Usage

This is the minimum configuration.

1import Scroller from 'react-infinite-grid-scroller'
2
3// ...
4
5const lowindex = -50, highindex = 50 // random range values
6
7<div style = { containerstyle }>
8  <Scroller 
9      cellHeight = { cellHeight }
10      cellWidth = { cellWidth }
11      startingListRange = { [lowindex, highindex] } // this constitutes the virtual list
12      getItemPack = { getItemPack } // a function called by RIGS to obtain a specified user component by index number
13  />
14</div>

See below for drag and drop configuration.

The scroller's highest level component, the Viewport, is a div with position:absolute, and inset:0, so the host container should be styled accordingly.

Note that scroller-generated elements show a data-type attribute in browser inspectors (eg. 'viewport').

User components loaded to CellFrames are placed in a data-type = 'contentenvelope' div. In 'uniform' layout this has position:absolute and inset:0. In 'variable' layout it has width:100% and max-height = cellHeight for 'vertical' orientation, and height:100% and max-width = cellWidth for 'horizontal' orientation. These elements allow overflow, but the user components should have overflow:hidden as appropriate.

See the "Content Types" section of the demodata.tsx module of the demo site for more code examples.

Table of properties

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.

The itemID for a user component is given to the host with the getItemPack call to obtain the component, so that the host can track the user component in the cache. If the user component is assigned to a new index number (see the returned function object cache management section below) the host will still be able to track the user component with the itemID.

The host can track removal of a user component and its itemID from the cache through tracking its associated index removal through the deleteListCallback return values, and the return values from cache management functions. These feedback mechanisms also return the host's item profile object for further identification. See callback documentation below.

Most of the time the itemID can be ignored.

Also, note that the cache is reloaded with a new getItemPack function.

The styles object

Create a style object for each of the elements you want to modify. The styles are not screened, though the RIGS essential styles pre-empt user styles. Be careful to only include "passive" styles (like color, backgroundColor) so as not to confuse the scroller. Do not add structural items like borders, padding etc.

1const styles = {
2  viewport: {}, 
3  scrollblock: {}, 
4  cradle: {},
5  scrolltracker: {},
6  placeholderframe: {},
7  placeholderliner: {},
8  placeholdererrorframe: {},
9  placeholdererrorliner: {},
10  dndDragIcon: {},
11  dndHighlights:{ // provide a color string for any you want to change
12    source, // default "darkorange"
13    target, // default "black"
14    dropped, // default "darkorange"
15    scroller, // default "red", canDrop but not isOver scroller
16    scrolltab, // default "brown", also used for isOver and canDrop scroller
17  },

You may want to add overscrollBehavior:'none' to the top level viewport styles to prevent inadvertent reloading of your app in certain browsers when users scroll past the top of a vertical list. Also note that dndDragIcon needs zIndex to be at least 1.

The scrolltracker is the small rectangular component that appears at the top left of the viewport when the list is being rapidly repositioned. The scrolltracker shows the user the current virtual position (index + 1) and total listsize during the repositioning process.

The placeholder styles are applied only to the default placeholder.

The placeholderMessages object

Replace any of the default messages used by the placeholder.

1const placeholderMessages = {
2    loading:'(loading...)',
3    retrieving:'(retrieving from cache)',
4    undefined:'host returned "undefined"', // displayed, and returned with itemExceptionCallback
5    invalid:'invalid React element', // displayed, and returned with itemExceptionCallback
6}

The callbacks object

Callbacks are host-defined closure functions which RIGS calls to provide data back to the host. RIGS returns data by setting the arguments of the callbacks. Include only the callbacks in the callbacks object that you want RIGS to use. The following callbacks are recognized by RIGS:

1const callbacks = {
2
3     // called at setup...
4     functionsCallback, // (functions) - get an object that has api functions
5     
6     // index tracking, called when triggered...
7     dragDropTransferCallback, // (fromScrollerID, fromIndex, toScrollerID, toIndex, context) - information about successful drop
8     referenceIndexCallback, // (index, context) - change of index adjacent to the axis
9     repositioningIndexCallback, // (index, context) - current virtual index number during rapid repositioning
10     preloadIndexCallback, // (index, context) - current index being preloaded
11     itemExceptionCallback, // (index, context) - details about failed getItemPack calls
12
13     // operations tracking, called when triggered
14     changeListRangeCallback, // (listrange, context) two part array lowindex, highindex 
15     deleteListCallback, // (deleteList, context) - data about which items have been deleted from the cache
16     boundaryCallback, // (position, index, context) - position is "SOL" or "EOL", index is the corresponding boundary index
17     repositioningFlagCallback, // (flag, context) - notification of start (true) or end (false) of rapid repositioning,
18}

An example of a callback closure (functionsCallback):

1const scrollerFunctionsRef = useRef(null)
2
3const functionsCallback = (functions) => {
4
5    scrollerFunctionsRef.current = functions // assign the returned functions object to a local Ref
6
7}
8
9//...
10
11scrollerFunctionsRef.current.scrollToIndex(targetIndex)

Details about the callbacks:

The returned API functions object

Details about the functions returned in an object by functionsCallback.

Functions with no return values:

Functions with return values

Notes: cache management functions are provided to support drag-n-drop, sorting, and filtering operations.

Cache management functions operate on indexes and itemIDs in the cache, and generally ignore indexes and itemIDs that are not in the cache. They synchronize Cradle cell content as appropriate.

This is a sparse in-memory cache, and indexes in the cache are not guaranteed to be contiguous.

The technical object

These properties would rarely be changed.

The cell component's acquired scrollerContext property

Cell components can get access to dynamically updated parent RIGS properties, by requesting the scrollerContext object.

The scrollerContext object is requested by host components by initializing a scrollerContext component property to null. The property is then recognized by RIGS and set to the scrollerContext object by the system on loading of the component to a CellFrame. Here is the internal code that does this:

1if (usercontent.props.hasOwnProperty('scrollerContext')) {
2  component = React.cloneElement(usercontent, {scrollerContext})
3} else {
4  component = usercontent
5}

The scrollerContext object contains two properties:

1{
2  cell,
3  scroller,
4}

Each of these is a reference object, with values found in propertyRef.current.

The cell.current object is instantiated only when a component is instantiated in the Cradle. It contains two properties:

1{
2  itemID, // session cache itemID
3  index, // place in virtual list
4}

The scroller.current object contains the following properties, which are identical to the properties set for the scroller (they are passed through):

orientation, cellHeight, cellWidth, cellMinHeight, cellMinWidth, layout, cache, cacheMax, startingIndex

It also contains scrollerID, the internal session id (integer) of the current scroller, as well as dndInstalled, and dndEnabled.

Finally, it contains four objects with bundled properties: virtualListProps, cradleContentProps, gapProps, and paddingProps.

virtualListProps is an object with the following properties:

1{
2   size, // the length (number of virtual cells) of the virtual list
3   range, // a two-part array [lowindex,highindex]
4   lowindex, // the virtual list low index
5   highindex, // the virtual list high index
6   baserowblanks, // cell offset count in the first row
7   endrowblanks, // blank cells at the end of the last row
8   crosscount, // number of cells perpendicular to the orientation
9   rowcount, // number of rows in virtual list
10   rowshift, // row shift from zero to accommodate lowindex
11}

cradleContentProps is an object with the following properties:

1{
2   cradleRowcount, // number of rows in the cradle (including any blank cells)
3   viewportRowcount, // number of full rows that can be shown in the viewport
4   runwayRowcount, // calculated current extra leading and trailing cell rows beyond the viewport boundary
5   SOL, // true or false, at start of virtual list in the cradle
6   EOL, // true or false, at end of virtual list in the cradle
7   lowindex, // of cells in the cradle
8   highindex, // of cells in the cradle
9   axisReferenceIndex, // the first index of the tail grid
10   size, // count of cells in the cradle
11}

gapProps is an object with the following properties:

1{
2  CSS, // the CSS to be applied to the grid
3  column, // column gap
4  row, // row gap
5  list, // [column, row]
6  original, // normalized parameter value
7  source, // original parameter value
8}

paddingProps is an object with the following properties:

1{
2  CSS, the CSS to be applied to the Scrollblock
3  top, // top padding
4  right, // right padding
5  bottom, // bottom padding
6  left, // left padding
7  list, // [top, right, bottom, left]
8  original, // normalized parameter value
9  source, // original parameter value
10}

Overview

The following are the basic steps to implement drag and drop on RIGS. Note that RIGS drags and drops its CellFrame components. The user content (React components) come along for the ride. The following assumes multiple sub-scrollers, although using just the main scroller is fine.

• design a type system for scroller items and scrollers. Scroller item types must be included in scroller accept type lists
• install the dnd system by invoking the specialized RigsDnd root component
• provide every scroller and subscroller with a scroller dndOptions object as a scroller parameter. Also providing a host-defined scroller profile object is highly recommended, for use during interaction with the system
• provide every item fetched using getItemPack with a cell dndOptions property through the returned object. Also providing items with a host-defined cell profile object is highly recommended, for use during interaction with the system. (Remember that subscrollers require both a direct scroller dndOptions property, and a cell dndOptions object returned by getItemPack. Sub-scrollers are both item repositories, and part of scroller items themselves).
• prepare to respond to specialized 'dndFetchRequest' getItemPack requests, which are for dropped copies of existing items, or replacements for dropped moved items that have gone out of scope as the result of scrolling during the drag activity
• request a scrollerContext object from the host scroller for each of your content items so that the items will be aware of dnd status in their host scrollers for layout purposes (see scrollerContext section)
• design and implement accommodating layout features on your cell components
• design and implement dnd configuration options as required
• create a getDropEffect function if needed, and pass this to the RigsDnd root component
• creat a nativeTypeCallback function and provide it to scroller dndOptions for handling of native type (file, url or text) drag and drop
• track drag and drop transfers with dragDropTransferCallback if desired

See below for details.

Installation

To install drag and drop ('dnd') capability,

1. first invoke the RigsDnd component (instead of the default component) for the root of the RIGS tree to install the dnd Provider. This can only be done once per environment. For embedded lists (sub-scrollers), use the default RIGS component.

1import  { RigsDnd as Scroller } from 'react-infinite-grid-scroller'
2...
3<div style = { containerstyle }>
4  <Scroller 
5      cellHeight = { cellHeight }
6      cellWidth = { cellWidth }
7      startingListRange = { [lowindex, highindex] } // this constitutes the virtual list
8      getItemPack = { getItemPack } // a function called by RIGS to obtain a specified user component by index number
9      dndOptions = { dndOptions } // required for both the root instance and all child RIGS instances
10  />
11</div>

2. dndOptions is a required property for all scrollers when dnd is enabled. It must include an accept property, with an array of accepted dnd content types (strings or Symbols). For the root scroller it may also include a master property. A complete list here:

1const dndOptions = {
2  accept:['type1','type2','type3',...], // required for all participating RIGS scrollers - any number of string (or Symbol) identifiers
3  master:{enabled}, // optional, default true, for root `RigsDnd` component only. Serves as default for scroller enabled setting.
4  enabled, // optional for all participating scrollers, default set by master.enabled
5  dropEffect, // optional. the prescribed value ('move' or 'copy') for dragged scroller items; can be overridden by getDropEffect.
6    // undefined dropEffect means default = 'move', posibly modified to 'copy' by pressing the altKey on desktop systems
7  showScrollTabs, // default = true. When set to false, suppresses the scroll tabs on the scroller during drag.
8  nativeTypeCallback, // a host provided function to return the result of a native type drag and drop. See below.
9}

3. When dnd is enabled, all data packages returned to RIGS with getItemPack must include a dndOptions object (together with the component and profile properties). The dndOptions object must contain a type property with a string that matches one of the accept array strings of its containing scroller, and a dragText property with text that will be shown in the drag image for the item.

1// in host getItemPack function
2...
3return {
4  component, // a valid React component, or promise of a component
5  dndOptions:{
6    type, // string (or Symbol) required to match one of the list accept values
7    dragText, // required. Displayed to user in the drag image for the component
8  }
9  profile, // recommended. Simple object created by host, returned to host for item identification in various contexts
10}

RIGS does not check for matches of type values returned with getItemPack, with accept values sent to scrollers via the dndOptions scroller property.

With dnd enabled, the context parameter of the getItemPack function sent to the host will include the accept list of the enclosing scroller, for convenience.

The canDrop and dropEffect properties, and the getDropEffect function

canDrop is an internal property controlled by react-dnd, by comparing the dragged item's type property (from the cell dndOptions property) to the list of accept values (from the scroller dndOptions property) of the target scroller. If a match is found, then react-dnd signals that the item can be dropped on the scroller.

canDrop can be further constrained by the host-provided getDropEffect function, by returning 'none'.

The internal dropEffect property for a dragged item can be set by the dropEffect property of the dndOptions of the source scroller. If this is undefined, then it becomes the default 'move' operation, or the 'copy' operation when the altKey is pressed by the user on most browsers.

dropEffect can be further constrained by the return value of the host-provided function getDropEffect (see Scroller Properties above). getDropEffect (if provided by the host) is called by RIGS whenever the drag location crosses into a scroller for which the internal isOver and canDrop properties are both true. This function has three parameters: sourceScrollerID (the scrollerID from the source of the drag), targetScrollerID (the scrollerID from the target of the drag), and context. Here are the properties of the context parameter:

1const context = {
2  sourceDndOptions:{ // taken from the source scroller
3    accept, // the array of strings signifying the types of content items accepted by drop
4    enabled, // the current state of dnd for the scroller
5    dropEffect // an optional prescribed value for use by contained list items
6  },
7  sourceProfile, // a host-provided simple object to assist with identification of the scroller
8  targetDndOptions:{
9    ... // same as sourceDndOptions, but taken from the target scroller
10  },
11  targetProfile, // similar to sourceProfile
12  itemData:{ // identifying information of the current item being dragged
13    itemID, // the itemID assigned to the content item by RIGA
14    index, // the item's logical position in the source scroller
15    profile, // host provided simple object to assist with item identification
16    dndOptions: {, // taken from getItemPack function
17      type, // the type of the item, matches one of the accept items in both the source and target scroller
18      dragText, // the text shown in the dragBar when the item is being dragged
19    } 
20    dropEffect, // the current internally prescribed dropEffect taken from scroller settings and altKey setting if any
21  }
22}

The host can return 'move', 'copy', 'none', or undefined from the getDropEffect function. 'none' prevents a drop, 'move' and 'copy' override the item's dropEffect value, and undefined yields to the value of the scroller's calculated dropEffect property.

The 'dndFetchRequest' specialized getItemPack call

When the user drags and drops an item which exists in the RIGS cache, and with a 'move' dropEffect, then RIGS takes care of the data transfer itself.

However, if the drop involves a 'copy', then the host has to supply what it considers to be a copy of the item (a RIGS cache item can only be used for one display instance). Also, if the item has been moved, but has gone out of scope as the result of scrolling during the drag operation and therefore removed from the cache, then a fresh instance of the moved item has to be obtained from the host. In those cases, RIGS sends out a specialized getItemPack(index, itemID, context) call with sufficient information for the host to respond appropriately. In this case, the context parameter contains the following:

1const context = {
2  contextType:'dndFetchRequest', // identifiaction of the specialized request
3  accept, // the accept list of the target scroller
4  scrollerID, // the target scroller ID
5  scrollerProfile, // the target scroller profile, as provided by the host as the scroller property
6  item:{
7    scrollerID, // the source scrollerID
8    index, // the item index at source
9    itemID, // the itemID at the start of drag (now to be replaced)
10    profile, // the item profile as passed to RIGS through the original instantiating getItemPack response (could include host item ID)
11    dndOptions, // the original item dndOptions from getItemPack
12    dropEffect, // the final dropEffect at the point of drop
13  },
14}

The native type drag and drop (file, url, and text)

On desktop systems, RIGS scrollers can accept native types (file, url, and text).

To accomplish this, first add the following to the scroller dndOptions.accept array:['__NATIVE_FILE__', '__NATIVE_URL__', '__NATIVE_TEXT__']

Then provide a scroller dndOptions.nativeTypeCallback function, which RIGS uses to return the result of the drag and drop for further processing. The nativeTypeCallback has two parameters, item and context. item is data returned by react-dnd for further processing, and context is provided by RIGS for more information, as follows:

1item: { // provided by system for further processing
2  dataTransfer,
3  files,
4  items,
5}
6
7context: { // provided by RIGS for further information
8  contextType:'nativeType',
9  scrollerID, // current scrollerID
10  internalDropResult: {
11    dataType, // location type of the drop - 'cellframe' or 'viewport'
12    dropEffect, // the computed drop effect at the time of drop
13    target, // target data - scrollerID, and itemID and index if dataType is 'cellframe'
14  },
15  itemType, // the native type
16  whitespaceposition, // 'head' or 'tail' for internaleDropResult.dataType == 'viewport' (ie. whitespace)
17  listrange, // the current scroller listrange [lowindex, highindex]
18}

Layout

RIGS shows a drag icon for draggable items at the top left of each CellFrame. Since this icon can overlay some of the content of the host provided content, the component may want to move this content out of the way of the drag icon when it is present. Here is how that can be done.

First, obtain a scrollerContext object from the host scroller. See the scrollerContext section for details.

Then code something like this.

1const isDnd = scrollerContext?.scroller.current.dndEnabled
2
3const float = useMemo(() => {
4  return <div 
5    style = {{float:'left', height: '28px', width:'34px'}} 
6    data-type = 'dnd-float'
7  />
8},[])
9
10return <div 
11  ... // properties
12>
13  {isDnd && float}
14  ... // content
15</div>

Configuration

Drag and drop can be enabled or disabled for individual scrollers, by setting the scroller's dndOptions.enabled property. If the scroller's enabled property is undefined, then it is set to the RigsDnd component's dndOptions.master.enabled property (which is itself set to default true if undefined. The enabled property can be set at runtime.

This presents a number of options. For example the user can set the dnd capability of a scroller themselves, something like this:

1const dndOptionsRef = useRef(dndOptions) // for use elsewhere, below
2dndOptionsRef.current = dndOptions
3...
4const checkdnd = (event:React.ChangeEvent) => {
5  const
6    target = event.target as HTMLInputElement,
7    isChecked = target.checked
8  dndOptionsRef.current.enabled = isChecked
9  setSubscrollerState('revised')
10}
11
12return ...
13<FormControl borderTop = '1px' style = {{clear:'left'}}>
14  <Checkbox 
15    isChecked = {dndOptions.current.enabled} 
16    size = 'sm'
17    mt = {2}
18    onChange = {checkdnd}
19  >
20    Drag and drop
21  </Checkbox>
22</FormControl>}
23...
24<Scroller
25  ...
26  dndOptions = {dndOptionsRef.current}
27  ...
28/>

Or you can create a global React context, say const DndEnabledContext = React.createContext(true). Then control that value through a global checkbox control. Finally, in your scroller component:

1const dndEnabledContext = useContext( DndEnabledContext )
2...
3useEffect(()=>{
4
5  dndOptionsRef.current.enabled = dndEnabledContext
6  setSubscrollerState('revised')
7
8},[dndEnabledContext])
9...

The combination of the local and global settings would allow the user much flexibility in terms of how to use drag and drop. This could be particularly useful in settings involving dozens of subscrollers.

Performance

If there are dozens of subscrollers on screen (say by zooming out to 50%), then performance of drag and drop (notably for the drag icon) can degrade owing to the pub/sub system of react-dnd. One way of dealing with this is to disable all drag and drop (see Configuration above), and let the user selectively enable drag and drop for the scrollers that they want to work with. That way, performance is quite good.

This is only of concern if your cell components support scrolling.

RIGS loads components into a cache (React portals), and into Cradle cells from there. Moreover RIGS moves components from one side of the (hidden) axis to the other through the cache during scrolling. Plus caching can be extended (by RIGS property settings) beyond the Cradle. So going into and out of cache happens a lot for components. While in cache, the component elements have their scrollTop, scrollLeft, width, and height values set to 0 by browsers. width and height values are restored by browsers when moved back into the visible DOM area, but scroll positions have to be manually restored.

Here is one way of restoring scroll positions. Basically, save scroll positions on an ongoing basis, detect going into cache when width and height values are both zero, and detect coming out of cache when width and height are no longer zero. When coming out of cache, restore the saved scroll positions.

This code is Typescript, in a function component.

1    // ------------------------[ handle scroll position recovery ]---------------------
2
3    // define required data repo
4    const scrollerElementRef = useRef<any>(null),
5        scrollPositionsRef = useRef({scrollTop:0, scrollLeft:0}),
6        wasCachedRef = useRef(false)
7
8    // define the scroll event handler - save scroll positions
9    const scrollerEventHandler = (event:React.UIEvent<HTMLElement>) => {
10
11        const scrollerElement = event.currentTarget
12
13        // save scroll positions if the scroller element is not cached
14        if (!(!scrollerElement.offsetHeight && !scrollerElement.offsetWidth)) {
15
16            const scrollPositions = scrollPositionsRef.current
17
18            scrollPositions.scrollTop = scrollerElement.scrollTop
19            scrollPositions.scrollLeft = scrollerElement.scrollLeft
20
21        }
22
23    }
24
25    // register the scroll event handler
26    useEffect( () => {
27
28        const scrollerElement = scrollerElementRef.current
29
30        scrollerElement.addEventListener('scroll', scrollerEventHandler)
31
32        // unmount
33        return () => {
34            scrollerElement.removeEventListener('scroll', scrollerEventHandler)
35        }
36
37    },[])
38
39    // define the cache sentinel - restore scroll positions
40    const cacheSentinel = () => {
41        const scrollerElement = scrollerElementRef.current
42
43        if (!scrollerElement) return // first iteration
44
45        const isCached = (!scrollerElement.offsetWidth && !scrollerElement.offsetHeight) // zero values == cached
46
47        if (isCached != wasCachedRef.current) { // there's been a change
48
49            wasCachedRef.current = isCached
50
51            if (!isCached) { // restore scroll positions
52
53                const {scrollTop, scrollLeft} = scrollPositionsRef.current
54
55                scrollerElement.scrollTop = scrollTop
56                scrollerElement.scrollLeft = scrollLeft
57
58            }
59
60        }
61
62    }
63
64    // run the cache sentinel on every iteration
65    cacheSentinel()
66
67    // register the scroller element through the ref attribute
68    return <div ref = {scrollerElementRef} style = {scrollerstyles}>
69        {scrollercontent}
70    </div>