feat(currentLength): replace itemsLength with more explicit currentLength prop name

Warns when using itemsLength instead of currentLength.

Some users had difficulties with the meaning of the former prop name and
interpreted it as totalLength which led them to misuse the component's awaitMore prop.

Author: Luis Merino

README.md

@@ -49,7 +49,7 @@ export default class MyList extends React.Component {
 
     render() {
         return (
-            <List itemsLength={1000} itemsRenderer={this.itemsRenderer}>
+            <List currentLength={1000} itemsRenderer={this.itemsRenderer}>
                 {this.itemRenderer}
             </List>
         );
@@ -85,7 +85,7 @@ Provided an `itemsRenderer` prop you must attach the `ref` argument to your scro
 
 This element specifies `overflow: auto|scroll` and it'll become the `IntersectionObserver root`. If the `overflow` property isn't found, then `window` will be used as the `root` instead.
 
-The `<sentinel />` element is by default detached from the list when the current size reaches the available length, unless you're using `awaitMore`. In case your list is in memory and you rely on the list for incremental rendering only, the default detaching behavior suffices. If you're loading items asynchoronously on-demand, make sure to switch `awaitMore` once you reach the total `itemsLength`.
+The `<sentinel />` element is by default detached from the list when the current size reaches the available length, unless you're using `awaitMore`. In case your list is in memory and you rely on the list for incremental rendering only, the default detaching behavior suffices. If you're loading items asynchoronously on-demand, make sure to switch `awaitMore` once you reach the total length.
 
 ### FAQ
 
@@ -113,7 +113,7 @@ The prop `pageSize` is `10` by default, so make sure you're not falling short on
 
 - **itemsRenderer**: `(items: Array<React.Element<*>>, ref: HTMLElement) => React.Element<*>`
 
-- **itemsLength**: `number` | default: `0` (number of renderable items)
+- **currentLength**: `number` | default: `0` (number of renderable items)
 
 - **awaitMore**: `bool` | default: `false` (if true keeps the sentinel from detaching)
 

docs/docs/components/AsyncList/index.js

@@ -59,7 +59,7 @@ export default class extends React.Component {
                 this.feedList(repos.filter(repo => repo.fork === false && repo.language));
             })
             .catch(err => {
-        console.error(err); // eslint-disable-line
+                console.error(err); // eslint-disable-line
                 this.feedList([]);
             });
     };
@@ -89,7 +89,7 @@ export default class extends React.Component {
                 <List
                     awaitMore={this.state.awaitMore}
                     itemsRenderer={this.renderItems}
-                    itemsLength={this.state.repos.length}
+                    currentLength={this.state.repos.length}
                     onIntersection={this.handleLoadMore}
                     pageSize={PAGE_SIZE}
                 >

docs/docs/components/Axis/index.js

@@ -8,4 +8,4 @@ const itemsRenderer = (items, ref) => (
 );
 
 // eslint-disable-next-line react/no-multi-comp
-export default () => <List axis="x" itemsLength={Infinity} itemsRenderer={itemsRenderer} pageSize={40} />;
+export default () => <List axis="x" currentLength={Infinity} itemsRenderer={itemsRenderer} pageSize={40} />;

docs/docs/components/InfiniteList/index.js

@@ -8,4 +8,4 @@ const itemsRenderer = (items, ref) => (
 );
 
 // eslint-disable-next-line react/no-multi-comp
-export default () => <List itemsLength={Infinity} itemsRenderer={itemsRenderer} pageSize={40} />;
+export default () => <List currentLength={Infinity} itemsRenderer={itemsRenderer} pageSize={40} />;

docs/recipes/README.md

@@ -2,7 +2,7 @@
 
 ### Asynchonous Repo List
 
-When the sentinel comes into view, you can use the callback to load data, create the next items, and attach them. For this case we're loading Github repositories with pagination. We assume that we don't know the total `itemsLength` and we'll want to keep fetching until the (unknown) end of the list. The solution here is to pass the prop `awaitMore:bool = true`, so that the sentinel awaits for more items.
+When the sentinel comes into view, you can use the callback to load data, create the next items, and attach them. For this case we're loading Github repositories with pagination. We assume that we don't know the total length and we'll want to keep fetching until the (unknown) end of the list. The solution here is to pass the prop `awaitMore:bool = true`, so that the sentinel awaits for more items.
 
 ```jsx
 import React from 'react';
@@ -67,7 +67,7 @@ export default class extends React.Component {
                 <List
                     awaitMore={this.state.awaitMore}
                     itemsRenderer={this.renderItems}
-                    itemsLength={this.state.repos.length}
+                    currentLength={this.state.repos.length}
                     onIntersection={this.handleLoadMore}
                     pageSize={PAGE_SIZE}
                 >
@@ -79,7 +79,7 @@ export default class extends React.Component {
 }
 ```
 
-If it's possible to get the total `itemsLength` in advance, we won't need `awaitMore` and the `pageSize` will be used to paginate results until we reach the bottom of the list.
+If the total amount of items are prefetched and available, we won't need `awaitMore` and the `pageSize` will be used to paginate results until we reach the bottom of the list.
 
 ### Infinite Synchronous List
 
@@ -88,7 +88,7 @@ import React from 'react';
 import List from '@researchgate/react-intersection-list';
 
 export default () => (
-    <List itemsLength={Infinity}>
+    <List currentLength={Infinity}>
         {(index, key) => <div key={key}>{index}</div>}
     </List>
 );

src/List.js

@@ -11,7 +11,7 @@ export default class List extends React.PureComponent {
         axis: PropTypes.oneOf(['x', 'y']),
         children: PropTypes.func,
         initialIndex: PropTypes.number,
-        itemsLength: PropTypes.number,
+        currentLength: PropTypes.number,
         itemsRenderer: PropTypes.func,
         onIntersection: PropTypes.func,
         pageSize: PropTypes.number,
@@ -22,7 +22,7 @@ export default class List extends React.PureComponent {
         axis: 'y',
         children: (index, key) => <div key={key}>{index}</div>,
         initialIndex: 0,
-        itemsLength: 0,
+        currentLength: 0,
         itemsRenderer: (items, ref) => <div ref={ref}>{items}</div>,
         pageSize: 10,
         threshold: '100px',
@@ -31,8 +31,16 @@ export default class List extends React.PureComponent {
     constructor(props) {
         super(props);
 
+        // eslint-disable-next-line no-undef
+        if (process.env.NODE_ENV !== 'production') {
+            warning(
+                !props.hasOwnProperty('itemsLength'),
+                'itemsLength is deprecated and will be removed in the next major version. Use currentLength instead.',
+            );
+        }
+
         this.state = {
-            size: this.computeSize(props.pageSize, props.itemsLength),
+            size: this.computeSize(props.pageSize, props.currentLength),
         };
 
         this.checkedForIntersection = this.state.size === 0;
@@ -46,20 +54,21 @@ export default class List extends React.PureComponent {
     };
 
     handleUpdate = ({ isIntersecting }) => {
-        const { pageSize, itemsLength, onIntersection, awaitMore } = this.props;
+        const { pageSize, currentLength, onIntersection, awaitMore } = this.props;
         const { size } = this.state;
 
         if (!this.checkedForIntersection) {
             this.checkedForIntersection = true;
             warning(
                 !isIntersecting,
-                'The sentinel detected a viewport with a bigger size than the size of its items. This could lead to detrimental behavior, e.g.: triggering more than one `onIntersection` callback at the start.\n' +
-                    'To prevent this, use either a bigger `pageSize` value or avoid using the prop `awaitMore` initially.',
+                'the sentinel detected a viewport with a bigger size than the size of its items. ' +
+                    'This could lead to detrimental behavior, e.g.: triggering more than one onIntersection callback at the start.\n' +
+                    'To prevent this, use either a bigger `pageSize` value or avoid using the prop awaitMore initially.',
             );
         }
 
         if (isIntersecting) {
-            const nextSize = this.computeSize(size + pageSize, itemsLength);
+            const nextSize = this.computeSize(size + pageSize, currentLength);
             this.setState({ size: nextSize });
 
             if (onIntersection && (!awaitMore || this.awaitIntersection)) {
@@ -71,12 +80,12 @@ export default class List extends React.PureComponent {
         }
     };
 
-    computeSize(pageSize, itemsLength) {
-        return Math.min(pageSize, itemsLength);
+    computeSize(pageSize, currentLength) {
+        return Math.min(pageSize, currentLength);
     }
 
     renderItems() {
-        const { children, itemsRenderer, initialIndex, itemsLength, threshold, axis, awaitMore } = this.props;
+        const { children, itemsRenderer, initialIndex, currentLength, threshold, axis, awaitMore } = this.props;
         const { size } = this.state;
         const items = [];
 
@@ -85,7 +94,7 @@ export default class List extends React.PureComponent {
         }
 
         let sentinel;
-        if (size < itemsLength || awaitMore) {
+        if (size < currentLength || awaitMore) {
             sentinel = (
                 <Sentinel
                     key="sentinel"
@@ -109,9 +118,9 @@ export default class List extends React.PureComponent {
         });
     }
 
-    componentWillReceiveProps({ pageSize, itemsLength }) {
-        if (this.props.pageSize !== pageSize || this.props.itemsLength !== itemsLength) {
-            const nextSize = this.computeSize(this.state.size + pageSize, itemsLength);
+    componentWillReceiveProps({ pageSize, currentLength }) {
+        if (this.props.pageSize !== pageSize || this.props.currentLength !== currentLength) {
+            const nextSize = this.computeSize(this.state.size + pageSize, currentLength);
             this.setState({ size: nextSize });
         }
     }

src/__tests__/List.spec.js

@@ -33,10 +33,16 @@ test('renders without crashing', () => {
     createTree();
 });
 
+test('warns about deprecated `itemsLength` prop', () => {
+    expect(() => createTree({ itemsLength: 10 })).toThrowError(
+        'Warning: itemsLength is deprecated and will be removed in the next major version. Use currentLength instead.',
+    );
+});
+
 describe('children', () => {
     test('receives correct arguments given default props', () => {
         const spy = jest.fn();
-        createTree({ itemsLength: 10, children: spy });
+        createTree({ currentLength: 10, children: spy });
         expect(spy).toHaveBeenCalledTimes(10);
         expect(spy).lastCalledWith(9, 9);
     });
@@ -45,7 +51,7 @@ describe('children', () => {
         const spy = jest.fn();
         createTree({
             initialIndex: 10,
-            itemsLength: 30,
+            currentLength: 30,
             pageSize: 15,
             children: spy,
         });
@@ -56,52 +62,52 @@ describe('children', () => {
 
 describe('render items', () => {
     test('sentinel observes if available items in view', () => {
-        const json = createTree({ itemsLength: 10, pageSize: 5 }).toJSON();
+        const json = createTree({ currentLength: 10, pageSize: 5 }).toJSON();
         const children = json.children;
         expect(children.length).toBe(6);
         expect(children[children.length - 1].type).toBe('sentinel');
     });
 
     test('sentinel gone if no items available in view', () => {
-        const json = createTree({ itemsLength: 5, pageSize: 5 }).toJSON();
+        const json = createTree({ currentLength: 5, pageSize: 5 }).toJSON();
         const children = json.children;
         expect(children.length).toBe(5);
         expect(children[children.length - 1].type).toBe('div');
     });
 
-    test('sentinel observes again if `itemsLength` is extended without re-rendering', () => {
-        const tree = createTree({ itemsLength: 5, pageSize: 5 });
+    test('sentinel observes again if `currentLength` is extended without re-rendering', () => {
+        const tree = createTree({ currentLength: 5, pageSize: 5 });
         const spy = jest.spyOn(tree.getInstance(), 'render');
         expect(tree.toJSON().children.length).toBe(5);
-        tree.update(<List pageSize={5} itemsLength={20} />);
+        tree.update(<List pageSize={5} currentLength={20} />);
         expect(tree.toJSON().children.length).toBe(11);
         expect(spy).toHaveBeenCalledTimes(1);
     });
 
     test('sentinel observes again if pageSize is extended without re-rendering', () => {
-        const tree = createTree({ itemsLength: 100, pageSize: 10 });
+        const tree = createTree({ currentLength: 100, pageSize: 10 });
         const spy = jest.spyOn(tree.getInstance(), 'render');
         expect(tree.toJSON().children.length).toBe(11);
-        tree.update(<List itemsLength={100} pageSize={20} />);
+        tree.update(<List currentLength={100} pageSize={20} />);
         expect(tree.toJSON().children.length).toBe(31);
         expect(spy).toHaveBeenCalledTimes(1);
     });
 
-    test('sentinel not present if `itemsLength` updates from zero', () => {
-        const tree = createTree({ itemsLength: 0 });
+    test('sentinel not present if `currentLength` updates from zero', () => {
+        const tree = createTree({ currentLength: 0 });
         const children = tree.toJSON().children;
         expect(children).toBeNull();
-        tree.update(<List itemsLength={8} />);
+        tree.update(<List currentLength={8} />);
         const newChildren = tree.toJSON().children;
         expect(newChildren.length).toBe(8);
         expect(newChildren[newChildren.length - 1].type).toBe('div');
     });
 
-    test('sentinel observes with `awaitMore` bypassing the `itemsLength` check', () => {
-        const tree = createTree({ itemsLength: 5 });
+    test('sentinel observes with `awaitMore` bypassing the `currentLength` check', () => {
+        const tree = createTree({ currentLength: 5 });
         const children = tree.toJSON().children;
         expect(children.length).toBe(5);
-        tree.update(<List itemsLength={5} awaitMore />);
+        tree.update(<List currentLength={5} awaitMore />);
         const newChildren = tree.toJSON().children;
         expect(newChildren.length).toBe(6);
         expect(newChildren[newChildren.length - 1].type).toBe('sentinel');
@@ -110,52 +116,52 @@ describe('render items', () => {
 
 describe('setRootNode', () => {
     test('ref callback sets root node', () => {
-        createTree({ itemsLength: 20 });
+        createTree({ currentLength: 20 });
         expect(mockCallback).toBeCalledWith(target);
     });
 
     test('ref callback does sets root node if unmounting', () => {
-        renderer.create(<List itemsLength={20} />, {
+        renderer.create(<List currentLength={20} />, {
             createNodeMock: () => undefined,
         });
         expect(mockCallback).not.toBeCalled();
     });
 
     test('ref callback does sets root node without sentinel', () => {
-        const tree = createTree({ itemsLength: 10 });
+        const tree = createTree({ currentLength: 10 });
         expect(tree.getInstance().setRootNode).toBeUndefined();
     });
 
     test('ref callback sets a null root if it does not have overflow', () => {
         window.getComputedStyle = jest.fn(() => ({
             overflowY: 'visible',
         }));
-        createTree({ itemsLength: 20 });
+        createTree({ currentLength: 20 });
         expect(mockCallback).toBeCalledWith(null);
     });
 });
 
 describe('handleUpdate', () => {
     test('throws once if sentinel intersects items on mount', () => {
-        const instance = createTree({ itemsLength: 10 }).getInstance();
+        const instance = createTree({ currentLength: 10 }).getInstance();
         expect(() => instance.handleUpdate({ isIntersecting: true })).toThrowErrorMatchingSnapshot();
         expect(() => instance.handleUpdate({ isIntersecting: true })).not.toThrow();
         expect(() =>
-            createTree({ itemsLength: 0 })
+            createTree({ currentLength: 0 })
                 .getInstance()
                 .handleUpdate({ isIntersecting: true }),
         ).not.toThrow();
     });
 
     test('sets next size value computed into `pageSize`', () => {
-        const instance = createTree({ itemsLength: 20 }).getInstance();
+        const instance = createTree({ currentLength: 20 }).getInstance();
         instance.handleUpdate({ isIntersecting: false });
         instance.handleUpdate({ isIntersecting: true });
         expect(instance.state.size).toBe(20);
     });
 
-    test('sets next size value computed into `itemsLength`', () => {
-        const instance = createTree({ itemsLength: 15 }).getInstance();
+    test('sets next size value computed into `currentLength`', () => {
+        const instance = createTree({ currentLength: 15 }).getInstance();
         instance.handleUpdate({ isIntersecting: false });
         instance.handleUpdate({ isIntersecting: true });
         expect(instance.state.size).toBe(15);
@@ -164,7 +170,7 @@ describe('handleUpdate', () => {
     test('calls `onIntersection` each time when `awaitIntersection` is falsy', () => {
         const spy = jest.fn();
         const instance = createTree({
-            itemsLength: 30,
+            currentLength: 30,
             onIntersection: spy,
         }).getInstance();
         instance.handleUpdate({ isIntersecting: false });
@@ -178,14 +184,14 @@ describe('handleUpdate', () => {
         const spy = jest.fn();
         const tree = createTree({
             awaitMore: true,
-            itemsLength: 10,
+            currentLength: 10,
             onIntersection: spy,
         });
         tree.getInstance().handleUpdate({ isIntersecting: false });
         tree.getInstance().handleUpdate({ isIntersecting: true });
         tree.getInstance().handleUpdate({ isIntersecting: true });
         expect(tree.getInstance().state.size).toBe(10);
-        tree.update(<List awaitMore itemsLength={30} onIntersection={spy} />);
+        tree.update(<List awaitMore currentLength={30} onIntersection={spy} />);
         tree.getInstance().handleUpdate({ isIntersecting: true });
         expect(spy).toHaveBeenCalledTimes(2);
     });

src/__tests__/__snapshots__/List.spec.js.snap

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`handleUpdate throws once if sentinel intersects items on mount 1`] = `
-"Warning: The sentinel detected a viewport with a bigger size than the size of its items. This could lead to detrimental behavior, e.g.: triggering more than one \`onIntersection\` callback at the start.
-To prevent this, use either a bigger \`pageSize\` value or avoid using the prop \`awaitMore\` initially."
+"Warning: the sentinel detected a viewport with a bigger size than the size of its items. This could lead to detrimental behavior, e.g.: triggering more than one onIntersection callback at the start.
+To prevent this, use either a bigger \`pageSize\` value or avoid using the prop awaitMore initially."
 `;