fix(sortby): Consistent across widget / connectors + migration

Author: bobylito

docgen/src/guides/migration.md

@@ -26,3 +26,33 @@ var search = instantsearch({
   }
 });
 ```
+
+## The items are not sorted like before in the refinementList / menu
+
+We changed the default sort order of those widgets. This might have impacted your implementation
+if you didn't specify them originally. To change back the order use the `sortBy` configuration
+key.
+
+Here are examples of usage of `sortBy` using the previous sorting scheme:
+
+```javascript
+search.addWidget(
+  instantsearch.widgets.refinementList({
+    container: '#brands',
+    attributeName: 'brand',
+    sortBy: ['count:desc', 'name:asc'],
+  })
+);
+
+search.addWidget(
+  instantsearch.widgets.menu({
+    container: '#categories',
+    attributeName: 'categories',
+    sortBy: ['count:desc', 'name:asc']
+  })
+);
+```
+
+If you want to learn more about sorting the values, check out the widget API to see what are
+the valid values for the `sortBy` option of [menu](../widgets/menu.html#struct-MenuWidgetOptions-sortBy) or 
+[refinementList](../widgets/refinementList.html#struct-RefinementListWidgetOptions-sortBy)

src/connectors/hierarchical-menu/connectHierarchicalMenu.js

@@ -17,7 +17,7 @@ search.addWidget(
     [ rootPath = null ],
     [ showParentLevel = true ],
     [ limit = 10 ],
-    [ sortBy = ['isRefined', 'count:desc'] ],
+    [ sortBy = ['name:asc'] ],
   })
 );
 Full documentation available at https://community.algolia.com/instantsearch.js/connectors/connectHierarchicalMenu.html
@@ -39,7 +39,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * @property {string} [rootPath] Prefix path to use if the first level is not the root level (default: `null`).
  * @property {string} [showParentLevel] Show the parent level of the current refined value (default: `true`).
  * @property {number} [limit] How much facet values to get (default: `10`).
- * @property {string[]|function} [sortBy] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
+ * @property  {string[]|function} [sortBy=['name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
  *
  * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
  *
@@ -73,7 +73,7 @@ export default function connectHierarchicalMenu(renderFn) {
       rootPath = null,
       showParentLevel = true,
       limit = 10,
-      sortBy = ['isRefined', 'count:desc'],
+      sortBy = ['name:asc'],
     } = widgetParams;
 
     if (!attributes || !attributes.length) {

src/connectors/menu/connectMenu.js

@@ -18,7 +18,7 @@ search.addWidget(
     attributeName,
     [ limit ],
     [ showMoreLimit ]
-    [ sortBy = ['isRefined', 'count:desc'] ]
+    [ sortBy = ['name:asc'] ]
   })
 );
 Full documentation available at https://community.algolia.com/instantsearch.js/connectors/connectMenu.html
@@ -37,7 +37,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
  * @property {string} attributeName Name of the attribute for faceting (eg. "free_shipping").
  * @property {number} [limit] How many facets values to retrieve [*] (default: `10`).
  * @property {number} [showMoreLimit] How many facets values to retrieve when `toggleShowMore` is called, this value is meant to be greater than `limit` option (default: `undefined`).
- * @property {string[]|function} [sortBy] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
+ * @property {string[]|function} [sortBy = ['name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
  *
  * You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax). [*]
  *
@@ -108,7 +108,7 @@ export default function connectMenu(renderFn) {
     const {
       attributeName,
       limit = 10,
-      sortBy = ['isRefined', 'count:desc'],
+      sortBy = ['name:asc'],
       showMoreLimit,
     } = widgetParams;
 

src/connectors/refinement-list/connectRefinementList.js

@@ -18,7 +18,7 @@ search.addWidget(
     attributeName,
     [ operator = 'or' ],
     [ limit ],
-    [ sortBy = ['isRefined', 'count:desc'] ],
+    [ sortBy = ['isRefined', 'count:desc', 'name:asc']],
   })
 );
 Full documentation available at https://community.algolia.com/instantsearch.js/connectors/connectRefinementList.html
@@ -46,6 +46,7 @@ export const checkUsage = ({attributeName, operator, usageMessage}) => {
  * @property {string} attributeName The name of the attribute in the records.
  * @property {"and"|"or"} [operator] How the filters are combined together (default: `"or"`).
  * @property {number} [limit] The max number of items to display.
+ * @property {string[]|function} [sortBy = ['isRefined', 'count:desc', 'name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
  * @property {string[]|function} [sortBy] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc` (default: `['isRefined', 'count:desc']`).
  */
 
@@ -119,7 +120,7 @@ export default function connectRefinementList(renderFn) {
       attributeName,
       operator = 'or',
       limit,
-      sortBy = ['isRefined', 'count:desc'],
+      sortBy = ['isRefined', 'count:desc', 'name:asc'],
     } = widgetParams;
 
     checkUsage({attributeName, operator, usage});

src/widgets/menu/menu.js

@@ -68,7 +68,7 @@ const usage = `Usage:
 menu({
   container,
   attributeName,
-  [ sortBy=['count:desc', 'name:asc'] ],
+  [ sortBy=['name:asc'] ],
   [ limit=10 ],
   [ cssClasses.{root,list,item} ],
   [ templates.{header,item,footer} ],
@@ -119,7 +119,7 @@ menu({
  * @typedef {Object} MenuWidgetOptions
  * @property {string|DOMElement} container CSS Selector or DOMElement to insert the widget
  * @property {string} attributeName Name of the attribute for faceting
- * @property {string[]|function} [sortBy=['count:desc', 'name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
+ * @property {string[]|function} [sortBy=['name:asc']] How to sort refinements. Possible values: `count|isRefined|name:asc|name:desc`.
  *   You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax). [*]
  * @property {string} [limit=10] How many facets values to retrieve [*]
  * @property {boolean|MenuShowMoreOptions} [showMore=false] Limit the number of results and display a showMore button
@@ -150,7 +150,7 @@ menu({
 export default function menu({
   container,
   attributeName,
-  sortBy = ['count:desc', 'name:asc'],
+  sortBy = ['name:asc'],
   limit = 10,
   cssClasses: userCssClasses = {},
   templates = defaultTemplates,

src/widgets/refinement-list/refinement-list.js

@@ -79,7 +79,7 @@ refinementList({
   container,
   attributeName,
   [ operator='or' ],
-  [ sortBy=['count:desc', 'name:asc'] ],
+  [ sortBy=['isRefined', 'count:desc', 'name:asc'] ],
   [ limit=10 ],
   [ cssClasses.{root, header, body, footer, list, item, active, label, checkbox, count}],
   [ templates.{header,item,footer} ],
@@ -161,8 +161,8 @@ refinementList({
  * @property {string|DOMElement} container CSS Selector or DOMElement to insert the widget
  * @property {string} attributeName Name of the attribute for faceting
  * @property {"and"|"or"} [operator="or"] How to apply refinements. Possible values: `or`, `and`
- * @property {("isRefined"|"count:asc"|"count:desc"|"name:asc"|"name:desc")[]|function} [sortBy=["count:desc", "name:asc"]] How to sort refinements. Possible values: `count:asc` `count:desc` `name:asc` `name:desc` `isRefined`.
- *   You can lso use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
+ * @property {string[]|function} [sortBy=["isRefined", "count:desc", "name:asc"]] How to sort refinements. Possible values: `count:asc` `count:desc` `name:asc` `name:desc` `isRefined`.
+ *   You can also use a sort function that behaves like the standard Javascript [compareFunction](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax).
  * @property {number} [limit=10] How much facet values to get. When the show more feature is activated this is the minimum number of facets requested (the show more button is not in active state).
  * @property {SearchForFacetOptions|boolean} [searchForFacetValues=false] Add a search input to let the user search for more facet values
  * @property {RefinementListShowMoreOptions|boolean} [showMore=false] Limit the number of results and display a showMore button
@@ -203,7 +203,7 @@ export default function refinementList({
   container,
   attributeName,
   operator = 'or',
-  sortBy = ['count:desc', 'name:asc'],
+  sortBy = ['isRefined', 'count:desc', 'name:asc'],
   limit = 10,
   cssClasses: userCssClasses = {},
   templates = defaultTemplates,