feat: pagination component

Mostly based on the work in ui-kit.

Differences:
- default padding is 3 not 5
- labels are strings and merged with the default ones
- there is no wrapping <nav> around, only the <ul>
- <, <<, >, >> are hidden if not available instead of disabled.
Showing a no-click sign felt frustrating. If not available, not shown,
not needed.

Still needed:
- hitsPerPage param
- maxPages param
- page href reads the state and generate a real link

README.md

@@ -83,3 +83,27 @@ npm run test:coverage
     })
   );
 ```
+
+## pagination
+
+```html
+  <div id="pagination"></div>
+```
+
+```js
+  instant.addWidget(
+    instantsearch.widgets.pagination({
+      container: '#pagination',
+      // cssClass: 'pagination', // no default
+      // padding: 3, // number of page numbers to show before/after current
+      // showFirstLast: true, // show or hide first and last links
+      // labels: {
+      //   previous: '‹', // &lsaquo;
+      //   next: '›', // &rsaquo;
+      //   first: '«', // &laquo;
+      //   last: '»' // &raquo;
+      // }
+    })
+  );
+```
+

components/Pagination/PaginationLink/index.js

@@ -0,0 +1,47 @@
+'use strict';
+
+var React = require('react');
+
+class PaginationLink extends React . Component {
+  render() {
+    var label = this.props.label;
+    var ariaLabel = this.props.ariaLabel;
+    var href = this.props.href;
+    var page = this.props.page;
+    var className = this.props.className;
+
+    return (
+      <li className={className}>
+        <a href={href} aria-label={ariaLabel} onClick={this.click.bind(this, page)}>
+          {label}
+        </a>
+      </li>
+    );
+  }
+
+  clickDisabled(e) {
+    e.preventDefault();
+  }
+
+  click(page, e) {
+    e.preventDefault();
+    this.props.setCurrentPage(page).search();
+  }
+}
+
+PaginationLink.propTypes = {
+  ariaLabel: React.PropTypes.oneOfType([
+    React.PropTypes.string,
+    React.PropTypes.number
+  ]).isRequired,
+  className: React.PropTypes.string,
+  href: React.PropTypes.string.isRequired,
+  label: React.PropTypes.oneOfType([
+    React.PropTypes.string,
+    React.PropTypes.number
+  ]).isRequired,
+  page: React.PropTypes.number.isRequired,
+  setCurrentPage: React.PropTypes.func.isRequired
+};
+
+module.exports = PaginationLink;

components/Pagination/Paginator/index.js

@@ -0,0 +1,43 @@
+'use strict';
+
+var range = require('lodash/utility/range');
+
+class Paginator {
+  constructor(params) {
+    this.currentPage = params.currentPage;
+    this.total = params.total;
+    this.padding = params.padding;
+  }
+
+  pages() {
+    var current = this.currentPage;
+    var padding = this.padding;
+    var paddingLeft = this.calculatePaddingLeft(current, padding, this.total);
+    var paddingRight = Math.min(2 * padding + 1, this.total) - paddingLeft;
+    var first = current - paddingLeft;
+    var last = current + paddingRight;
+    return range(first, last);
+  }
+
+  calculatePaddingLeft(current, padding, total) {
+    if (current <= padding) {
+      return current;
+    }
+
+    if (current >= (total - padding)) {
+      return 2 * padding + 1 - (total - current);
+    }
+
+    return padding;
+  }
+
+  isLastPage() {
+    return this.currentPage === this.total - 1;
+  }
+
+  isFirstPage() {
+    return this.currentPage === 0;
+  }
+}
+
+module.exports = Paginator;

components/Pagination/index.js

@@ -0,0 +1,147 @@
+'use strict';
+
+var React = require('react');
+var forEach = require('lodash/collection/forEach');
+var defaultsDeep = require('lodash/object/defaultsDeep');
+
+var Paginator = require('./Paginator');
+var PaginationLink = require('./PaginationLink');
+
+var bem = require('../BemHelper')('as-pagination');
+var cx = require('classnames');
+
+class Pagination extends React.Component {
+  constructor(props) {
+    super(defaultsDeep(props, Pagination.defaultProps));
+  }
+
+  render() {
+    if (this.props.nbHits === 0) {
+      return null;
+    }
+
+    var pager = new Paginator({
+      currentPage: this.props.currentPage,
+      total: this.props.nbPages,
+      padding: this.props.padding
+    });
+
+    var classNames = cx(bem('ul'), this.props.cssClass);
+
+    return (
+      <ul className={classNames}>
+        {this.props.showFirstLast ? this.firstPageLink(pager) : null}
+        {this.previousPageLink(pager)}
+        {this.pages(pager)}
+        {this.nextPageLink(pager)}
+        {this.props.showFirstLast ? this.lastPageLink(pager) : null}
+      </ul>
+    );
+  }
+
+  previousPageLink(pager) {
+    if (pager.isFirstPage()) return null;
+
+    return (
+      <PaginationLink
+        href="#"
+        label={this.props.labels.prev} ariaLabel="Previous"
+        setCurrentPage={this.props.setCurrentPage}
+        page={pager.currentPage - 1} />
+    );
+  }
+
+  nextPageLink(pager) {
+    if (pager.isLastPage()) return null;
+
+    return (
+      <PaginationLink
+        href="#"
+        label={this.props.labels.next} ariaLabel="Next"
+        setCurrentPage={this.props.setCurrentPage}
+        page={pager.currentPage + 1} />
+    );
+  }
+
+  firstPageLink(pager) {
+    if (pager.isFirstPage()) return null;
+
+    return (
+      <PaginationLink
+        href="#"
+        label={this.props.labels.first}
+        ariaLabel="First"
+        setCurrentPage={this.props.setCurrentPage}
+        page={0} />
+    );
+  }
+
+  lastPageLink(pager) {
+    if (pager.isLastPage()) return null;
+
+    return (
+      <PaginationLink
+        href="#"
+        label={this.props.labels.last}
+        ariaLabel="Last"
+        setCurrentPage={this.props.setCurrentPage}
+        page={pager.total - 1} />
+    );
+  }
+
+  pages(pager) {
+    var elements = [];
+
+    forEach(pager.pages(), function(pageNumber) {
+      var className = pageNumber === pager.currentPage ? 'active' : '';
+
+      elements.push(
+        <PaginationLink
+          href="#"
+          label={pageNumber + 1}
+          ariaLabel={pageNumber + 1}
+          setCurrentPage={this.props.setCurrentPage}
+          page={pageNumber}
+          key={pageNumber}
+          className={className} />
+      );
+    }, this);
+
+    return elements;
+  }
+}
+
+Pagination.propTypes = {
+  nbHits: React.PropTypes.number,
+  currentPage: React.PropTypes.number,
+  nbPages: React.PropTypes.number,
+  labels: React.PropTypes.shape({
+    prev: React.PropTypes.string,
+    next: React.PropTypes.string,
+    first: React.PropTypes.string,
+    last: React.PropTypes.string
+  }),
+  showFirstLast: React.PropTypes.bool,
+  padding: React.PropTypes.number,
+  setCurrentPage: React.PropTypes.func.isRequired,
+  cssClass: React.PropTypes.oneOfType([
+    React.PropTypes.string,
+    React.PropTypes.array
+  ])
+};
+
+Pagination.defaultProps = {
+  nbHits: 0,
+  currentPage: 0,
+  nbPages: 0,
+  labels: {
+    prev: '‹', // &lsaquo;
+    next: '›', // &rsaquo;
+    first: '«', // &laquo;
+    last: '»' // &raquo;
+  },
+  showFirstLast: true,
+  padding: 3
+};
+
+module.exports = Pagination;

example/app.js

@@ -26,4 +26,11 @@ instant.addWidget(
   })
 );
 
+instant.addWidget(
+  instantsearch.widgets.pagination({
+    container: '#pagination',
+    cssClass: 'pagination'
+  })
+);
+
 instant.start();

example/index.html

@@ -19,6 +19,7 @@ <h1>Instant search demo <small>using instantsearch.js</small></h1>
       </div>
       <div class="col-md-9">
         <div id="hits"></div>
+        <div id="pagination" class="text-center"></div>
       </div>
     </div>
   </div>

index.js

@@ -4,6 +4,7 @@ module.exports = {
   InstantSearch: require('./lib/InstantSearch'),
   widgets: {
     searchBox: require('./widgets/search-box/'),
-    results: require('./widgets/hits/')
+    results: require('./widgets/hits/'),
+    pagination: require('./widgets/pagination/')
   }
 };

widgets/pagination/index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+var React = require('react');
+
+var utils = require('../../lib/widgetUtils.js');
+
+function hits(params) {
+  var Pagination = require('../../components/Pagination/');
+  var containerNode = utils.getContainerNode(params.container);
+
+  return {
+    render: function(results, state, helper) {
+      React.render(
+        <Pagination
+          nbHits={results.nbHits}
+          currentPage={results.page}
+          nbPages={results.nbPages}
+          setCurrentPage={helper.setCurrentPage.bind(helper)}
+          cssClass={params.cssClass}
+          labels={params.labels} />,
+        containerNode
+      );
+    }
+  };
+}
+
+module.exports = hits;