feat(search):ES-5892 Introduce displayName and displayKey fields to facets (#2690)

jfugalde · web-flow · commit 44f6bc0e2549 · 2025-12-05T16:56:43.000Z
* feat(search):ES-5892 Introduce displayName and displayKey fields to facets

* feat(search): ES-5892 Add displayName and filterKey fields to facets for improved labeling

* feat(search): Enhance facet filters with displayName and filterKey fields for improved UI labeling and functionality

* test(search):ES-5892  Refactor Facets Tests
diff --git a/.changeset/facets-displayName.md b/.changeset/facets-displayName.md
@@ -0,0 +1,7 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Introduce displayName and displayKey fields to facets for improved labeling and filtering
+
+Facet filters now use the `displayName` field for more descriptive labels in the UI, replacing the deprecated `name` field. Product attribute facets now support the `filterKey` field for consistent parameter naming. The facet transformer has been updated to use `displayName` with a fallback to `filterName` when `displayName` is not available.
diff --git a/core/app/[locale]/(default)/(faceted)/fetch-faceted-search.ts b/core/app/[locale]/(default)/(faceted)/fetch-faceted-search.ts
@@ -39,10 +39,11 @@ const GetProductSearchResultsQuery = graphql(
               edges {
                 node {
                   __typename
-                  name
+                  displayName
                   isCollapsedByDefault
                   ... on BrandSearchFilter {
                     displayProductCount
+                    displayName
                     brands {
                       pageInfo {
                         ...PaginationFragment
@@ -60,6 +61,7 @@ const GetProductSearchResultsQuery = graphql(
                   }
                   ... on CategorySearchFilter {
                     displayProductCount
+                    displayName
                     categories {
                       pageInfo {
                         ...PaginationFragment
@@ -92,6 +94,8 @@ const GetProductSearchResultsQuery = graphql(
                   ... on ProductAttributeSearchFilter {
                     displayProductCount
                     filterName
+                    filterKey
+                    displayName
                     attributes {
                       pageInfo {
                         ...PaginationFragment
@@ -107,6 +111,7 @@ const GetProductSearchResultsQuery = graphql(
                     }
                   }
                   ... on RatingSearchFilter {
+                    displayName
                     ratings {
                       pageInfo {
                         ...PaginationFragment
@@ -122,6 +127,7 @@ const GetProductSearchResultsQuery = graphql(
                     }
                   }
                   ... on PriceSearchFilter {
+                    displayName
                     selected {
                       minPrice
                       maxPrice
diff --git a/core/data-transformers/facets-transformer.ts b/core/data-transformers/facets-transformer.ts
@@ -22,7 +22,7 @@ export const facetsTransformer = async ({
   const { filters } = PublicToPrivateParams.parse(searchParams);
 
   return allFacets.map((facet) => {
-    const refinedFacet = refinedFacets.find((f) => f.name === facet.name);
+    const refinedFacet = refinedFacets.find((f) => f.displayName === facet.displayName);
 
     if (facet.__typename === 'CategorySearchFilter') {
       const refinedCategorySearchFilter =
@@ -31,7 +31,7 @@ export const facetsTransformer = async ({
       return {
         type: 'toggle-group' as const,
         paramName: 'categoryIn',
-        label: facet.name,
+        label: facet.displayName,
         defaultCollapsed: facet.isCollapsedByDefault,
         options: facet.categories.map((category) => {
           const refinedCategory = refinedCategorySearchFilter?.categories.find(
@@ -57,7 +57,7 @@ export const facetsTransformer = async ({
       return {
         type: 'toggle-group' as const,
         paramName: 'brand',
-        label: facet.name,
+        label: facet.displayName,
         defaultCollapsed: facet.isCollapsedByDefault,
         options: facet.brands.map((brand) => {
           const refinedBrand = refinedBrandSearchFilter?.brands.find(
@@ -80,8 +80,8 @@ export const facetsTransformer = async ({
 
       return {
         type: 'toggle-group' as const,
-        paramName: `attr_${facet.filterName}`,
-        label: facet.filterName,
+        paramName: `attr_${facet.filterKey}`,
+        label: facet.displayName,
         defaultCollapsed: facet.isCollapsedByDefault,
         options: facet.attributes.map((attribute) => {
           const refinedAttribute = refinedProductAttributeSearchFilter?.attributes.find(
@@ -111,7 +111,7 @@ export const facetsTransformer = async ({
       return {
         type: 'rating' as const,
         paramName: 'minRating',
-        label: facet.name,
+        label: facet.displayName,
         disabled: refinedRatingSearchFilter == null && !isSelected,
         defaultCollapsed: facet.isCollapsedByDefault,
       };
@@ -126,7 +126,7 @@ export const facetsTransformer = async ({
         type: 'range' as const,
         minParamName: 'minPrice',
         maxParamName: 'maxPrice',
-        label: facet.name,
+        label: facet.displayName,
         min: facet.selected?.minPrice ?? undefined,
         max: facet.selected?.maxPrice ?? undefined,
         disabled: refinedPriceSearchFilter == null && !isSelected,
diff --git a/core/tests/ui/e2e/facets.spec.ts b/core/tests/ui/e2e/facets.spec.ts
@@ -0,0 +1,88 @@
+import { expect, Page, test } from '~/tests/fixtures';
+
+const SHOP_ALL_URL = '/shop-all/';
+
+const PRODUCT_LE_PARFAIT_JAR = '[Sample] 1 L Le Parfait Jar';
+const PRODUCT_DUSTPAN_BRUSH = '[Sample] Dustpan & Brush';
+const PRODUCT_UTILITY_CADDY = '[Sample] Utility Caddy';
+
+async function expandFilterIfNeeded(page: Page, filterLabel: string) {
+  const filterButton = page
+    .getByRole('heading', { name: filterLabel, level: 3 })
+    .getByRole('button', { name: filterLabel });
+
+  const isExpanded = await filterButton.getAttribute('aria-expanded');
+
+  if (isExpanded === 'false') {
+    await filterButton.click();
+  }
+}
+
+async function clickSpecificFilterOption(page: Page, filterName: string, optionName: string) {
+  const filterButton = page
+    .getByRole('region', { name: filterName })
+    .getByRole('button', { name: optionName, disabled: false });
+
+  await filterButton.click();
+}
+
+test('Blue color filter shows expected product on shop-all page', async ({ page }) => {
+  await page.goto(SHOP_ALL_URL);
+  await expect(page.getByRole('heading', { name: 'Shop All 13' })).toBeVisible();
+
+  await expandFilterIfNeeded(page, 'Color');
+  await clickSpecificFilterOption(page, 'Color', 'Blue');
+
+  await expect(page).toHaveURL((url) => url.searchParams.get('attr_Color') === 'Blue');
+  await expect(page.getByRole('link', { name: PRODUCT_LE_PARFAIT_JAR })).toBeVisible();
+});
+
+test('Brand filter shows correct products', async ({ page }) => {
+  await page.goto(SHOP_ALL_URL);
+  await expect(page.getByRole('heading', { name: 'Shop All 13' })).toBeVisible();
+
+  await expandFilterIfNeeded(page, 'Brand');
+  await clickSpecificFilterOption(page, 'Brand', 'OFS');
+
+  await expect(page).toHaveURL((url) => url.searchParams.has('brand'));
+  await expect(page.getByRole('heading', { name: 'Shop All 5' })).toBeVisible();
+  await expect(page.getByRole('link', { name: PRODUCT_DUSTPAN_BRUSH })).toBeVisible();
+  await expect(page.getByRole('link', { name: PRODUCT_UTILITY_CADDY })).toBeVisible();
+  await expect(page.getByRole('link', { name: PRODUCT_LE_PARFAIT_JAR })).toBeVisible();
+});
+
+test('Multiple filters work together (Color + Brand)', async ({ page }) => {
+  await page.goto(SHOP_ALL_URL);
+  await expect(page.getByRole('heading', { name: 'Shop All 13' })).toBeVisible();
+
+  await expandFilterIfNeeded(page, 'Color');
+  await clickSpecificFilterOption(page, 'Color', 'Blue');
+
+  await expect(page).toHaveURL((url) => url.searchParams.get('attr_Color') === 'Blue');
+
+  await expandFilterIfNeeded(page, 'Brand');
+  await clickSpecificFilterOption(page, 'Brand', 'OFS');
+
+  await expect(page).toHaveURL((url) => {
+    const params = url.searchParams;
+
+    return params.get('attr_Color') === 'Blue' && params.has('brand');
+  });
+  await expect(page.getByRole('link', { name: PRODUCT_LE_PARFAIT_JAR })).toBeVisible();
+});
+
+test('Removing filter restores product list', async ({ page }) => {
+  await page.goto(SHOP_ALL_URL);
+  await expect(page.getByRole('heading', { name: 'Shop All 13' })).toBeVisible();
+
+  await expandFilterIfNeeded(page, 'Brand');
+  await clickSpecificFilterOption(page, 'Brand', 'OFS');
+
+  await expect(page).toHaveURL((url) => url.searchParams.has('brand'));
+  await expect(page.getByRole('heading', { name: 'Shop All 5' })).toBeVisible();
+
+  await page.getByRole('button', { name: 'Reset filters' }).click();
+
+  await expect(page).toHaveURL((url) => !url.searchParams.has('brand'));
+  await expect(page.getByRole('heading', { name: 'Shop All 13' })).toBeVisible();
+});
