feat(headless): add support for breadcrumb manager in commerce ssr (#…

…4601)

https://coveord.atlassian.net/browse/KIT-3464

This PR adds the breadcrumb manager definer function and a sample for
it.

packages/headless/src/controllers/commerce/core/breadcrumb-manager/headless-core-breadcrumb-manager.ssr.ts

@@ -0,0 +1,34 @@
+import {ensureAtLeastOneSolutionType} from '../../../../app/commerce-ssr-engine/common.js';
+import {
+  ControllerDefinitionOption,
+  SolutionType,
+  SubControllerDefinitionWithoutProps,
+} from '../../../../app/commerce-ssr-engine/types/common.js';
+import {buildProductListing} from '../../product-listing/headless-product-listing.js';
+import {buildSearch} from '../../search/headless-search.js';
+import {
+  BreadcrumbManager,
+  BreadcrumbManagerState,
+} from './headless-core-breadcrumb-manager.js';
+
+export type {BreadcrumbManager, BreadcrumbManagerState};
+
+/**
+ * Defines a `BreadcrumbManager` controller instance.
+ *
+ * @returns The `BreadcrumbManager` controller definition.
+ *
+ * @internal
+ */
+export function defineBreadcrumbManager<
+  TOptions extends ControllerDefinitionOption | undefined,
+>(options?: TOptions) {
+  ensureAtLeastOneSolutionType(options);
+  return {
+    ...options,
+    build: (engine, solutionType) =>
+      solutionType === SolutionType.listing
+        ? buildProductListing(engine).breadcrumbManager()
+        : buildSearch(engine).breadcrumbManager(),
+  } as SubControllerDefinitionWithoutProps<BreadcrumbManager, TOptions>;
+}

packages/headless/src/controllers/commerce/core/facets/date/headless-commerce-date-facet.ts

@@ -15,6 +15,8 @@ import {
   buildCoreCommerceFacet,
 } from '../headless-core-commerce-facet.js';
 
+export type {DateFacetValue};
+
 export type DateFacetOptions = Omit<
   CoreCommerceFacetOptions,
   'toggleSelectActionCreator' | 'toggleExcludeActionCreator'

packages/headless/src/controllers/commerce/core/facets/generator/headless-commerce-facet-generator.ssr.ts

@@ -38,6 +38,7 @@ import {
 import {
   DateFacet,
   DateFacetState,
+  DateFacetValue,
   getDateFacetState,
 } from '../date/headless-commerce-date-facet.js';
 import {
@@ -53,6 +54,7 @@ import {
 import {
   getNumericFacetState,
   NumericFacet,
+  NumericFacetValue,
   NumericFacetState,
 } from '../numeric/headless-commerce-numeric-facet.js';
 import {
@@ -72,8 +74,10 @@ export type {
   CategoryFacetValue,
   CategoryFacetSearchResult,
   DateFacet,
+  DateFacetValue,
   DateFacetState,
   NumericFacet,
+  NumericFacetValue,
   NumericFacetState,
   RegularFacet,
   RegularFacetState,

packages/headless/src/controllers/commerce/core/facets/numeric/headless-commerce-numeric-facet.ts

@@ -20,6 +20,8 @@ import {
   buildCoreCommerceFacet,
 } from '../headless-core-commerce-facet.js';
 
+export type {NumericFacetValue};
+
 export type NumericFacetOptions = Omit<
   CoreCommerceFacetOptions,
   'toggleSelectActionCreator' | 'toggleExcludeActionCreator'

packages/headless/src/ssr-commerce.index.ts

@@ -65,10 +65,12 @@ export type {
   CategoryFacetValue,
   CategoryFacetSearchResult,
   DateFacet,
+  DateFacetValue,
   DateFacetState,
   FacetGenerator,
   FacetGeneratorState,
   NumericFacet,
+  NumericFacetValue,
   NumericFacetState,
   RegularFacet,
   RegularFacetState,
@@ -149,6 +151,12 @@ export type {
 } from './controllers/commerce/core/sort/headless-core-commerce-sort.ssr.js';
 export {defineSort} from './controllers/commerce/core/sort/headless-core-commerce-sort.ssr.js';
 
+export type {
+  BreadcrumbManager,
+  BreadcrumbManagerState,
+} from './controllers/commerce/core/breadcrumb-manager/headless-core-breadcrumb-manager.ssr.js';
+export {defineBreadcrumbManager} from './controllers/commerce/core/breadcrumb-manager/headless-core-breadcrumb-manager.ssr.js';
+
 export type {
   Summary,
   ProductListingSummaryState,

packages/samples/headless-ssr-commerce/app/_components/breadcrumb-manager.tsx

@@ -0,0 +1,81 @@
+import {
+  BreadcrumbManagerState,
+  NumericFacetValue,
+  DateFacetValue,
+  CategoryFacetValue,
+  BreadcrumbManager as HeadlessBreadcrumbManager,
+  RegularFacetValue,
+} from '@coveo/headless/ssr-commerce';
+import {useEffect, useState} from 'react';
+
+interface BreadcrumbManagerProps {
+  staticState: BreadcrumbManagerState;
+  controller?: HeadlessBreadcrumbManager;
+}
+
+export default function BreadcrumbManager(props: BreadcrumbManagerProps) {
+  const {staticState, controller} = props;
+
+  const [state, setState] = useState(staticState);
+
+  useEffect(() => {
+    controller?.subscribe(() => setState(controller.state));
+  }, [controller]);
+
+  const renderBreadcrumbValue = (
+    value:
+      | CategoryFacetValue
+      | RegularFacetValue
+      | NumericFacetValue
+      | DateFacetValue,
+    type: string
+  ) => {
+    switch (type) {
+      case 'hierarchical':
+        return (value as CategoryFacetValue).path.join(' > ');
+      case 'regular':
+        return (value as RegularFacetValue).value;
+      case 'numericalRange':
+        return (
+          (value as NumericFacetValue).start +
+          ' - ' +
+          (value as NumericFacetValue).end
+        );
+      case 'dateRange':
+        return (
+          (value as DateFacetValue).start +
+          ' - ' +
+          (value as DateFacetValue).end
+        );
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <div>
+      <div>
+        <button onClick={controller?.deselectAll}>Clear all filters</button>
+      </div>
+      <ul>
+        {state.facetBreadcrumbs.map((facetBreadcrumb) => {
+          return (
+            <li key={`${facetBreadcrumb.facetId}-breadcrumbs`}>
+              {facetBreadcrumb.values.map((value, index) => {
+                return (
+                  <button
+                    key={`${value.value}-breadcrumb-${index}`}
+                    onClick={() => value.deselect()}
+                  >
+                    {facetBreadcrumb.facetDisplayName}:{' '}
+                    {renderBreadcrumbValue(value.value, facetBreadcrumb.type)} X
+                  </button>
+                );
+              })}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

packages/samples/headless-ssr-commerce/app/_components/pages/listing-page.tsx

@@ -7,6 +7,7 @@ import {
   ListingHydratedState,
   ListingStaticState,
 } from '../../_lib/commerce-engine';
+import BreadcrumbManager from '../breadcrumb-manager';
 import Cart from '../cart';
 import FacetGenerator from '../facets/facet-generator';
 import Pagination from '../pagination';
@@ -63,6 +64,10 @@ export default function ListingPage({
               hydratedState?.controllers.instantProducts
             }
           />
+          <BreadcrumbManager
+            staticState={staticState.controllers.breadcrumbManager.state}
+            controller={hydratedState?.controllers.breadcrumbManager}
+          />
           <FacetGenerator
             staticState={staticState.controllers.facetGenerator.state}
             controller={hydratedState?.controllers.facetGenerator}

packages/samples/headless-ssr-commerce/app/_components/pages/search-page.tsx

@@ -7,6 +7,7 @@ import {
   SearchStaticState,
   searchEngineDefinition,
 } from '../../_lib/commerce-engine';
+import BreadcrumbManager from '../breadcrumb-manager';
 import FacetGenerator from '../facets/facet-generator';
 import ProductList from '../product-list';
 import {Recommendations} from '../recommendation-list';
@@ -75,6 +76,10 @@ export default function SearchPage({
               hydratedState?.controllers.instantProducts
             }
           />
+          <BreadcrumbManager
+            staticState={staticState.controllers.breadcrumbManager.state}
+            controller={hydratedState?.controllers.breadcrumbManager}
+          />
           <FacetGenerator
             staticState={staticState.controllers.facetGenerator.state}
             controller={hydratedState?.controllers.facetGenerator}

packages/samples/headless-ssr-commerce/app/_lib/commerce-engine-config.ts

@@ -21,6 +21,7 @@ import {
   getSampleCommerceEngineConfiguration,
   defineDidYouMean,
   defineRecommendations, //defineParameterManager,
+  defineBreadcrumbManager,
 } from '@coveo/headless/ssr-commerce';
 
 type CommerceEngineConfig = CommerceEngineDefinitionOptions<
@@ -69,5 +70,6 @@ export default {
     didYouMean: defineDidYouMean(), // TODO KIT-3463: implement did you mean in sample
     //parameterManager: defineParameterManager(), // TODO KIT-3462: implement parameter manager in sample
     facetGenerator: defineFacetGenerator(),
+    breadcrumbManager: defineBreadcrumbManager(),
   },
 } satisfies CommerceEngineConfig;