feat(hitsPerPageSelector): default hits per page setting

* feat(hitsPerPageSelector): accept default value into items[]
* doc(dev): add example of hitPerPageSelector with default value
* test(connectHitsPerPage): it now provides `getConfiguration()`
* fix(connectHitsPerPage): dont attribute a default value when none specified
* test(hitsPerPage): comply to no default value when none specified
* feat(hitsPerPage): display warning when more than one default value
* refactor(connectHitsPerPage): remove a loop
* feat(connectHitsPerPage): thrown an error instead of warning
* refactor(connectHitsPerPage): check for error on init
* test(connectHitsPerPage): throw when two or more default
* test(hits-per-page-selector): configuration is correct

Author: Maxime Janton

dev/app/init-builtin-widgets.js

@@ -76,21 +76,37 @@ export default () => {
     })
   );
 
-  storiesOf('HitsPerPageSelector').add(
-    'default',
-    wrapWithHits(container => {
-      window.search.addWidget(
-        instantsearch.widgets.hitsPerPageSelector({
-          container,
-          items: [
-            { value: 3, label: '3 per page' },
-            { value: 5, label: '5 per page' },
-            { value: 10, label: '10 per page' },
-          ],
-        })
-      );
-    })
-  );
+  storiesOf('HitsPerPageSelector')
+    .add(
+      'default',
+      wrapWithHits(container => {
+        window.search.addWidget(
+          instantsearch.widgets.hitsPerPageSelector({
+            container,
+            items: [
+              { value: 3, label: '3 per page' },
+              { value: 5, label: '5 per page' },
+              { value: 10, label: '10 per page' },
+            ],
+          })
+        );
+      })
+    )
+    .add(
+      'With default hitPerPage to 5',
+      wrapWithHits(container => {
+        window.search.addWidget(
+          instantsearch.widgets.hitsPerPageSelector({
+            container,
+            items: [
+              { value: 3, label: '3 per page' },
+              { value: 5, label: '5 per page', default: true },
+              { value: 10, label: '10 per page' },
+            ],
+          })
+        );
+      })
+    );
 
   storiesOf('Hits').add(
     'default',

src/connectors/hits-per-page/__tests__/connectHitsPerPage-test.js

@@ -7,6 +7,17 @@ import connectHitsPerPage from '../connectHitsPerPage.js';
 const fakeClient = { addAlgoliaAgent: () => {} };
 
 describe('connectHitsPerPage', () => {
+  it('should throw when there is two default items defined', () => {
+    expect(() => {
+      connectHitsPerPage(() => {})({
+        items: [
+          { value: 3, label: '3 items per page', default: true },
+          { value: 10, label: '10 items per page', default: true },
+        ],
+      });
+    }).toThrow(/^\[Error\]/);
+  });
+
   it('Renders during init and render', () => {
     // test that the dummyRendering is called with the isFirstRendering
     // flag set accordingly
@@ -19,7 +30,8 @@ describe('connectHitsPerPage', () => {
       ],
     });
 
-    expect(widget.getConfiguration).toEqual(undefined);
+    expect(typeof widget.getConfiguration).toEqual('function');
+    expect(widget.getConfiguration()).toEqual({});
 
     // test if widget is not rendered yet at this point
     expect(rendering.callCount).toBe(0);
@@ -65,6 +77,34 @@ describe('connectHitsPerPage', () => {
     });
   });
 
+  it('Configures the search with the default hitsPerPage provided', () => {
+    const rendering = sinon.stub();
+    const makeWidget = connectHitsPerPage(rendering);
+    const widget = makeWidget({
+      items: [
+        { value: 3, label: '3 items per page' },
+        { value: 10, label: '10 items per page', default: true },
+      ],
+    });
+
+    expect(widget.getConfiguration()).toEqual({
+      hitsPerPage: 10,
+    });
+  });
+
+  it('Does not configures the search when there is no default value', () => {
+    const rendering = sinon.stub();
+    const makeWidget = connectHitsPerPage(rendering);
+    const widget = makeWidget({
+      items: [
+        { value: 3, label: '3 items per page' },
+        { value: 10, label: '10 items per page' },
+      ],
+    });
+
+    expect(widget.getConfiguration()).toEqual({});
+  });
+
   it('Provide a function to change the current hits per page, and provide the current value', () => {
     const rendering = sinon.stub();
     const makeWidget = connectHitsPerPage(rendering);

src/connectors/hits-per-page/connectHitsPerPage.js

@@ -15,6 +15,7 @@ var customHitsPerPage = connectHitsPerPage(function render(params, isFirstRender
 search.addWidget(
   customHitsPerPage({
     items: [
+      {value: 5, label: '5 results per page', default: true},
       {value: 10, label: '10 results per page'},
       {value: 42, label: '42 results per page'},
     ],
@@ -34,6 +35,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 * @typedef {Object} HitsPerPageWidgetOptionsItem
 * @property {number} value Number of hits to display per page.
 * @property {string} label Label to display in the option.
+* @property {boolean} default The default hits per page on first search.
 */
 
 /**
@@ -96,7 +98,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  *   customHitsPerPage({
  *     containerNode: $('#custom-hits-per-page-container'),
  *     items: [
- *       {value: 6, label: '6 per page'},
+ *       {value: 6, label: '6 per page', default: true},
  *       {value: 12, label: '12 per page'},
  *       {value: 24, label: '24 per page'},
  *     ],
@@ -114,7 +116,21 @@ export default function connectHitsPerPage(renderFn) {
       throw new Error(usage);
     }
 
+    const defaultValues = items.filter(item => item.default);
+    if (defaultValues.length > 1) {
+      throw new Error(
+        `[Error][hitsPerPageSelector] more than one default value is specified in \`items[]\`
+The first one will be picked, you should probably set only one default value`
+      );
+    }
+
     return {
+      getConfiguration() {
+        return defaultValues.length > 0
+          ? { hitsPerPage: defaultValues[0].value }
+          : {};
+      },
+
       init({ helper, state, instantSearchInstance }) {
         const isCurrentInOptions = some(
           items,

src/widgets/hits-per-page-selector/__tests__/hits-per-page-selector-test.js

@@ -56,8 +56,23 @@ describe('hitsPerPageSelector()', () => {
     };
   });
 
-  it("doesn't configure anything", () => {
-    expect(widget.getConfiguration).toEqual(undefined);
+  it('does not configure the default hits per page if not specified', () => {
+    expect(typeof widget.getConfiguration).toEqual('function');
+    expect(widget.getConfiguration()).toEqual({});
+  });
+
+  it('does configures the default hits per page if specified', () => {
+    const widgetWithDefaults = hitsPerPageSelector({
+      container: document.createElement('div'),
+      items: [
+        { value: 10, label: '10 results' },
+        { value: 20, label: '20 results', default: true },
+      ],
+    });
+
+    expect(widgetWithDefaults.getConfiguration()).toEqual({
+      hitsPerPage: 20,
+    });
   });
 
   it('calls twice ReactDOM.render(<Selector props />, container)', () => {

src/widgets/hits-per-page-selector/hits-per-page-selector.js

@@ -50,6 +50,7 @@ hitsPerPageSelector({
  * @typedef {Object} HitsPerPageSelectorItems
  * @property {number} value number of hits to display per page.
  * @property {string} label Label to display in the option.
+ * @property {boolean} default The default hits per page on first search.
  */
 
 /**
@@ -63,6 +64,8 @@ hitsPerPageSelector({
 /**
  * The hitsPerPageSelector widget gives the user the ability to change the number of results
  * displayed in the hits widget.
+ *
+ * You can specify the default hits per page using a boolean in the items[] array. If none is specified, this first hits per page option will be picked.
  * @type {WidgetFactory}
  * @category basic
  * @param {HitsPerPageSelectorWidgetOptions} $0 The options of the HitPerPageSelector widget.
@@ -72,7 +75,7 @@ hitsPerPageSelector({
  *   instantsearch.widgets.hitsPerPageSelector({
  *     container: '#hits-per-page-selector',
  *     items: [
- *       {value: 3, label: '3 per page'},
+ *       {value: 3, label: '3 per page', default: true},
  *       {value: 6, label: '6 per page'},
  *       {value: 12, label: '12 per page'},
  *     ]