CHANGELOG.md

@@ -1,3 +1,12 @@
+# [4.25.0](https://github.com/algolia/instantsearch.js/compare/v4.24.3...v4.25.0) (2021-07-06)
+
+
+### Features
+
+* **facets:** apply result from facet ordering ([#4784](https://github.com/algolia/instantsearch.js/issues/4784)) ([9e9d839](https://github.com/algolia/instantsearch.js/commit/9e9d8394067bec35425b7d66f94fcce504faee7f))
+
+
+
 ## [4.24.3](https://github.com/algolia/instantsearch.js/compare/v4.24.2...v4.24.3) (2021-07-05)
 
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "instantsearch.js",
-  "version": "4.24.3",
+  "version": "4.25.0",
   "description": "InstantSearch.js is a JavaScript library for building performant and instant search experiences with Algolia.",
   "homepage": "https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/",
   "types": "es/index.d.ts",

src/connectors/hierarchical-menu/__tests__/connectHierarchicalMenu-test.ts

@@ -691,6 +691,201 @@ See documentation: https://www.algolia.com/doc/api-reference/widgets/hierarchica
         canToggleShowMore: false,
       });
     });
+
+    describe('facetOrdering', () => {
+      const resultsViaFacetOrdering = [
+        {
+          count: 47,
+          data: null,
+          exhaustive: true,
+          isRefined: false,
+          label: 'Outdoor',
+          value: 'Outdoor',
+        },
+        {
+          count: 880,
+          data: [
+            {
+              count: 173,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Frames & pictures',
+              value: 'Decoration > Frames & pictures',
+            },
+            {
+              count: 193,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Candle holders & candles',
+              value: 'Decoration > Candle holders & candles',
+            },
+          ],
+          exhaustive: true,
+          isRefined: true,
+          label: 'Decoration',
+          value: 'Decoration',
+        },
+      ];
+      const resultsViaDefaultSortBy = [
+        {
+          count: 880,
+          data: [
+            {
+              count: 193,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Candle holders & candles',
+              value: 'Decoration > Candle holders & candles',
+            },
+            {
+              count: 173,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Frames & pictures',
+              value: 'Decoration > Frames & pictures',
+            },
+          ],
+          exhaustive: true,
+          isRefined: true,
+          label: 'Decoration',
+          value: 'Decoration',
+        },
+        {
+          count: 47,
+          data: null,
+          exhaustive: true,
+          isRefined: false,
+          label: 'Outdoor',
+          value: 'Outdoor',
+        },
+      ];
+      const resultsViaSortBy = [
+        {
+          count: 47,
+          data: null,
+          exhaustive: true,
+          isRefined: false,
+          label: 'Outdoor',
+          value: 'Outdoor',
+        },
+        {
+          count: 880,
+          data: [
+            {
+              count: 173,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Frames & pictures',
+              value: 'Decoration > Frames & pictures',
+            },
+            {
+              count: 193,
+              data: null,
+              exhaustive: true,
+              isRefined: false,
+              label: 'Candle holders & candles',
+              value: 'Decoration > Candle holders & candles',
+            },
+          ],
+          exhaustive: true,
+          isRefined: true,
+          label: 'Decoration',
+          value: 'Decoration',
+        },
+      ];
+
+      test.each`
+        facetOrderingInResult | sortBy           | expected
+        ${true}               | ${undefined}     | ${resultsViaFacetOrdering}
+        ${false}              | ${undefined}     | ${resultsViaDefaultSortBy}
+        ${true}               | ${['name:desc']} | ${resultsViaSortBy}
+        ${false}              | ${['name:desc']} | ${resultsViaSortBy}
+      `(
+        'renderingContent present: $facetOrderingInResult, sortBy: $sortBy',
+        ({ facetOrderingInResult, sortBy, expected }) => {
+          const renderFn = jest.fn();
+          const unmountFn = jest.fn();
+          const createHierarchicalMenu = connectHierarchicalMenu(
+            renderFn,
+            unmountFn
+          );
+          const hierarchicalMenu = createHierarchicalMenu({
+            attributes: ['category', 'subCategory'],
+            sortBy,
+          });
+          const helper = algoliasearchHelper(
+            createSearchClient(),
+            'indexName',
+            hierarchicalMenu.getWidgetSearchParameters!(
+              new SearchParameters(),
+              {
+                uiState: {
+                  hierarchicalMenu: {
+                    category: ['Decoration'],
+                  },
+                },
+              }
+            )
+          );
+
+          hierarchicalMenu.init!(createInitOptions({ helper }));
+
+          const renderingContent = facetOrderingInResult
+            ? {
+                facetOrdering: {
+                  values: {
+                    category: {
+                      order: ['Outdoor'],
+                      sortRemainingBy: 'alpha' as const,
+                    },
+                    subCategory: {
+                      order: ['Decoration > Frames & pictures'],
+                      sortRemainingBy: 'count' as const,
+                    },
+                  },
+                },
+              }
+            : undefined;
+
+          const results = new SearchResults(helper.state, [
+            createSingleSearchResponse({
+              renderingContent,
+              facets: {
+                category: {
+                  Decoration: 880,
+                },
+                subCategory: {
+                  'Decoration > Candle holders & candles': 193,
+                  'Decoration > Frames & pictures': 173,
+                },
+              },
+            }),
+            createSingleSearchResponse({
+              facets: {
+                category: {
+                  Decoration: 880,
+                  Outdoor: 47,
+                },
+              },
+            }),
+          ]);
+
+          const renderState = hierarchicalMenu.getWidgetRenderState(
+            createRenderOptions({
+              helper,
+              results,
+            })
+          );
+
+          expect(renderState.items).toEqual(expected);
+        }
+      );
+    });
   });
 
   describe('getWidgetUiState', () => {

src/connectors/hierarchical-menu/connectHierarchicalMenu.ts

@@ -23,6 +23,8 @@ const withUsage = createDocumentationMessageGenerator({
   connector: true,
 });
 
+const DEFAULT_SORT = ['name:asc'];
+
 export type HierarchicalMenuItem = {
   /**
    * Value of the menu item.
@@ -79,6 +81,8 @@ export type HierarchicalMenuConnectorParams = {
   /**
    * 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).
+   *
+   * If a facetOrdering is set in the index settings, it is used when sortBy isn't passed
    */
   sortBy?: SortBy<HierarchicalMenuItem>;
   /**
@@ -174,7 +178,7 @@ const connectHierarchicalMenu: HierarchicalMenuConnector = function connectHiera
       limit = 10,
       showMore = false,
       showMoreLimit = 20,
-      sortBy = ['name:asc'],
+      sortBy = DEFAULT_SORT,
       transformItems = (items => items) as TransformItems<HierarchicalMenuItem>,
     } = widgetParams || {};
 
@@ -273,11 +277,6 @@ const connectHierarchicalMenu: HierarchicalMenuConnector = function connectHiera
         );
       },
 
-      /**
-       * @param {Object} param0 cleanup arguments
-       * @param {any} param0.state current search parameters
-       * @returns {any} next search parameters
-       */
       dispose({ state }) {
         unmountFn();
 
@@ -336,6 +335,7 @@ const connectHierarchicalMenu: HierarchicalMenuConnector = function connectHiera
         if (results) {
           const facetValues = results.getFacetValues(hierarchicalFacetName, {
             sortBy,
+            facetOrdering: sortBy === DEFAULT_SORT,
           });
           const facetItems =
             facetValues && !Array.isArray(facetValues) && facetValues.data