feat(sortBy): rename item name to value

dev/app/builtin/stories/sort-by.stories.js

@@ -15,9 +15,9 @@ export default () => {
           instantsearch.widgets.sortBy({
             container,
             items: [
-              { name: 'instant_search', label: 'Most relevant' },
-              { name: 'instant_search_price_asc', label: 'Lowest price' },
-              { name: 'instant_search_price_desc', label: 'Highest price' },
+              { value: 'instant_search', label: 'Most relevant' },
+              { value: 'instant_search_price_asc', label: 'Lowest price' },
+              { value: 'instant_search_price_desc', label: 'Highest price' },
             ],
           })
         );
@@ -30,14 +30,14 @@ export default () => {
           instantsearch.widgets.sortBy({
             container,
             items: [
-              { name: 'instant_search', label: 'Most relevant' },
-              { name: 'instant_search_price_asc', label: 'Lowest price' },
-              { name: 'instant_search_price_desc', label: 'Highest price' },
+              { value: 'instant_search', label: 'Most relevant' },
+              { value: 'instant_search_price_asc', label: 'Lowest price' },
+              { value: 'instant_search_price_desc', label: 'Highest price' },
             ],
             transformItems: items =>
               items.map(item => ({
                 ...item,
-                label: `${item.label} (transformed)`,
+                label: item.label.toUpperCase(),
               })),
           })
         );

dev/app/init-unmount-widgets.js

@@ -248,9 +248,9 @@ export default () => {
       instantsearch.widgets.sortBy({
         container,
         items: [
-          { name: 'instant_search', label: 'Most relevant' },
-          { name: 'instant_search_price_asc', label: 'Lowest price' },
-          { name: 'instant_search_price_desc', label: 'Highest price' },
+          { value: 'instant_search', label: 'Most relevant' },
+          { value: 'instant_search_price_asc', label: 'Lowest price' },
+          { value: 'instant_search_price_desc', label: 'Highest price' },
         ],
       })
     )

dev/app/jquery/stories/sort-by.stories.js

@@ -12,9 +12,9 @@ export default () => {
         widgets.sortBy({
           containerNode,
           items: [
-            { name: 'instant_search', label: 'Most relevant' },
-            { name: 'instant_search_price_asc', label: 'Lowest price' },
-            { name: 'instant_search_price_desc', label: 'Highest price' },
+            { value: 'instant_search', label: 'Most relevant' },
+            { value: 'instant_search_price_asc', label: 'Lowest price' },
+            { value: 'instant_search_price_desc', label: 'Highest price' },
           ],
         })
       );

docgen/src/guides/v3-migration.md

@@ -1103,6 +1103,15 @@ Finally, `autofocus` is now set to `false` by default and does not support the `
 | --------- | ------- |
 | `indices` | `items` |
 
+- A `sortBy` item value is now `value` instead of `name`:
+
+```js
+const sortByItem = {
+  value: string,
+  label: string,
+}
+```
+
 #### CSS classes
 
 | Before                 | After               |

src/connectors/sort-by/__tests__/connectSortBy-test.js

@@ -18,14 +18,14 @@ describe('connectSortBy', () => {
     });
 
     const items = [
-      { label: 'Sort products by relevance', name: 'relevance' },
-      { label: 'Sort products by price', name: 'priceASC' },
+      { label: 'Sort products by relevance', value: 'relevance' },
+      { label: 'Sort products by price', value: 'priceASC' },
     ];
     const widget = makeWidget({ items });
 
     expect(widget.getConfiguration).toBe(undefined);
 
-    const helper = jsHelper({}, items[0].name);
+    const helper = jsHelper({}, items[0].value);
     helper.search = jest.fn();
 
     widget.init({
@@ -81,16 +81,16 @@ describe('connectSortBy', () => {
     });
 
     const items = [
-      { label: 'Sort products by relevance', name: 'relevance' },
-      { label: 'Sort products by price', name: 'priceASC' },
+      { label: 'Sort products by relevance', value: 'relevance' },
+      { label: 'Sort products by price', value: 'priceASC' },
     ];
     const widget = makeWidget({
       items,
       transformItems: allItems =>
         allItems.map(item => ({ ...item, label: 'transformed' })),
     });
 
-    const helper = jsHelper({}, items[0].name);
+    const helper = jsHelper({}, items[0].value);
     helper.search = jest.fn();
 
     widget.init({
@@ -136,14 +136,14 @@ describe('connectSortBy', () => {
     });
 
     const items = [
-      { label: 'Sort products by relevance', name: 'relevance' },
-      { label: 'Sort products by price', name: 'priceASC' },
+      { label: 'Sort products by relevance', value: 'relevance' },
+      { label: 'Sort products by price', value: 'priceASC' },
     ];
     const widget = makeWidget({
       items,
     });
 
-    const helper = jsHelper({}, items[0].name);
+    const helper = jsHelper({}, items[0].value);
     helper.search = jest.fn();
 
     widget.init({
@@ -156,7 +156,7 @@ describe('connectSortBy', () => {
 
     {
       // first rendering
-      expect(helper.state.index).toBe(items[0].name);
+      expect(helper.state.index).toBe(items[0].value);
       const renderOptions =
         rendering.mock.calls[rendering.mock.calls.length - 1][0];
       const { refine, currentRefinement } = renderOptions;
@@ -195,9 +195,9 @@ describe('connectSortBy', () => {
         searchClient: { search() {} },
       });
       const items = [
-        { label: 'Sort products by relevance', name: 'relevance' },
-        { label: 'Sort products by price', name: 'priceASC' },
-        { label: 'Sort products by magic', name: 'other' },
+        { label: 'Sort products by relevance', value: 'relevance' },
+        { label: 'Sort products by price', value: 'priceASC' },
+        { label: 'Sort products by magic', value: 'other' },
       ];
 
       const widget = makeWidget({

src/connectors/sort-by/connectSortBy.js

@@ -23,8 +23,8 @@ Full documentation available at https://community.algolia.com/instantsearch.js/v
 
 /**
  * @typedef {Object} SortByItem
- * @property {string} name Name of the index to target.
- * @property {string} label Label to display for the targeted index.
+ * @property {string} value The name of the index to target.
+ * @property {string} label The label of the index to display.
  */
 
 /**
@@ -91,9 +91,9 @@ Full documentation available at https://community.algolia.com/instantsearch.js/v
  *   customSortBy({
  *     containerNode: $('#custom-sort-by-container'),
  *     items: [
- *       {name: 'instant_search', label: 'Most relevant'},
- *       {name: 'instant_search_price_asc', label: 'Lowest price'},
- *       {name: 'instant_search_price_desc', label: 'Highest price'},
+ *       { value: 'instant_search', label: 'Most relevant' },
+ *       { value: 'instant_search_price_asc', label: 'Lowest price' },
+ *       { value: 'instant_search_price_desc', label: 'Highest price' },
  *     ],
  *   })
  * );
@@ -108,15 +108,10 @@ export default function connectSortBy(renderFn, unmountFn) {
       throw new Error(usage);
     }
 
-    const selectorOptions = items.map(({ label, name }) => ({
-      label,
-      value: name,
-    }));
-
     return {
       init({ helper, instantSearchInstance }) {
         const currentIndex = helper.getIndex();
-        const isIndexInList = find(items, ({ name }) => name === currentIndex);
+        const isIndexInList = find(items, item => item.value === currentIndex);
 
         if (!isIndexInList) {
           throw new Error(
@@ -130,7 +125,7 @@ export default function connectSortBy(renderFn, unmountFn) {
         renderFn(
           {
             currentRefinement: currentIndex,
-            options: transformItems(selectorOptions),
+            options: transformItems(items),
             refine: this.setIndex,
             hasNoResults: true,
             widgetParams,
@@ -144,7 +139,7 @@ export default function connectSortBy(renderFn, unmountFn) {
         renderFn(
           {
             currentRefinement: helper.getIndex(),
-            options: transformItems(selectorOptions),
+            options: transformItems(items),
             refine: this.setIndex,
             hasNoResults: results.nbHits === 0,
             widgetParams,

src/widgets/sort-by/__tests__/sort-by-test.js

@@ -35,8 +35,8 @@ describe('sortBy()', () => {
 
     container = document.createElement('div');
     items = [
-      { name: 'index-a', label: 'Index A' },
-      { name: 'index-b', label: 'Index B' },
+      { value: 'index-a', label: 'Index A' },
+      { value: 'index-b', label: 'Index B' },
     ];
     cssClasses = {
       root: ['custom-root', 'cx'],

src/widgets/sort-by/sort-by.js

@@ -45,8 +45,8 @@ sortBy({
 
 /**
  * @typedef {Object} SortByIndexDefinition
- * @property {string} name The name of the index in Algolia.
- * @property {string} label The name of the index, for user usage.
+ * @property {string} value The name of the index to target.
+ * @property {string} label The label of the index to display.
  */
 
 /**
@@ -72,9 +72,9 @@ sortBy({
  *   instantsearch.widgets.sortBy({
  *     container: '#sort-by-container',
  *     items: [
- *       {name: 'instant_search', label: 'Most relevant'},
- *       {name: 'instant_search_price_asc', label: 'Lowest price'},
- *       {name: 'instant_search_price_desc', label: 'Highest price'}
+ *       {value: 'instant_search', label: 'Most relevant'},
+ *       {value: 'instant_search_price_asc', label: 'Lowest price'},
+ *       {value: 'instant_search_price_desc', label: 'Highest price'}
  *     ]
  *   })
  * );