pologram

A React component for scolling over huge list with windowing technique

Install

With npm:

npm install --save @cascadium/pologram

Or with yarn:

yarn add @cascadium/pologram

Usage

// You need to import some predefined styles first. Of course
// you may override it by adding inline styles.
import '@cascadium/pologram/dist/index.modern.css';

// ...

const pologram = <Pologram {...{
  itemData,
  rowRenderer, 
  topWidgetRenderer,
  height,
  buffer,
}} />

where:

• itemData: the list of data to be rendered
• rowRenderer: the React component that renders the row.
• topWidgetRenderer: the React component that renders a widget sticky to the top of the list.
• height: height of the view, must be specified
• buffer: the number of rows to be rendered ahead of visible ones, so that to prevent rendering AFTER moving into visible area (which makes the table looking 'flashy' when scrolling fast).

the rowRenderer and topWidgetRenderer will be explained in the following sections.

The Row Renderer

Since Pologram is derived from a personal project, it doesn't have strict type check, an will not look into the implementation of row renderer, however improper row renderer will cause unexpected behavior. Here is an example of row renderer implementation. You may also find it in the example of source code.

forwardRef(({index, data, style}, ref) => {

  const outerStyle = {
    width:'100%',
    ...style
  }

  const innerStyle = {
    width: '100%',
    display:'flex',
    alignItems: 'center',
  }

  return <div style={outerStyle}>
    <div style={innerStyle} ref={ref}>
      <InnerElem {...data[index]}/>
    </div>
  </div>
});

1. The row renderer is wrapped by a component that measures the rendered DOM (called Measurer if you look into the code). It needs the ref of the inner div element. Thus the row renderer must pass the ref out. If your row render is a functional component, then it should be wrapped with forwardRef.

2. The height of the element with innerStyle will be measured, which determines the position of rows to be rendered. The inner style doesn't have to be inline style, it can also be specified via CSS.

3. The calculated position of the row will be assigned back to the element with the style property, and finally assigned to the row via outerStyle. The style contains four CSS property, which are top, bottom and height. You may add other CSS properties to the inline style, or refer some style with className, but always remember to use the style passed into, and never mess it up. Otherwise the rows will not show properly, or never render at all.

4. The data is the whole list. The record data to be rendered can be referenced by index of the data. We use this instead of merely passing the record ( the content of data[index]) is that you may need to interact with other rows in the current row. Moreover, when you pass an object into a React component as prop, React will make it immutable by Object.freeze it. Passing the whole data table avoids the single record being frozen.

(Personally I don't accept the idea of making everything immutable. The data table could be huge or could contain complex shape, returning a new object for each operation is counterintuitive and excessively costy)

License

WTFPL marvintau