[CSL-2867] Section configuration option updates (#112)

* Implementation

* Update documentation

* Change default section logic for recommendations

* Add deprecation notice

* Typo

* Add explanation for recommendationsSection styles

* Update docs

* Forward indexSection

* Add documentation for indexSection

* Address comments

* Simplify kebabcase implementation

* Remove identifier

* Rename indexSection

* Add type guards

* Lint

* Update kebabcase

* Typo

* Update types

Author: esezen

README.md

@@ -78,10 +78,10 @@ function YourComponent() {
         {isOpen && (
           <>
             {sections?.map((section) => (
-              <div key={section.identifier} className={section.identifier}>
+              <div key={section.indexSectionName} className={section.indexSectionName}>
                 <div className='cio-section'>
                   <div className='cio-sectionName'>
-                    {section?.displayName || section.identifier}
+                    {section?.displayName || section.indexSectionName}
                   </div>
                   <div className='cio-items'>
                     {section?.data?.map((item) => (

src/components/Autocomplete/AutocompleteResults/AutocompleteResults.tsx

@@ -1,5 +1,6 @@
 import React, { ReactNode, useContext } from 'react';
 import { GetItemProps, Section } from '../../../types';
+import { toKebabCase } from '../../../utils';
 import { CioAutocompleteContext } from '../CioAutocompleteProvider';
 import SectionItemsList from '../SectionItemsList/SectionItemsList';
 
@@ -13,9 +14,27 @@ type AutocompleteResultsProps = {
 };
 
 const DefaultRenderResults: RenderResults = ({ sections }) =>
-  sections?.map((section: Section) => (
-    <SectionItemsList section={section} key={section.identifier} />
-  ));
+  sections?.map((section: Section) => {
+    const { type } = section;
+    let key = section.displayName;
+
+    switch (type) {
+      case 'recommendations':
+        key = section.podId;
+        break;
+      case 'custom':
+        key = toKebabCase(section.displayName);
+        break;
+      case 'autocomplete':
+        key = section.indexSectionName;
+        break;
+      default:
+        key = section.indexSectionName;
+        break;
+    }
+
+    return <SectionItemsList section={section} key={key} />;
+  });
 
 export default function AutocompleteResults(props: AutocompleteResultsProps) {
   const { children = DefaultRenderResults } = props;

src/components/Autocomplete/SectionItemsList/SectionItemsList.tsx

@@ -17,15 +17,32 @@ type SectionItemsListProps = {
 // eslint-disable-next-line func-names
 const DefaultRenderSectionItemsList: RenderSectionItemsList = function ({ section }) {
   const { getSectionProps } = useContext(CioAutocompleteContext);
+  const { type, displayName } = section;
+  let sectionTitle = displayName;
 
-  const sectionName = section?.displayName || section?.identifier;
+  if (!sectionTitle) {
+    switch (type) {
+      case 'recommendations':
+        sectionTitle = section.podId;
+        break;
+      case 'autocomplete':
+        sectionTitle = section.indexSectionName;
+        break;
+      case 'custom':
+        sectionTitle = section.displayName;
+        break;
+      default:
+        sectionTitle = section.indexSectionName;
+        break;
+    }
+  }
 
   if (!section?.data?.length) return null;
 
   return (
     <li {...getSectionProps(section)}>
       <h5 className='cio-sectionName' aria-hidden>
-        {camelToStartCase(sectionName)}
+        {camelToStartCase(sectionTitle)}
       </h5>
       <ul className='cio-section-items' role='none'>
         {section?.data?.map((item) => (

src/constants.ts

@@ -59,24 +59,28 @@ The following stories show how different options affect the hook's behavior!
 // Storybook Pages
 /// //////////////////////////////
 
-export const sectionsDescription = `- by default, typing a query will fetch data for search suggestions and Products
+export const sectionsDescription = `- by default, typing a query will fetch data for Search Suggestions and Products
 - to override this, pass an array of sections objects
 - the order of the objects in the \`sections\` array determines the order of the results
-- each section object must have an \`identifier\`
+- each autocomplete section object must have a \`indexSectionName\`
+- each recommendation section object must have a \`podId\`
+- each custom section object must have a \`displayName\`
 - each section object can specify a \`type\`
 - each section object can override the default \`numResults\` of 8
 
+\`indexSectionName\` refers to a section under an index. The default sections are "Products" and "Search Suggestions". You can find all the sections that exist in your index under the "Indexes" tab of Constructor dashboard.
+
 When no values are passed for the \`sections\` argument, the following defaults are used:
 
 \`\`\`jsx
 [
   {
-    identifier: 'Search Suggestions',
+    indexSectionName: 'Search Suggestions',
     type: 'autocomplete',
     numResults: 8
   },
   {
-    identifier: 'Products',
+    indexSectionName: 'Products',
     type: 'autocomplete',
     numResults: 8
   }
@@ -98,7 +102,9 @@ export const zeroStateDescription = `- when the text input field has no text, we
 - when \`zeroStateSections\` has sections, the menu will open on user focus by default
 - set \`openOnFocus\` to false, to only show \`zeroStateSections\` after user has typed and then cleared the text input, instead of as soon as the user focuses on the text input
 - the order of the objects in the \`zeroStateSections\` array determines the order of the results
-- each section object must have an \`identifier\`
+- each autocomplete section object must have a \`indexSectionName\`
+- each recommendation section object must have a \`podId\`
+- each custom section object must have a \`displayName\`
 - each section object can specify a \`type\`
 - each section object can override the default \`numResults\` of 8`;
 

src/hooks/useCioAutocomplete.ts

@@ -14,24 +14,47 @@ import {
   getItemsForActiveSections,
   getSearchSuggestionFeatures,
   trackRecommendationView,
+  toKebabCase,
 } from '../utils';
 import useConsoleErrors from './useConsoleErrors';
 import useSections from './useSections';
 import useRecommendationsObserver from './useRecommendationsObserver';
+import { isAutocompleteSection, isRecommendationsSection } from '../typeGuards';
 
 export const defaultSections: UserDefinedSection[] = [
   {
-    identifier: 'Search Suggestions',
+    indexSectionName: 'Search Suggestions',
     type: 'autocomplete',
   },
   {
-    identifier: 'Products',
+    indexSectionName: 'Products',
     type: 'autocomplete',
   },
 ];
 
 export type UseCioAutocompleteOptions = Omit<CioAutocompleteProps, 'children'>;
 
+const convertLegacyParametersAndAddDefaults = (sections: UserDefinedSection[]) =>
+  sections.map((config) => {
+    if (isRecommendationsSection(config)) {
+      if (config.identifier && !config.podId) {
+        return { ...config, podId: config.identifier };
+      }
+
+      if (!config.indexSectionName) {
+        return { ...config, indexSectionName: 'Products' };
+      }
+    }
+
+    if (isAutocompleteSection(config)) {
+      if (config.identifier && !config.indexSectionName) {
+        return { ...config, indexSectionName: config.identifier };
+      }
+    }
+
+    return config;
+  });
+
 const useCioAutocomplete = (options: UseCioAutocompleteOptions) => {
   const {
     onSubmit,
@@ -41,13 +64,29 @@ const useCioAutocomplete = (options: UseCioAutocompleteOptions) => {
     cioJsClient,
     cioJsClientOptions,
     placeholder = 'What can we help you find today?',
-    sections = defaultSections,
-    zeroStateSections,
     autocompleteClassName = 'cio-autocomplete',
     advancedParameters,
     defaultInput,
   } = options;
 
+  let { sections = defaultSections, zeroStateSections } = options;
+
+  sections = useMemo(() => {
+    if (sections) {
+      return convertLegacyParametersAndAddDefaults(sections);
+    }
+
+    return sections;
+  }, [sections]);
+
+  zeroStateSections = useMemo(() => {
+    if (zeroStateSections) {
+      return convertLegacyParametersAndAddDefaults(zeroStateSections);
+    }
+
+    return zeroStateSections;
+  }, [zeroStateSections]);
+
   const [query, setQuery] = useState(defaultInput || '');
   const previousQuery = usePrevious(query);
   const cioClient = useCioClient({ apiKey, cioJsClient, cioJsClientOptions } as CioClientConfig);
@@ -171,18 +210,43 @@ const useCioAutocomplete = (options: UseCioAutocompleteOptions) => {
       'data-testid': 'cio-form',
     }),
     getSectionProps: (section: Section) => {
-      const sectionName = section?.displayName || section?.identifier;
+      const { type, displayName } = section;
+      let sectionTitle = displayName;
+
+      // Add the indexSectionName as a class to the section container to make sure it gets the styles
+      // Even if the section is a recommendation pod, if the results are "Products" or "Search Suggestions"
+      // ... they should be styled accordingly
+      const indexSectionName =
+        type !== 'custom' && section.indexSectionName ? toKebabCase(section.indexSectionName) : '';
+
+      if (!sectionTitle) {
+        switch (type) {
+          case 'recommendations':
+            sectionTitle = section.podId;
+            break;
+          case 'autocomplete':
+            sectionTitle = section.indexSectionName;
+            break;
+          case 'custom':
+            sectionTitle = section.displayName;
+            break;
+          default:
+            sectionTitle = section.indexSectionName;
+            break;
+        }
+      }
+
       const attributes: HTMLPropsWithCioDataAttributes = {
-        className: `${sectionName} cio-section`,
+        className: `${sectionTitle} cio-section  ${indexSectionName}`,
         ref: section.ref,
         role: 'none',
         'data-cnstrc-section': section.data[0]?.section,
       };
 
       // Add data attributes for recommendations
-      if (section.type === 'recommendations') {
+      if (isRecommendationsSection(section)) {
         attributes['data-cnstrc-recommendations'] = true;
-        attributes['data-cnstrc-recommendations-pod-id'] = section.identifier;
+        attributes['data-cnstrc-recommendations-pod-id'] = section.podId;
       }
       return attributes;
     },

src/hooks/useDebouncedFetchSections.ts

@@ -3,17 +3,18 @@ import ConstructorIOClient from '@constructor-io/constructorio-client-javascript
 import {
   Nullable,
   IAutocompleteParameters,
+  AutocompleteResponse,
 } from '@constructor-io/constructorio-client-javascript/lib/types';
 import useDebounce from './useDebounce';
 import {
   AutocompleteResultSections,
-  UserDefinedSection,
   AdvancedParameters,
   AdvancedParametersBase,
   SectionsData,
+  AutocompleteSectionConfiguration,
 } from '../types';
 
-const transformResponse = (response, options) => {
+const transformResponse = (response: AutocompleteResponse, options) => {
   const { numTermsWithGroupSuggestions, numGroupsSuggestedPerTerm } = options;
   const newSectionsData: SectionsData = {};
   Object.keys(response?.sections || {}).forEach((section: string) => {
@@ -52,7 +53,7 @@ const transformResponse = (response, options) => {
 const useDebouncedFetchSection = (
   query: string,
   cioClient: Nullable<ConstructorIOClient>,
-  autocompleteSections: UserDefinedSection[],
+  autocompleteSections: AutocompleteSectionConfiguration[],
   advancedParameters?: AdvancedParameters
 ) => {
   const [sectionsData, setSectionsData] = useState<AutocompleteResultSections>({
@@ -75,7 +76,7 @@ const useDebouncedFetchSection = (
       decoratedParameters.resultsPerSection = autocompleteSections.reduce(
         (acc, sectionConfig) => ({
           ...acc,
-          [sectionConfig.identifier]: sectionConfig?.numResults || 8,
+          [sectionConfig.indexSectionName]: sectionConfig?.numResults || 8,
         }),
         {}
       );
@@ -92,11 +93,13 @@ const useDebouncedFetchSection = (
             debouncedSearchTerm,
             autocompleteParameters
           );
-          const newSectionsData = transformResponse(response, {
-            numTermsWithGroupSuggestions,
-            numGroupsSuggestedPerTerm,
-          });
-          setSectionsData(newSectionsData);
+          if (response) {
+            const newSectionsData = transformResponse(response, {
+              numTermsWithGroupSuggestions,
+              numGroupsSuggestedPerTerm,
+            });
+            setSectionsData(newSectionsData);
+          }
         } catch (error: any) {
           // eslint-disable-next-line no-console
           console.log(error);

src/hooks/useFetchRecommendationPod.ts

@@ -1,20 +1,23 @@
 import { useEffect, useState } from 'react';
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import { Nullable } from '@constructor-io/constructorio-client-javascript/lib/types';
-import { RecommendationsSection, Item, SectionsData } from '../types';
+import { Item, SectionsData, RecommendationsSectionConfiguration } from '../types';
 
 const useFetchRecommendationPod = (
   cioClient: Nullable<ConstructorIOClient>,
-  recommendationPods: RecommendationsSection[]
+  recommendationPods: RecommendationsSectionConfiguration[]
 ) => {
   const [recommendationResults, setRecommendationResults] = useState<SectionsData>({});
 
   useEffect(() => {
     if (!cioClient || !Array.isArray(recommendationPods) || recommendationPods.length === 0) return;
     const fetchRecommendationResults = async () => {
       const responses = await Promise.all(
-        recommendationPods.map(({ identifier: podId, ...parameters }) =>
-          cioClient.recommendations.getRecommendations(podId, parameters)
+        recommendationPods.map(({ podId, indexSectionName, ...parameters }) =>
+          cioClient.recommendations.getRecommendations(podId, {
+            ...parameters,
+            section: indexSectionName,
+          })
         )
       );
       const recommendationPodResults = {};
@@ -25,7 +28,7 @@ const useFetchRecommendationPod = (
           recommendationPodResults[pod.id] = results?.map((item: Item) => ({
             ...item,
             id: item?.data?.id,
-            section: recommendationPods[index]?.section || 'Products',
+            section: recommendationPods[index]?.indexSectionName,
             podId: pod.id,
           }));
         }

src/hooks/useRecommendationsObserver.ts

@@ -2,6 +2,7 @@ import { useEffect } from 'react';
 import { Nullable } from '@constructor-io/constructorio-client-javascript/lib/types';
 import ConstructorIO from '@constructor-io/constructorio-client-javascript';
 import { Section } from '../types';
+import { isRecommendationsSection } from '../typeGuards';
 
 /**
  * Custom hook that observes the visibility of recommendation sections and calls trackRecommendationView event.
@@ -27,7 +28,7 @@ function useRecommendationsObserver(
 ) {
   // Get refs for each section
   const refs = sections
-    .filter((section) => section.type === 'recommendations')
+    .filter((section) => isRecommendationsSection(section))
     .map((section) => section.ref);
 
   useEffect(() => {