feat(atomic): migrate atomic-sort-expression from Stencil to Lit (#6653)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: y-lakhdar <12199712+y-lakhdar@users.noreply.github.com>
Co-authored-by: ylakhdar <ylakhdar@coveo.com>
Co-authored-by: developer-experience-bot[bot] <91079284+developer-experience-bot[bot]@users.noreply.github.com>

Author: 3 people

packages/atomic-react/src/components/search/components.ts

@@ -45,6 +45,7 @@ import {
   AtomicSearchLayout as LitAtomicSearchLayout,
   AtomicSegmentedFacetScrollable as LitAtomicSegmentedFacetScrollable,
   AtomicSortDropdown as LitAtomicSortDropdown,
+  AtomicSortExpression as LitAtomicSortExpression,
   AtomicTab as LitAtomicTab,
   AtomicText as LitAtomicText,
 } from '@coveo/atomic/components';
@@ -327,6 +328,12 @@ export const AtomicSortDropdown = createComponent({
   elementClass: LitAtomicSortDropdown,
 });
 
+export const AtomicSortExpression = createComponent({
+  tagName: 'atomic-sort-expression',
+  react: React,
+  elementClass: LitAtomicSortExpression,
+});
+
 export const AtomicTab = createComponent({
   tagName: 'atomic-tab',
   react: React,

packages/atomic/src/components.d.ts

@@ -1781,27 +1781,6 @@ export namespace Components {
          */
         "snippetStyle"?: string;
     }
-    /**
-     * The `atomic-sort-expression` component defines a sort expression. This component must be inside an `atomic-sort-dropdown` component.
-     */
-    interface AtomicSortExpression {
-        /**
-          * One or more sort criteria that the end user can select or toggle between.  The available sort criteria are:  * `relevancy` * `date ascending`/`date descending` * `qre` * `<FIELD> ascending`/`<FIELD> descending`, where you replace `<FIELD>` with the name of a sortable field in your index (`criteria="size ascending"`).  You can specify multiple sort criteria to be used in the same request by separating them with a comma (`criteria="size ascending, date ascending"`).  You can specify a list of comma-separated sort criteria which will be applied sequentially. For example, if there's a tie on the 1st criterion, the API uses the 2nd criterion to break the tie. However, this only works when combining: * a relevancy criterion followed by one or more field or date criteria. * a qre criterion followed by one or more field or date criteria. * two or more field criteria (`<FIELD>` descending, `<FIELD>` descending). * a single date criterion and one or more field criteria in any order (`<FIELD>` descending, date ascending).  Examples: * `relevancy`, `<FIELD> descending` * `qre`, `<FIELD> ascending` * `date descending`, `<FIELD> descending`, `<FIELD> ascending`
-         */
-        "expression": string;
-        /**
-          * The non-localized label to display for this expression.
-         */
-        "label": string;
-        /**
-          * The tabs on which the sort expression must not be displayed. This property should not be used at the same time as `tabs-included`.  Set this property as a stringified JSON array, for example: ```html  <atomic-sort-expression tabs-excluded='["tabIDA", "tabIDB"]'></atomic-sort-expression> ``` If you don't set this property, the sort expression can be displayed on any tab. Otherwise, the sort expression won't be displayed on any of the specified tabs.
-         */
-        "tabsExcluded": string[] | string;
-        /**
-          * The tabs on which the sort expression can be displayed. This property should not be used at the same time as `tabs-excluded`.  Set this property as a stringified JSON array, for example: ```html  <atomic-sort-expression tabs-included='["tabIDA", "tabIDB"]'></atomic-sort-expression snippet> ``` If you don't set this property, the sort expression can be displayed on any tab. Otherwise, the sort expression can only be displayed on the specified tabs.
-         */
-        "tabsIncluded": string[] | string;
-    }
     /**
      * @deprecated Use `atomic-facet-date-input` instead. This component is meant to be used with Stencil components only.
      * Internal component made to be integrated in a TimeframeFacet.
@@ -2939,15 +2918,6 @@ declare global {
         prototype: HTMLAtomicSmartSnippetSuggestionsElement;
         new (): HTMLAtomicSmartSnippetSuggestionsElement;
     };
-    /**
-     * The `atomic-sort-expression` component defines a sort expression. This component must be inside an `atomic-sort-dropdown` component.
-     */
-    interface HTMLAtomicSortExpressionElement extends Components.AtomicSortExpression, HTMLStencilElement {
-    }
-    var HTMLAtomicSortExpressionElement: {
-        prototype: HTMLAtomicSortExpressionElement;
-        new (): HTMLAtomicSortExpressionElement;
-    };
     interface HTMLAtomicStencilFacetDateInputElementEventMap {
         "atomic/dateInputApply": any;
     }
@@ -3130,7 +3100,6 @@ declare global {
         "atomic-smart-snippet-feedback-modal": HTMLAtomicSmartSnippetFeedbackModalElement;
         "atomic-smart-snippet-source": HTMLAtomicSmartSnippetSourceElement;
         "atomic-smart-snippet-suggestions": HTMLAtomicSmartSnippetSuggestionsElement;
-        "atomic-sort-expression": HTMLAtomicSortExpressionElement;
         "atomic-stencil-facet-date-input": HTMLAtomicStencilFacetDateInputElement;
         "atomic-suggestion-renderer": HTMLAtomicSuggestionRendererElement;
         "atomic-tab-bar": HTMLAtomicTabBarElement;
@@ -4858,27 +4827,6 @@ declare namespace LocalJSX {
          */
         "snippetStyle"?: string;
     }
-    /**
-     * The `atomic-sort-expression` component defines a sort expression. This component must be inside an `atomic-sort-dropdown` component.
-     */
-    interface AtomicSortExpression {
-        /**
-          * One or more sort criteria that the end user can select or toggle between.  The available sort criteria are:  * `relevancy` * `date ascending`/`date descending` * `qre` * `<FIELD> ascending`/`<FIELD> descending`, where you replace `<FIELD>` with the name of a sortable field in your index (`criteria="size ascending"`).  You can specify multiple sort criteria to be used in the same request by separating them with a comma (`criteria="size ascending, date ascending"`).  You can specify a list of comma-separated sort criteria which will be applied sequentially. For example, if there's a tie on the 1st criterion, the API uses the 2nd criterion to break the tie. However, this only works when combining: * a relevancy criterion followed by one or more field or date criteria. * a qre criterion followed by one or more field or date criteria. * two or more field criteria (`<FIELD>` descending, `<FIELD>` descending). * a single date criterion and one or more field criteria in any order (`<FIELD>` descending, date ascending).  Examples: * `relevancy`, `<FIELD> descending` * `qre`, `<FIELD> ascending` * `date descending`, `<FIELD> descending`, `<FIELD> ascending`
-         */
-        "expression": string;
-        /**
-          * The non-localized label to display for this expression.
-         */
-        "label": string;
-        /**
-          * The tabs on which the sort expression must not be displayed. This property should not be used at the same time as `tabs-included`.  Set this property as a stringified JSON array, for example: ```html  <atomic-sort-expression tabs-excluded='["tabIDA", "tabIDB"]'></atomic-sort-expression> ``` If you don't set this property, the sort expression can be displayed on any tab. Otherwise, the sort expression won't be displayed on any of the specified tabs.
-         */
-        "tabsExcluded"?: string[] | string;
-        /**
-          * The tabs on which the sort expression can be displayed. This property should not be used at the same time as `tabs-excluded`.  Set this property as a stringified JSON array, for example: ```html  <atomic-sort-expression tabs-included='["tabIDA", "tabIDB"]'></atomic-sort-expression snippet> ``` If you don't set this property, the sort expression can be displayed on any tab. Otherwise, the sort expression can only be displayed on the specified tabs.
-         */
-        "tabsIncluded"?: string[] | string;
-    }
     /**
      * @deprecated Use `atomic-facet-date-input` instead. This component is meant to be used with Stencil components only.
      * Internal component made to be integrated in a TimeframeFacet.
@@ -5124,7 +5072,6 @@ declare namespace LocalJSX {
         "atomic-smart-snippet-feedback-modal": AtomicSmartSnippetFeedbackModal;
         "atomic-smart-snippet-source": AtomicSmartSnippetSource;
         "atomic-smart-snippet-suggestions": AtomicSmartSnippetSuggestions;
-        "atomic-sort-expression": AtomicSortExpression;
         "atomic-stencil-facet-date-input": AtomicStencilFacetDateInput;
         "atomic-suggestion-renderer": AtomicSuggestionRenderer;
         "atomic-tab-bar": AtomicTabBar;
@@ -5429,10 +5376,6 @@ declare module "@stencil/core" {
              * ```
              */
             "atomic-smart-snippet-suggestions": LocalJSX.AtomicSmartSnippetSuggestions & JSXBase.HTMLAttributes<HTMLAtomicSmartSnippetSuggestionsElement>;
-            /**
-             * The `atomic-sort-expression` component defines a sort expression. This component must be inside an `atomic-sort-dropdown` component.
-             */
-            "atomic-sort-expression": LocalJSX.AtomicSortExpression & JSXBase.HTMLAttributes<HTMLAtomicSortExpressionElement>;
             /**
              * @deprecated Use `atomic-facet-date-input` instead. This component is meant to be used with Stencil components only.
              * Internal component made to be integrated in a TimeframeFacet.

packages/atomic/src/components/search/atomic-sort-expression/atomic-sort-expression.mdx

@@ -0,0 +1,94 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import * as AtomicSortExpressionStories from './atomic-sort-expression.new.stories';
+import { AtomicDocTemplate } from '../../../../storybook-utils/documentation/atomic-doc-template';
+
+
+<Meta of={AtomicSortExpressionStories} />
+
+<AtomicDocTemplate
+  stories={AtomicSortExpressionStories}
+  githubPath="search/atomic-sort-expression/atomic-sort-expression.ts"
+  tagName="atomic-sort-expression"
+  className="AtomicSortExpression"
+>
+
+The `atomic-sort-expression` component defines a sort expression. This component must be inside an `atomic-sort-dropdown` component.
+
+This component is not used standalone. It must be a child of `atomic-sort-dropdown`.
+
+See the [atomic-sort-dropdown documentation](?path=/docs/atomic-sort-dropdown--docs) for additional usage examples.
+
+```html
+<atomic-search-interface>
+  <!-- other components -->
+  
+  <atomic-sort-dropdown>
+    <atomic-sort-expression label="Relevance" expression="relevancy"></atomic-sort-expression>
+    <atomic-sort-expression label="Newest" expression="date descending"></atomic-sort-expression>
+    <atomic-sort-expression label="Oldest" expression="date ascending"></atomic-sort-expression>
+    <atomic-sort-expression label="Size" expression="size descending"></atomic-sort-expression>
+  </atomic-sort-dropdown>
+
+  <!-- other components -->
+</atomic-search-interface>
+```
+
+## Sort Criteria
+
+The available sort criteria are:
+
+- `relevancy` - Sort by relevance score
+- `date ascending` / `date descending` - Sort by date
+- `qre` - Sort using Query Ranking Expression
+- `<FIELD> ascending` / `<FIELD> descending` - Sort by a specific field (e.g., `size ascending`)
+
+### Complex Sort Expressions
+
+You can specify multiple sort criteria separated by commas. The API applies them sequentially:
+
+```html
+<atomic-sort-expression 
+  label="Size then Date" 
+  expression="size ascending, date descending">
+</atomic-sort-expression>
+```
+
+Valid combinations:
+- A relevancy criterion followed by field or date criteria
+- A qre criterion followed by field or date criteria  
+- Two or more field criteria
+- A date criterion and one or more field criteria
+
+## Tab Filtering
+
+### tabs-included
+
+Specify which tabs should display this sort expression:
+
+```html
+<atomic-sort-expression 
+  label="Relevance" 
+  expression="relevancy"
+  tabs-included='["all", "documents"]'>
+</atomic-sort-expression>
+```
+
+### tabs-excluded
+
+Specify which tabs should NOT display this sort expression:
+
+```html
+<atomic-sort-expression 
+  label="Date" 
+  expression="date descending"
+  tabs-excluded='["images"]'>
+</atomic-sort-expression>
+```
+
+> **Note:** Do not use both `tabs-included` and `tabs-excluded` on the same component, as this may lead to unexpected behavior.
+
+## Related Components
+
+- [atomic-sort-dropdown](?path=/docs/atomic-sort-dropdown--docs): Renders a dropdown that allows users to select sort criteria
+
+</AtomicDocTemplate>

packages/atomic/src/components/search/atomic-sort-expression/atomic-sort-expression.new.stories.tsx

@@ -1,9 +1,11 @@
 import type {Meta, StoryObj as Story} from '@storybook/web-components-vite';
 import {getStorybookHelpers} from '@wc-toolkit/storybook-helpers';
 import {html} from 'lit/static-html.js';
+import {MockSearchApi} from '@/storybook-utils/api/search/mock';
 import {parameters} from '@/storybook-utils/common/common-meta-parameters';
 import {wrapInSearchInterface} from '@/storybook-utils/search/search-interface-wrapper';
 
+const searchApiHarness = new MockSearchApi();
 const {decorator, play} = wrapInSearchInterface();
 const {events, args, argTypes, template} = getStorybookHelpers(
   'atomic-sort-expression',
@@ -24,6 +26,9 @@ const meta: Meta = {
   ],
   parameters: {
     ...parameters,
+    msw: {
+      handlers: [...searchApiHarness.handlers],
+    },
     actions: {
       handles: events,
     },
@@ -43,3 +48,37 @@ export const Default: Story = {
     expression: 'relevancy',
   },
 };
+
+export const DateDescending: Story = {
+  name: 'Date Descending Sort',
+  args: {
+    label: 'Newest',
+    expression: 'date descending',
+  },
+};
+
+export const WithTabsIncluded: Story = {
+  name: 'With Tabs Included',
+  args: {
+    label: 'Relevance',
+    expression: 'relevancy',
+    'tabs-included': '["all", "documents"]',
+  },
+};
+
+export const WithTabsExcluded: Story = {
+  name: 'With Tabs Excluded',
+  args: {
+    label: 'Relevance',
+    expression: 'relevancy',
+    'tabs-excluded': '["images"]',
+  },
+};
+
+export const ComplexExpression: Story = {
+  name: 'Complex Sort Expression',
+  args: {
+    label: 'Size then Date',
+    expression: 'size ascending, date descending',
+  },
+};