feat(atomic, headless): add support for sort criteria alphanumericNatural

packages/atomic/package.json

@@ -138,6 +138,7 @@
     "lit-html": "3.1.4",
     "local-web-server": "5.4.0",
     "lodash": "4.17.21",
+    "natural-orderby": "4.0.0",
     "ncp": "2.0.0",
     "postcss-focus-visible": "9.0.1",
     "postcss-import": "16.1.0",

packages/atomic/src/components.d.ts

@@ -888,7 +888,7 @@ export namespace Components {
          */
         "resultsMustMatch": FacetResultsMustMatch;
         /**
-          * The sort criterion to apply to the returned facet values. Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', and 'automatic'.
+          * The sort criterion to apply to the returned facet values. Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', alphanumericNatural', 'alphanumericNaturalDescending' and 'automatic'.
          */
         "sortCriteria": FacetSortCriterion;
         /**
@@ -7031,7 +7031,7 @@ declare namespace LocalJSX {
          */
         "resultsMustMatch"?: FacetResultsMustMatch;
         /**
-          * The sort criterion to apply to the returned facet values. Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', and 'automatic'.
+          * The sort criterion to apply to the returned facet values. Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', alphanumericNatural', 'alphanumericNaturalDescending' and 'automatic'.
          */
         "sortCriteria"?: FacetSortCriterion;
         /**

packages/atomic/src/components/search/facets/atomic-facet/atomic-facet.new.stories.tsx

@@ -20,6 +20,10 @@ const meta: Meta = {
       name: 'number-of-values',
       control: {type: 'number', min: 1},
     },
+    'attributes-sort-criteria': {
+      name: 'sort-criteria',
+      type: 'string',
+    },
   },
   args: {
     'attributes-number-of-values': 8,

packages/atomic/src/components/search/facets/atomic-facet/atomic-facet.tsx

@@ -174,7 +174,7 @@ export class AtomicFacet implements InitializableComponent {
   @Prop({reflect: true}) public withSearch = true;
   /**
    * The sort criterion to apply to the returned facet values.
-   * Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', and 'automatic'.
+   * Possible values are 'score', 'alphanumeric', 'alphanumericDescending', 'occurrences', alphanumericNatural', 'alphanumericNaturalDescending' and 'automatic'.
    */
   @Prop({reflect: true}) public sortCriteria: FacetSortCriterion = 'automatic';
   /**

packages/atomic/src/components/search/facets/atomic-facet/e2e/atomic-facet.e2e.ts

@@ -1,3 +1,5 @@
+import {FacetSortCriterion} from '@coveo/headless';
+import {orderBy} from 'natural-orderby';
 import {test, expect} from './fixture';
 
 test.describe('when selecting the facet search "More matches for" button', () => {
@@ -151,3 +153,81 @@ test.describe('when the "Show more" button has been selected', () => {
     });
   });
 });
+
+const sortCriteriaTests: {
+  criteria: FacetSortCriterion;
+  sortFunction: (values: string[]) => string[];
+}[] = [
+  {
+    criteria: 'alphanumeric',
+    sortFunction: (values: string[]) => [...values].sort(),
+  },
+  {
+    criteria: 'alphanumericDescending',
+    sortFunction: (values: string[]) => [...values].sort().reverse(),
+  },
+  {
+    criteria: 'alphanumericNatural',
+    sortFunction: (values: string[]) =>
+      orderBy([...values], [(value) => value], 'asc'),
+  },
+  {
+    criteria: 'alphanumericNaturalDescending',
+    sortFunction: (values: string[]) =>
+      orderBy([...values], [(value) => value], ['desc']),
+  },
+];
+
+test.describe('Sort Criteria', () => {
+  sortCriteriaTests.forEach(({criteria, sortFunction}) => {
+    test.describe(`when sort criteria is set to "${criteria}"`, () => {
+      test.beforeEach(async ({facet}) => {
+        await facet.load({
+          args: {
+            sortCriteria: criteria,
+            field: 'cat_available_sizes',
+            label: 'Size',
+            numberOfValues: 30,
+          },
+        });
+        await facet.hydrated.waitFor();
+        await expect.poll(async () => await facet.facetValue.count()).toBe(30);
+      });
+
+      test(`should have facet values sorted by ${criteria}`, async ({
+        facet,
+      }) => {
+        const values = await facet.facetValueLabel.allTextContents();
+        const sortedValues = sortFunction(values);
+        expect(values).toEqual(sortedValues);
+      });
+    });
+  });
+
+  test.describe('when sort criteria is set to "occurrences"', () => {
+    test.beforeEach(async ({facet}) => {
+      await facet.load({
+        args: {
+          sortCriteria: 'occurrences',
+          field: 'cat_available_sizes',
+          label: 'Size',
+          numberOfValues: 30,
+        },
+      });
+      await facet.hydrated.waitFor();
+      await expect.poll(async () => await facet.facetValue.count()).toBe(30);
+    });
+
+    test('should have facet values sorted by occurrences', async ({facet}) => {
+      const values = await facet.facetValueOccurrences.allTextContents();
+      const sortedValues = [...values]
+        .sort((a, b) => {
+          const numA = parseInt(a.replace(/[^\d]/g, ''), 10);
+          const numB = parseInt(b.replace(/[^\d]/g, ''), 10);
+          return numA - numB;
+        })
+        .reverse();
+      expect(values).toEqual(sortedValues);
+    });
+  });
+});

packages/atomic/src/components/search/facets/atomic-facet/e2e/page-object.ts

@@ -18,6 +18,14 @@ export class AtomicFacetPageObject extends BasePageObject<'atomic-facet'> {
     return this.page.locator('ul[part="values"] > li');
   }
 
+  get facetValueLabel() {
+    return this.page.locator('ul[part="values"] > li span[part="value-label"]');
+  }
+
+  get facetValueOccurrences() {
+    return this.page.locator('ul[part="values"] > li span[part="value-count"]');
+  }
+
   get facetSearchMoreMatchesFor() {
     return this.page.getByRole('button', {name: 'More matches for p'});
   }

packages/headless/src/features/facets/facet-api/request.ts

@@ -92,6 +92,8 @@ export interface SortCriteria<
     | 'score'
     | 'alphanumeric'
     | 'alphanumericDescending'
+    | 'alphanumericNatural'
+    | 'alphanumericNaturalDescending'
     | 'ascending'
     | 'descending'
     | 'occurrences'

packages/headless/src/features/facets/facet-set/interfaces/request.ts

@@ -17,14 +17,18 @@ export const facetSortCriteria: FacetSortCriterion[] = [
   'alphanumericDescending',
   'occurrences',
   'automatic',
+  'alphanumericNatural',
+  'alphanumericNaturalDescending',
 ];
 
 export type FacetSortCriterion =
   | 'score'
   | 'alphanumeric'
   | 'alphanumericDescending'
   | 'occurrences'
-  | 'automatic';
+  | 'automatic'
+  | 'alphanumericNatural'
+  | 'alphanumericNaturalDescending';
 
 export type FacetSortOrder = 'ascending' | 'descending';
 

packages/headless/src/features/search/search-request.test.ts

@@ -120,6 +120,21 @@ describe('search request', () => {
       type: 'alphanumeric',
     });
   });
+  it('#searchRequest returns the facet state alphanumericNaturalDescending #sortCriteria', async () => {
+    const request = buildMockFacetRequest({
+      field: 'objecttype',
+      sortCriteria: 'alphanumericNaturalDescending',
+    });
+    state.facetSet[1] = buildMockFacetSlice({request});
+    const {facets} = (
+      await buildSearchRequest(state, buildMockNavigatorContextProvider()())
+    ).request;
+
+    expect(facets?.map((f) => f.sortCriteria)).toContainEqual({
+      order: 'descending',
+      type: 'alphanumericNatural',
+    });
+  });
 
   it('#searchRequest returns the facets in the state #numericFacetSet', async () => {
     const request = buildMockNumericFacetRequest({

packages/headless/src/features/search/search-request.ts

@@ -17,6 +17,11 @@ import {mapSearchRequest} from './search-mappings.js';
 type StateNeededBySearchRequest = ConfigurationSection &
   Partial<SearchAppState>;
 
+type SortCriteria = {
+  type: string;
+  order: string;
+};
+
 export const buildSearchRequest = async (
   state: StateNeededBySearchRequest,
   navigatorContext: NavigatorContext,
@@ -147,20 +152,26 @@ function getAllFacets(state: StateNeededBySearchRequest) {
   ];
 }
 
+const sortCriteriaMap: Record<string, SortCriteria> = {
+  alphanumericDescending: {type: 'alphanumeric', order: 'descending'},
+  alphanumericNaturalDescending: {
+    type: 'alphanumericNatural',
+    order: 'descending',
+  },
+};
+
 function getSpecificFacetRequests<T extends FacetSetState>(state: T) {
   return getFacetRequests(state).map((request) => {
     /* The Search API does not support 'alphanumericDescending' as a string value and instead relies on a new sort mechanism to specify sort order.
     At the moment, this is only supported for alphanumeric sorting, but will likely transition to this pattern for other types in the future. */
-    if (request.sortCriteria === 'alphanumericDescending') {
+    const sortCriteria =
+      sortCriteriaMap[request.sortCriteria as keyof typeof sortCriteriaMap];
+    if (sortCriteria) {
       return {
         ...request,
-        sortCriteria: {
-          type: 'alphanumeric',
-          order: 'descending',
-        },
+        sortCriteria,
       };
     }
-
     return request;
   });
 }

packages/headless/src/utils/facet-utils.ts

@@ -8,6 +8,11 @@ import {ConfigurationSection} from '../state/state-sections.js';
 type StateNeededBySearchRequest = ConfigurationSection &
   Partial<SearchAppState>;
 
+type SortCriteria = {
+  type: string;
+  order: string;
+};
+
 export function sortFacets<T extends {facetId: string}>(
   facets: T[],
   sortOrder: string[]
@@ -40,20 +45,26 @@ function getRangeFacetRequests<T extends RangeFacetSetState>(state: T) {
   });
 }
 
+const sortCriteriaMap: Record<string, SortCriteria> = {
+  alphanumericDescending: {type: 'alphanumeric', order: 'descending'},
+  alphanumericNaturalDescending: {
+    type: 'alphanumericNatural',
+    order: 'descending',
+  },
+};
+
 function getSpecificFacetRequests<T extends FacetSetState>(state: T) {
   return getFacetRequests(state).map((request) => {
     /* The Search API does not support 'alphanumericDescending' as a string value and instead relies on a new sort mechanism to specify sort order.
     At the moment, this is only supported for alphanumeric sorting, but will likely transition to this pattern for other types in the future. */
-    if (request.sortCriteria === 'alphanumericDescending') {
+    const sortCriteria =
+      sortCriteriaMap[request.sortCriteria as keyof typeof sortCriteriaMap];
+    if (sortCriteria) {
       return {
         ...request,
-        sortCriteria: {
-          type: 'alphanumeric',
-          order: 'descending',
-        },
+        sortCriteria,
       };
     }
-
     return request;
   });
 }