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

[jfugalde]

What/Why?

This pull request updates how facet filters are handled and displayed in the product search functionality. The main focus is on switching from using the name property since it's now a deprecated field and use displayName property across both the GraphQL query and the data transformer logic, ensuring consistency and improved labeling in the UI. Additionally, new fields such as displayName and filterKey are added to the GraphQL query for richer data support.

Facet filter field improvements:

• Added the displayName field to all facet filter types (BrandSearchFilter, CategorySearchFilter, ProductAttributeSearchFilter, RatingSearchFilter, and PriceSearchFilter) in the GraphQL query in fetch-faceted-search.ts for more descriptive labels.

Facet transformer logic updates:

• Updated the facet transformer in facets-transformer.ts to use displayName instead of name for matching and labeling facets, improving user-facing labels and consistency.
• Changed product attribute facet logic to use filterKey for parameter naming and to prefer displayName for labels, falling back to filterName if displayName is not present.

Testing

Functionality remained the same after the change

Migration

For existing Catalyst stores with customizations, to get this update:

1. Rebase your code with the latest Catalyst release
2. Update the following files if you have customizations:
   • core/app/[locale]/(default)/(faceted)/fetch-faceted-search.ts - The GraphQL query now uses displayName instead of name for facet labels
   • core/data-transformers/facets-transformer.ts - The transformer now uses displayName for matching and labeling facets, with fallback to filterName for product attributes

If you have customized the facet transformer or GraphQL query, ensure your code uses displayName instead of the deprecated name field. Product attribute facets will now use filterKey for parameter naming (e.g., attr_Color instead of using the filter name directly).

[changeset-bot]

🦋 Changeset detected

Latest commit: 29ce1f6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst-b2b	Ready	Preview	Comment	Dec 5, 2025 4:46pm
catalyst-canary	Ready	Preview	Comment	Dec 5, 2025 4:46pm

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst	Ignored			Dec 5, 2025 4:46pm
catalyst-uplift-vertex	Ignored			Dec 5, 2025 4:46pm

[chanceaclark]

Hey @jfugalde thanks for this! In addition to the CI run, would you also add a changeset for this PR?

I tested that this works on another locale: https://catalyst-canary-git-es-5892-bigcommerce-platform.vercel.app/es/shop-all/?attr_Color=Verde

[chanceaclark]

Looks like the lint task is still failing. You might need to add our store 1002923827 to any feature flags that are driving this feature.

Additionally, could we add functional tests to our local functional test suite, under /core/tests/? This test suite is for merchant consumption for context.