@constructor-io/constructorio-ui-autocomplete 1.5.2 → 1.6.0

package/README.md

@@ -82,9 +82,9 @@ function YourComponent() {
                   </div>
                   <div className='cio-items'>
                     {section?.data?.map((item) => (
-                      <div {...getItemProps(item)} key={item?.data?.id}>
+                      <div {...getItemProps(item)} key={item?.id}>
                         <div>
-                          {isProduct(item) && (
+                          {item.data?.image_url && (
                             <img
                               width='100%'
                               src={item.data?.image_url}
@@ -92,7 +92,11 @@ function YourComponent() {
                               data-testid='cio-img'
                             />
                           )}
-                          <p>{item.value}</p>
+                          {item.groupName ? (
+                            <p className='cio-term-in-group'>in {item.groupName}</p>
+                          ) : (
+                            <p>{item.value}</p>
+                          )}
                         </div>
                       </div>
                     ))}

package/lib/cjs/components/Autocomplete/SectionItem/SectionItem.js

@@ -14,8 +14,13 @@ function SectionItem(props) {
             react_1.default.createElement("img", { "data-testid": 'cio-img', src: (_a = item.data) === null || _a === void 0 ? void 0 : _a.image_url, alt: item.value }),
             react_1.default.createElement("p", { "data-testid": 'cio-text' }, item.value)));
     }
+    else if ((0, typeGuards_1.isInGroupSuggestion)(item)) {
+        defaultChildren = react_1.default.createElement("p", { className: 'cio-term-in-group' },
+            "in ",
+            item.groupName);
+    }
     else {
-        defaultChildren = item.value;
+        defaultChildren = react_1.default.createElement("p", null, item.value);
     }
     return react_1.default.createElement("li", Object.assign({}, getItemProps(item)), children || defaultChildren);
 }

package/lib/cjs/components/Autocomplete/SectionItemsList/SectionItemsList.js

@@ -12,10 +12,7 @@ const DefaultRenderSectionItemsList = function ({ section }) {
         return null;
     return (react_1.default.createElement("li", { className: `${sectionName} cio-section`, role: 'none' },
         react_1.default.createElement("h5", { className: 'cio-sectionName', "aria-hidden": true }, (0, utils_1.camelToStartCase)(sectionName)),
-        react_1.default.createElement("ul", { className: 'cio-section-items', role: 'none' }, (_b = section === null || section === void 0 ? void 0 : section.data) === null || _b === void 0 ? void 0 : _b.map((item) => {
-            var _a;
-            return (react_1.default.createElement(SectionItem_1.default, { item: item, key: `${section === null || section === void 0 ? void 0 : section.identifier}_${(_a = item === null || item === void 0 ? void 0 : item.data) === null || _a === void 0 ? void 0 : _a.id}` }));
-        }))));
+        react_1.default.createElement("ul", { className: 'cio-section-items', role: 'none' }, (_b = section === null || section === void 0 ? void 0 : section.data) === null || _b === void 0 ? void 0 : _b.map((item) => (react_1.default.createElement(SectionItem_1.default, { item: item, key: item === null || item === void 0 ? void 0 : item.id }))))));
 };
 function SectionItemsList(props) {
     const { section, children = DefaultRenderSectionItemsList } = props;

package/lib/cjs/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.customStylesDescription = exports.multipleSectionsDescription = exports.openOnFocusDescription = exports.zeroStateSectionsDescription = exports.onSubmitDefault = exports.onSubmitDescription = exports.onChangeDescription = exports.onFocusDescription = exports.customSectionDescription = exports.recommendationsDescription = exports.sectionOrderDescription = exports.numResultsDescription = exports.contentDescription = exports.productsDescription = exports.searchSuggestionsDescription = exports.placeholderDescription = exports.cioJsClientDescription = exports.apiKeyDescription = exports.zeroStateDescription = exports.userEventsDescription = exports.sectionsDescription = exports.hookDescription = exports.componentDescription = exports.apiKey = void 0;
+exports.termsWithGroupSuggestionsDescription = exports.advancedParametersDefaultDescription = exports.advancedParametersDescription = exports.customStylesDescription = exports.multipleSectionsDescription = exports.openOnFocusDescription = exports.zeroStateSectionsDescription = exports.onSubmitDefault = exports.onSubmitDescription = exports.onChangeDescription = exports.onFocusDescription = exports.customSectionDescription = exports.recommendationsDescription = exports.sectionOrderDescription = exports.numResultsDescription = exports.contentDescription = exports.productsDescription = exports.searchSuggestionsDescription = exports.placeholderDescription = exports.cioJsClientDescription = exports.apiKeyDescription = exports.zeroStateDescription = exports.userEventsDescription = exports.sectionsDescription = exports.hookDescription = exports.componentDescription = exports.apiKey = void 0;
 // Autocomplete key index
 exports.apiKey = 'key_Gep3oQOu5IMcNh9A';
 /// //////////////////////////////
@@ -33,8 +33,8 @@ const {
   sections: [{...}], // array of sections data to render in menu list
   getFormProps: () => ({...})), // prop getter for jsx form element
   getInputProps: () => ({...})), // prop getter for jsx input element
-  getMenuProps: () => ({...})), // prop getter for jsx element serving as menu container
-  getItemProps: (item) => ({...})), // prop getter for jsx element serving as each result
+  getMenuProps: () => ({...})), // prop getter for jsx element rendering the results container
+  getItemProps: (item) => ({...})), // prop getter for jsx element rendering each result
 
   // available for use, but not required for all use cases
   selectedItem: item, // undefined or current selected item (via hover or arrow keys)
@@ -186,3 +186,8 @@ import '@constructor-io/constructorio-ui-autocomplete/styles.css';
 }
 \`\`\`
 `;
+exports.advancedParametersDescription = `Pass an \`advancedParameters\` object to configure more options for the data included in the results requested from constructor's servers. The stories below show examples of the optional fields within this \`advancedParameters\` object that can be used to fine-tune the autosuggest data returned from constructor's servers.`;
+exports.advancedParametersDefaultDescription = `Passing an \`advancedParameters\` object is optional. Passing an empty object for the \`advancedParameters\` field behaves the same as not passing an \`advancedParameters\` object at all. This has no impact on the results returned by default.`;
+exports.termsWithGroupSuggestionsDescription = `Pass integers for the \`numTermsWithGroupSuggestions\` and \`numGroupsSuggestedPerTerm\` fields to add suggested group filters to search term suggestions. Not all suggested search terms will have group filters, so these integers are upper limits, used to specify the maximum number of terms with group filters and the maximum number of suggested group filters per term. To see this in action:
+- type "bab" in the example below. Notice how the user is presented with a search term of "baby" as well as "baby in Bodysuits" and "baby in Baby Organic Cotton"
+- navigate to the "Terms With Group Suggestions" story (using the navigation menu to the left), then use the Controls to adjust the values of \`numTermsWithGroupSuggestions\` to \`3\` and \`numGroupsSuggestedPerTerm\` to \`1\`. Next, type "dan" in the example autocomplete input field. Notice how the user is presented with three different search terms that have a maximum of one "in {group}" suggestion each`;

package/lib/cjs/hooks/useCioAutocomplete.js

@@ -9,6 +9,7 @@ const useDebouncedFetchSections_1 = tslib_1.__importDefault(require("./useDeboun
 const useFetchRecommendationPod_1 = tslib_1.__importDefault(require("./useFetchRecommendationPod"));
 const usePrevious_1 = tslib_1.__importDefault(require("./usePrevious"));
 const utils_1 = require("../utils");
+const typeGuards_1 = require("../typeGuards");
 exports.defaultSections = [
     {
         identifier: 'Search Suggestions',
@@ -21,7 +22,7 @@ exports.defaultSections = [
 ];
 const useCioAutocomplete = (options) => {
     const defaultPlaceholder = 'What can we help you find today?';
-    const { onSubmit, onChange, openOnFocus, apiKey, cioJsClient, placeholder = defaultPlaceholder, sections = exports.defaultSections, zeroStateSections, autocompleteClassName = 'cio-autocomplete', } = options;
+    const { onSubmit, onChange, openOnFocus, apiKey, cioJsClient, placeholder = defaultPlaceholder, sections = exports.defaultSections, zeroStateSections, autocompleteClassName = 'cio-autocomplete', advancedParameters = {}, } = options;
     const [query, setQuery] = (0, react_1.useState)('');
     const previousQuery = (0, usePrevious_1.default)(query);
     const cioClient = (0, useCioClient_1.default)({ apiKey, cioJsClient });
@@ -39,14 +40,20 @@ const useCioAutocomplete = (options) => {
     }
     const autocompleteSections = activeSections === null || activeSections === void 0 ? void 0 : activeSections.filter((config) => config.type === 'autocomplete' || !config.type);
     const recommendationsSections = activeSections === null || activeSections === void 0 ? void 0 : activeSections.filter((config) => config.type === 'recommendations');
-    const autocompleteResults = (0, useDebouncedFetchSections_1.default)(query, cioClient, autocompleteSections);
+    const autocompleteResults = (0, useDebouncedFetchSections_1.default)(query, cioClient, autocompleteSections, advancedParameters);
     const recommendationsResults = (0, useFetchRecommendationPod_1.default)(cioClient, recommendationsSections);
     const sectionResults = Object.assign(Object.assign({}, autocompleteResults), recommendationsResults);
     const activeSectionsWithData = [];
     activeSections === null || activeSections === void 0 ? void 0 : activeSections.forEach((config) => {
-        const { identifier, data: customData } = config;
-        const data = sectionResults[identifier] || customData;
-        if (data && data !== undefined) {
+        const { identifier } = config;
+        let data;
+        if ((0, typeGuards_1.isCustomSection)(config)) {
+            data = config.data;
+        }
+        else {
+            data = sectionResults[identifier];
+        }
+        if (Array.isArray(data)) {
             activeSectionsWithData.push(Object.assign(Object.assign({}, config), { data }));
         }
     });
@@ -67,7 +74,7 @@ const useCioAutocomplete = (options) => {
         openMenu,
         closeMenu,
         getItemProps: (item) => {
-            const { index, sectionId } = (0, utils_1.getItemPosition)({ item, activeSectionsWithData });
+            const { index, sectionId } = (0, utils_1.getItemPosition)({ item, items });
             const sectionItemTestId = `cio-item-${sectionId === null || sectionId === void 0 ? void 0 : sectionId.replace(' ', '')}`;
             return Object.assign(Object.assign({}, downshift.getItemProps({ item, index })), { className: `cio-item ${sectionItemTestId}`, 'data-testid': sectionItemTestId });
         },

package/lib/cjs/hooks/useDebouncedFetchSections.js

@@ -3,6 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const tslib_1 = require("tslib");
 const react_1 = require("react");
 const useDebounce_1 = tslib_1.__importDefault(require("./useDebounce"));
+const transformResponse = (response, options) => {
+    const { numTermsWithGroupSuggestions, numGroupsSuggestedPerTerm } = options;
+    const newSectionsData = {};
+    Object.keys(response.sections).forEach((section) => {
+        newSectionsData[section] = [];
+        const sectionItems = response.sections[section].map((item) => {
+            var _a;
+            return (Object.assign(Object.assign({}, item), { id: (_a = item === null || item === void 0 ? void 0 : item.data) === null || _a === void 0 ? void 0 : _a.id, section }));
+        });
+        sectionItems.forEach((item, itemIndex) => {
+            var _a, _b, _c;
+            (_a = newSectionsData[section]) === null || _a === void 0 ? void 0 : _a.push(item);
+            if (section === 'Search Suggestions' &&
+                ((_c = (_b = item === null || item === void 0 ? void 0 : item.data) === null || _b === void 0 ? void 0 : _b.groups) === null || _c === void 0 ? void 0 : _c.length) &&
+                itemIndex < numTermsWithGroupSuggestions) {
+                item.data.groups.forEach((group, groupIndex) => {
+                    var _a, _b;
+                    if (groupIndex < numGroupsSuggestedPerTerm) {
+                        const inGroupSearchSuggestion = Object.assign(Object.assign({}, item), { id: `${(_a = item.data) === null || _a === void 0 ? void 0 : _a.id}_${group.group_id}`, groupName: group.display_name, groupId: group.group_id });
+                        (_b = newSectionsData[section]) === null || _b === void 0 ? void 0 : _b.push(inGroupSearchSuggestion);
+                    }
+                });
+            }
+        });
+    });
+    return newSectionsData;
+};
 const autocompleteParameters = {
     resultsPerSection: {},
     // numResults: 8,
@@ -10,18 +37,19 @@ const autocompleteParameters = {
     // filters: {},
     // variationsMap: {}
 };
-const useDebouncedFetchSection = (query, cioClient, autocompleteSections) => {
+const useDebouncedFetchSection = (query, cioClient, autocompleteSections, advancedParameters) => {
     const [sectionsData, setSectionsData] = (0, react_1.useState)({});
     const debouncedSearchTerm = (0, useDebounce_1.default)(query);
+    const { numTermsWithGroupSuggestions = 0, numGroupsSuggestedPerTerm = 0 } = advancedParameters;
     if (autocompleteSections) {
         autocompleteParameters.resultsPerSection = autocompleteSections.reduce((acc, sectionConfig) => (Object.assign(Object.assign({}, acc), { [sectionConfig.identifier]: (sectionConfig === null || sectionConfig === void 0 ? void 0 : sectionConfig.numResults) || 8 })), {});
     }
     (0, react_1.useEffect)(() => {
         if (debouncedSearchTerm) {
             cioClient === null || cioClient === void 0 ? void 0 : cioClient.autocomplete.getAutocompleteResults(debouncedSearchTerm, autocompleteParameters).then((response) => {
-                const newSectionsData = {};
-                Object.keys(response.sections).forEach((section) => {
-                    newSectionsData[section] = response.sections[section].map((item) => (Object.assign(Object.assign({}, item), { section })));
+                const newSectionsData = transformResponse(response, {
+                    numTermsWithGroupSuggestions,
+                    numGroupsSuggestedPerTerm,
                 });
                 setSectionsData(newSectionsData);
             });
@@ -29,7 +57,7 @@ const useDebouncedFetchSection = (query, cioClient, autocompleteSections) => {
         else if (!debouncedSearchTerm) {
             setSectionsData({});
         }
-    }, [debouncedSearchTerm, cioClient]);
+    }, [debouncedSearchTerm, cioClient, numTermsWithGroupSuggestions, numGroupsSuggestedPerTerm]);
     return sectionsData;
 };
 exports.default = useDebouncedFetchSection;

package/lib/cjs/hooks/useFetchRecommendationPod.js

@@ -16,7 +16,10 @@ const useFetchRecommendationPod = (cioClient, recommendationPods) => {
             responses.forEach(({ response }) => {
                 const { pod, results } = response;
                 if (pod === null || pod === void 0 ? void 0 : pod.id) {
-                    recommendationPodResults[pod.id] = results === null || results === void 0 ? void 0 : results.map((item) => (Object.assign(Object.assign({}, item), { section: pod.id })));
+                    recommendationPodResults[pod.id] = results === null || results === void 0 ? void 0 : results.map((item) => {
+                        var _a;
+                        return (Object.assign(Object.assign({}, item), { id: (_a = item === null || item === void 0 ? void 0 : item.data) === null || _a === void 0 ? void 0 : _a.id, section: pod.id }));
+                    });
                 }
             });
             setRecommendationResults(recommendationPodResults);

package/lib/cjs/typeGuards.js

@@ -1,9 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isProduct = void 0;
-// Type Guard
-// eslint-disable-next-line
+exports.isCustomSection = exports.isInGroupSuggestion = exports.isProduct = void 0;
 function isProduct(item) {
-    return item.data.image_url !== undefined;
+    var _a;
+    return ((_a = item.data) === null || _a === void 0 ? void 0 : _a.image_url) !== undefined;
 }
 exports.isProduct = isProduct;
+function isInGroupSuggestion(item) {
+    return item.groupName !== undefined;
+}
+exports.isInGroupSuggestion = isInGroupSuggestion;
+function isCustomSection(config) {
+    return config.data !== undefined;
+}
+exports.isCustomSection = isCustomSection;

package/lib/cjs/utils.js

@@ -3,23 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCioClient = exports.disableStoryActions = exports.stringifyWithDefaults = exports.defaultArgumentsCode = exports.defaultOnSubmitCode = exports.getStoryParams = exports.sleep = exports.clearConstructorRequests = exports.isTrackingRequestSent = exports.camelToStartCase = exports.getItemPosition = void 0;
 const tslib_1 = require("tslib");
 const constructorio_client_javascript_1 = tslib_1.__importDefault(require("@constructor-io/constructorio-client-javascript"));
-const getItemPosition = ({ item, activeSectionsWithData }) => {
-    let indexAcrossSections = -1;
-    let sectionId;
-    activeSectionsWithData.find((section) => {
-        var _a;
-        const indexInSection = (_a = section.data) === null || _a === void 0 ? void 0 : _a.findIndex(({ data: result }) => {
-            var _a;
-            indexAcrossSections += 1;
-            return (result === null || result === void 0 ? void 0 : result.id) === ((_a = item === null || item === void 0 ? void 0 : item.data) === null || _a === void 0 ? void 0 : _a.id);
-        });
-        if (indexInSection === -1) {
-            return false; // continue searching through sections
-        }
-        sectionId = section.identifier; // item found in current section
-        return true; // stop looping through sections
-    });
-    return { sectionId, index: indexAcrossSections };
+const getItemPosition = ({ item, items }) => {
+    var _a;
+    const index = items.findIndex((itemInFlatList) => (itemInFlatList === null || itemInFlatList === void 0 ? void 0 : itemInFlatList.id) === (item === null || item === void 0 ? void 0 : item.id));
+    const sectionId = (_a = items[index]) === null || _a === void 0 ? void 0 : _a.section;
+    return { sectionId, index };
 };
 exports.getItemPosition = getItemPosition;
 const camelToStartCase = (camelCaseString) => camelCaseString

package/lib/mjs/components/Autocomplete/SectionItem/SectionItem.js

@@ -1,6 +1,6 @@
 import React, { useContext } from 'react';
 import { CioAutocompleteContext } from '../CioAutocompleteProvider';
-import { isProduct } from '../../../typeGuards';
+import { isProduct, isInGroupSuggestion } from '../../../typeGuards';
 export default function SectionItem(props) {
     const { item, children } = props;
     const { getItemProps } = useContext(CioAutocompleteContext);
@@ -10,8 +10,13 @@ export default function SectionItem(props) {
             React.createElement("img", { "data-testid": 'cio-img', src: item.data?.image_url, alt: item.value }),
             React.createElement("p", { "data-testid": 'cio-text' }, item.value)));
     }
+    else if (isInGroupSuggestion(item)) {
+        defaultChildren = React.createElement("p", { className: 'cio-term-in-group' },
+            "in ",
+            item.groupName);
+    }
     else {
-        defaultChildren = item.value;
+        defaultChildren = React.createElement("p", null, item.value);
     }
     return React.createElement("li", { ...getItemProps(item) }, children || defaultChildren);
 }

package/lib/mjs/components/Autocomplete/SectionItemsList/SectionItemsList.js

@@ -8,7 +8,7 @@ const DefaultRenderSectionItemsList = function ({ section }) {
         return null;
     return (React.createElement("li", { className: `${sectionName} cio-section`, role: 'none' },
         React.createElement("h5", { className: 'cio-sectionName', "aria-hidden": true }, camelToStartCase(sectionName)),
-        React.createElement("ul", { className: 'cio-section-items', role: 'none' }, section?.data?.map((item) => (React.createElement(SectionItem, { item: item, key: `${section?.identifier}_${item?.data?.id}` }))))));
+        React.createElement("ul", { className: 'cio-section-items', role: 'none' }, section?.data?.map((item) => (React.createElement(SectionItem, { item: item, key: item?.id }))))));
 };
 export default function SectionItemsList(props) {
     const { section, children = DefaultRenderSectionItemsList } = props;

package/lib/mjs/constants.js

@@ -30,8 +30,8 @@ const {
   sections: [{...}], // array of sections data to render in menu list
   getFormProps: () => ({...})), // prop getter for jsx form element
   getInputProps: () => ({...})), // prop getter for jsx input element
-  getMenuProps: () => ({...})), // prop getter for jsx element serving as menu container
-  getItemProps: (item) => ({...})), // prop getter for jsx element serving as each result
+  getMenuProps: () => ({...})), // prop getter for jsx element rendering the results container
+  getItemProps: (item) => ({...})), // prop getter for jsx element rendering each result
 
   // available for use, but not required for all use cases
   selectedItem: item, // undefined or current selected item (via hover or arrow keys)
@@ -182,3 +182,8 @@ import '@constructor-io/constructorio-ui-autocomplete/styles.css';
 }
 \`\`\`
 `;
+export const advancedParametersDescription = `Pass an \`advancedParameters\` object to configure more options for the data included in the results requested from constructor's servers. The stories below show examples of the optional fields within this \`advancedParameters\` object that can be used to fine-tune the autosuggest data returned from constructor's servers.`;
+export const advancedParametersDefaultDescription = `Passing an \`advancedParameters\` object is optional. Passing an empty object for the \`advancedParameters\` field behaves the same as not passing an \`advancedParameters\` object at all. This has no impact on the results returned by default.`;
+export const termsWithGroupSuggestionsDescription = `Pass integers for the \`numTermsWithGroupSuggestions\` and \`numGroupsSuggestedPerTerm\` fields to add suggested group filters to search term suggestions. Not all suggested search terms will have group filters, so these integers are upper limits, used to specify the maximum number of terms with group filters and the maximum number of suggested group filters per term. To see this in action:
+- type "bab" in the example below. Notice how the user is presented with a search term of "baby" as well as "baby in Bodysuits" and "baby in Baby Organic Cotton"
+- navigate to the "Terms With Group Suggestions" story (using the navigation menu to the left), then use the Controls to adjust the values of \`numTermsWithGroupSuggestions\` to \`3\` and \`numGroupsSuggestedPerTerm\` to \`1\`. Next, type "dan" in the example autocomplete input field. Notice how the user is presented with three different search terms that have a maximum of one "in {group}" suggestion each`;

package/lib/mjs/hooks/useCioAutocomplete.js

@@ -5,6 +5,7 @@ import useDebouncedFetchSection from './useDebouncedFetchSections';
 import useFetchRecommendationPod from './useFetchRecommendationPod';
 import usePrevious from './usePrevious';
 import { getItemPosition } from '../utils';
+import { isCustomSection } from '../typeGuards';
 export const defaultSections = [
     {
         identifier: 'Search Suggestions',
@@ -17,7 +18,7 @@ export const defaultSections = [
 ];
 const useCioAutocomplete = (options) => {
     const defaultPlaceholder = 'What can we help you find today?';
-    const { onSubmit, onChange, openOnFocus, apiKey, cioJsClient, placeholder = defaultPlaceholder, sections = defaultSections, zeroStateSections, autocompleteClassName = 'cio-autocomplete', } = options;
+    const { onSubmit, onChange, openOnFocus, apiKey, cioJsClient, placeholder = defaultPlaceholder, sections = defaultSections, zeroStateSections, autocompleteClassName = 'cio-autocomplete', advancedParameters = {}, } = options;
     const [query, setQuery] = useState('');
     const previousQuery = usePrevious(query);
     const cioClient = useCioClient({ apiKey, cioJsClient });
@@ -35,14 +36,20 @@ const useCioAutocomplete = (options) => {
     }
     const autocompleteSections = activeSections?.filter((config) => config.type === 'autocomplete' || !config.type);
     const recommendationsSections = activeSections?.filter((config) => config.type === 'recommendations');
-    const autocompleteResults = useDebouncedFetchSection(query, cioClient, autocompleteSections);
+    const autocompleteResults = useDebouncedFetchSection(query, cioClient, autocompleteSections, advancedParameters);
     const recommendationsResults = useFetchRecommendationPod(cioClient, recommendationsSections);
     const sectionResults = { ...autocompleteResults, ...recommendationsResults };
     const activeSectionsWithData = [];
     activeSections?.forEach((config) => {
-        const { identifier, data: customData } = config;
-        const data = sectionResults[identifier] || customData;
-        if (data && data !== undefined) {
+        const { identifier } = config;
+        let data;
+        if (isCustomSection(config)) {
+            data = config.data;
+        }
+        else {
+            data = sectionResults[identifier];
+        }
+        if (Array.isArray(data)) {
             activeSectionsWithData.push({ ...config, data });
         }
     });
@@ -67,7 +74,7 @@ const useCioAutocomplete = (options) => {
         openMenu,
         closeMenu,
         getItemProps: (item) => {
-            const { index, sectionId } = getItemPosition({ item, activeSectionsWithData });
+            const { index, sectionId } = getItemPosition({ item, items });
             const sectionItemTestId = `cio-item-${sectionId?.replace(' ', '')}`;
             return {
                 ...downshift.getItemProps({ item, index }),

package/lib/mjs/hooks/useDebouncedFetchSections.js

@@ -1,5 +1,36 @@
 import { useEffect, useState } from 'react';
 import useDebounce from './useDebounce';
+const transformResponse = (response, options) => {
+    const { numTermsWithGroupSuggestions, numGroupsSuggestedPerTerm } = options;
+    const newSectionsData = {};
+    Object.keys(response.sections).forEach((section) => {
+        newSectionsData[section] = [];
+        const sectionItems = response.sections[section].map((item) => ({
+            ...item,
+            id: item?.data?.id,
+            section,
+        }));
+        sectionItems.forEach((item, itemIndex) => {
+            newSectionsData[section]?.push(item);
+            if (section === 'Search Suggestions' &&
+                item?.data?.groups?.length &&
+                itemIndex < numTermsWithGroupSuggestions) {
+                item.data.groups.forEach((group, groupIndex) => {
+                    if (groupIndex < numGroupsSuggestedPerTerm) {
+                        const inGroupSearchSuggestion = {
+                            ...item,
+                            id: `${item.data?.id}_${group.group_id}`,
+                            groupName: group.display_name,
+                            groupId: group.group_id,
+                        };
+                        newSectionsData[section]?.push(inGroupSearchSuggestion);
+                    }
+                });
+            }
+        });
+    });
+    return newSectionsData;
+};
 const autocompleteParameters = {
     resultsPerSection: {},
     // numResults: 8,
@@ -7,9 +38,10 @@ const autocompleteParameters = {
     // filters: {},
     // variationsMap: {}
 };
-const useDebouncedFetchSection = (query, cioClient, autocompleteSections) => {
+const useDebouncedFetchSection = (query, cioClient, autocompleteSections, advancedParameters) => {
     const [sectionsData, setSectionsData] = useState({});
     const debouncedSearchTerm = useDebounce(query);
+    const { numTermsWithGroupSuggestions = 0, numGroupsSuggestedPerTerm = 0 } = advancedParameters;
     if (autocompleteSections) {
         autocompleteParameters.resultsPerSection = autocompleteSections.reduce((acc, sectionConfig) => ({
             ...acc,
@@ -21,12 +53,9 @@ const useDebouncedFetchSection = (query, cioClient, autocompleteSections) => {
             cioClient?.autocomplete
                 .getAutocompleteResults(debouncedSearchTerm, autocompleteParameters)
                 .then((response) => {
-                const newSectionsData = {};
-                Object.keys(response.sections).forEach((section) => {
-                    newSectionsData[section] = response.sections[section].map((item) => ({
-                        ...item,
-                        section,
-                    }));
+                const newSectionsData = transformResponse(response, {
+                    numTermsWithGroupSuggestions,
+                    numGroupsSuggestedPerTerm,
                 });
                 setSectionsData(newSectionsData);
             });
@@ -34,7 +63,7 @@ const useDebouncedFetchSection = (query, cioClient, autocompleteSections) => {
         else if (!debouncedSearchTerm) {
             setSectionsData({});
         }
-    }, [debouncedSearchTerm, cioClient]);
+    }, [debouncedSearchTerm, cioClient, numTermsWithGroupSuggestions, numGroupsSuggestedPerTerm]);
     return sectionsData;
 };
 export default useDebouncedFetchSection;

package/lib/mjs/hooks/useFetchRecommendationPod.js

@@ -12,6 +12,7 @@ const useFetchRecommendationPod = (cioClient, recommendationPods) => {
                 if (pod?.id) {
                     recommendationPodResults[pod.id] = results?.map((item) => ({
                         ...item,
+                        id: item?.data?.id,
                         section: pod.id,
                     }));
                 }

package/lib/mjs/typeGuards.js

@@ -1,5 +1,9 @@
-// Type Guard
-// eslint-disable-next-line
 export function isProduct(item) {
-    return item.data.image_url !== undefined;
+    return item.data?.image_url !== undefined;
+}
+export function isInGroupSuggestion(item) {
+    return item.groupName !== undefined;
+}
+export function isCustomSection(config) {
+    return config.data !== undefined;
 }

package/lib/mjs/utils.js

@@ -1,19 +1,8 @@
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
-export const getItemPosition = ({ item, activeSectionsWithData }) => {
-    let indexAcrossSections = -1;
-    let sectionId;
-    activeSectionsWithData.find((section) => {
-        const indexInSection = section.data?.findIndex(({ data: result }) => {
-            indexAcrossSections += 1;
-            return result?.id === item?.data?.id;
-        });
-        if (indexInSection === -1) {
-            return false; // continue searching through sections
-        }
-        sectionId = section.identifier; // item found in current section
-        return true; // stop looping through sections
-    });
-    return { sectionId, index: indexAcrossSections };
+export const getItemPosition = ({ item, items }) => {
+    const index = items.findIndex((itemInFlatList) => itemInFlatList?.id === item?.id);
+    const sectionId = items[index]?.section;
+    return { sectionId, index };
 };
 export const camelToStartCase = (camelCaseString) => camelCaseString
     // insert a space before all caps

package/lib/styles.css

@@ -113,3 +113,7 @@
   max-width: 100px;
   max-height: 100px;
 }
+
+.cio-autocomplete .cio-term-in-group {
+  padding-left: 10px;
+}

package/lib/types/constants.d.ts

@@ -1,7 +1,7 @@
 import { AutocompleteSubmitEvent } from './types';
 export declare const apiKey = "key_Gep3oQOu5IMcNh9A";
 export declare const componentDescription = "- import `CioAutocomplete` to render in your JSX.\n- This component handles state management, data fetching, and rendering logic.\n- To use this component, an `apiKey` or `cioJsClient` are required, and an `onSubmit` callback must be passed. All other values are optional.\n- Use different props to configure the behavior of this component.\n- The following stories shows how different props affect the component's behavior\n\n> Note: when we say `cioJsClient`, we are referring to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n";
-export declare const hookDescription = "- import `useCioAutocomplete` and call this custom hook in a functional component.\n- This hook leaves rendering logic up to you, while handling:\n  - state management\n  - data fetching\n  - keyboard navigation\n  - mouse interactions\n  - focus and submit event handling\n- To use this hook, an `apiKey` or `cioJsClient` are required, and an `onSubmit` callback must be passed to the `useCioAutocomplete` hook to configure behavior. All other values are optional.\n- use the <a href=\"https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters\" target=\"__blank\">prop getters</a> and other variables returned by this hook (below) to leverage the functionality described above with jsx elements in your react component definitions\n\nCalling the `useCioAutocomplete` hook returns an object with the following keys:\n\n```jsx\nconst {\n  // must be used for a hooks integrations\n  query: string, // current input field value\n  sections: [{...}], // array of sections data to render in menu list\n  getFormProps: () => ({...})), // prop getter for jsx form element\n  getInputProps: () => ({...})), // prop getter for jsx input element\n  getMenuProps: () => ({...})), // prop getter for jsx element serving as menu container\n  getItemProps: (item) => ({...})), // prop getter for jsx element serving as each result\n\n  // available for use, but not required for all use cases\n  selectedItem: item, // undefined or current selected item (via hover or arrow keys)\n  isOpen: boolean, // current state of the menu list\n  openMenu: () => void, // open menu\n  closeMenu: () => void, // close menu\n  setQuery: () => void, // update the current input field value\n  getLabelProps: () => ({...})), // prop getter for a jsx label element\n  cioJsClient, // instance of constructorio-client-javascript\n } = useCioAutocomplete(args);\n```\n\n> Note: when we say `cioJsClient`, we are referring to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n\nThe following stories show how different options affect the hook's behavior!\n";
+export declare const hookDescription = "- import `useCioAutocomplete` and call this custom hook in a functional component.\n- This hook leaves rendering logic up to you, while handling:\n  - state management\n  - data fetching\n  - keyboard navigation\n  - mouse interactions\n  - focus and submit event handling\n- To use this hook, an `apiKey` or `cioJsClient` are required, and an `onSubmit` callback must be passed to the `useCioAutocomplete` hook to configure behavior. All other values are optional.\n- use the <a href=\"https://kentcdodds.com/blog/how-to-give-rendering-control-to-users-with-prop-getters\" target=\"__blank\">prop getters</a> and other variables returned by this hook (below) to leverage the functionality described above with jsx elements in your react component definitions\n\nCalling the `useCioAutocomplete` hook returns an object with the following keys:\n\n```jsx\nconst {\n  // must be used for a hooks integrations\n  query: string, // current input field value\n  sections: [{...}], // array of sections data to render in menu list\n  getFormProps: () => ({...})), // prop getter for jsx form element\n  getInputProps: () => ({...})), // prop getter for jsx input element\n  getMenuProps: () => ({...})), // prop getter for jsx element rendering the results container\n  getItemProps: (item) => ({...})), // prop getter for jsx element rendering each result\n\n  // available for use, but not required for all use cases\n  selectedItem: item, // undefined or current selected item (via hover or arrow keys)\n  isOpen: boolean, // current state of the menu list\n  openMenu: () => void, // open menu\n  closeMenu: () => void, // close menu\n  setQuery: () => void, // update the current input field value\n  getLabelProps: () => ({...})), // prop getter for a jsx label element\n  cioJsClient, // instance of constructorio-client-javascript\n } = useCioAutocomplete(args);\n```\n\n> Note: when we say `cioJsClient`, we are referring to an instance of the [constructorio-client-javascript](https://www.npmjs.com/package/@constructor-io/constructorio-client-javascript)\n\nThe following stories show how different options affect the hook's behavior!\n";
 export declare const sectionsDescription = "- by default, typing a query will fetch data for search suggestions and Products\n- to override this, pass an array of sections objects\n- the order of the objects in the `sections` array determines the order of the results\n- each section object must have an `identifier`\n- each section object can specify a `type`\n- each section object can override the default `numResults` of 8\n\nWhen no values are passed for the `sections` argument, the following defaults are used:\n\n```jsx\n[\n  {\n    identifier: 'Search Suggestions',\n    type: 'autocomplete',\n    numResults: 8\n  },\n  {\n    identifier: 'Products',\n    type: 'autocomplete',\n    numResults: 8\n  }\n]\n```\n";
 export declare const userEventsDescription = "- pass callback functions to respond to user events\n- if provided, the onFocus callback function will be called each time the user focuses on the text input field\n- if provided, the onChange callback function will be called each time the user changes the value in the text input field\n- the onSubmit callback function will be called each time the user submits the form\n- the user can submit the form by pressing the enter key in the text input field, clicking a submit button within the form, clicking on a result, or pressing enter while a result is selected\n\n> \u26A0\uFE0F NOTE \u26A0\uFE0F Use the Storybook Canvas Actions tab to explore the behavior of all of these `OnEvent` callback functions as you interact with our Default User Events example rendered in the Canvas. In the stories below, Storybook Canvas Actions have been disabled to focus on each of these callback functions in isolation. Each of the example callback functions in the stories below log output to the console tab of the browser's developer tools.";
 export declare const zeroStateDescription = "- when the text input field has no text, we call this zero state\n- by default, the autocomplete shows nothing in the menu it's for zero state\n- to show zero state results, pass an array of section objects for `zeroStateSections`\n- when `zeroStateSections` has sections, the menu will open on user focus by default\n- 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\n- the order of the objects in the `zeroStateSections` array determines the order of the results\n- each section object must have an `identifier`\n- each section object can specify a `type`\n- each section object can override the default `numResults` of 8";
@@ -23,3 +23,6 @@ export declare const zeroStateSectionsDescription = "Use `zeroStateSections` to
 export declare const openOnFocusDescription = "Use `openOnFocus: false` to show suggestions after a user clears their query, but not when they initially apply focus to the search input field";
 export declare const multipleSectionsDescription = "Use as many different `recommendations` and `custom` sections as you'd like and in whatever order you would like!";
 export declare const customStylesDescription = "\nBy default, importing react components or hooks from this library does not pull any css into your project.\n\nIf you wish to use some starter styles from this library, add an import statement similar to the example import statement below:\n\n`\nimport '@constructor-io/constructorio-ui-autocomplete/styles.css';\n`\n\n<i></i>\n\n- To opt out of all default styling, do not import the `styles.css` stylesheet.\n- The path and syntax in the example above may change depending on your module bundling strategy\n- These starter styles can be used as a foundation to build on top of, or just as a reference for you to replace completely.\n- All starter styles in this library are scoped within the `.cio-autocomplete` css selector.\n- These starter styles are intended to be extended by layering in your own css rules\n- If you like, you can override the container's className like so:\n`autocompleteClassName='custom-autocomplete-container'`\n- If you like, you can pass additional className(s) of your choosing like so:\n`autocompleteClassName='cio-autocomplete custom-autocomplete-container'`\n\n\n```css\n/* Custom Style Sheet */\n.cio-autocomplete.custom-autocomplete-styles form {\n  height: 44px;\n  width: 600px;\n  border-radius: 8px;\n  background-color: rgb(247, 247, 247);\n}\n\n.cio-autocomplete.custom-autocomplete-styles .cio-input {\n  font-weight: bold;\n}\n\n.cio-autocomplete.custom-autocomplete-styles .cio-form button {\n  width: 44px;\n}\n\n.cio-autocomplete.custom-autocomplete-styles .cio-clear-btn {\n  right: 24px;\n}\n\n.cio-autocomplete.custom-autocomplete-styles .cio-sectionName {\n  margin: 5px 3px;\n}\n\n.cio-autocomplete.custom-autocomplete-styles .cio-results {\n  width: 620px;\n  max-height: 334px;\n  overflow: hidden;\n  border-radius: 0px 0px 8px 8px;\n  color: rgb(51, 51, 51);\n}\n\n.cio-autocomplete.custom-autocomplete-styles .Products p {\n  padding: 5px 5px 0;\n}\n```\n";
+export declare const advancedParametersDescription = "Pass an `advancedParameters` object to configure more options for the data included in the results requested from constructor's servers. The stories below show examples of the optional fields within this `advancedParameters` object that can be used to fine-tune the autosuggest data returned from constructor's servers.";
+export declare const advancedParametersDefaultDescription = "Passing an `advancedParameters` object is optional. Passing an empty object for the `advancedParameters` field behaves the same as not passing an `advancedParameters` object at all. This has no impact on the results returned by default.";
+export declare const termsWithGroupSuggestionsDescription = "Pass integers for the `numTermsWithGroupSuggestions` and `numGroupsSuggestedPerTerm` fields to add suggested group filters to search term suggestions. Not all suggested search terms will have group filters, so these integers are upper limits, used to specify the maximum number of terms with group filters and the maximum number of suggested group filters per term. To see this in action:\n- type \"bab\" in the example below. Notice how the user is presented with a search term of \"baby\" as well as \"baby in Bodysuits\" and \"baby in Baby Organic Cotton\"\n- navigate to the \"Terms With Group Suggestions\" story (using the navigation menu to the left), then use the Controls to adjust the values of `numTermsWithGroupSuggestions` to `3` and `numGroupsSuggestedPerTerm` to `1`. Next, type \"dan\" in the example autocomplete input field. Notice how the user is presented with three different search terms that have a maximum of one \"in {group}\" suggestion each";

package/lib/types/hooks/useCioAutocomplete.d.ts

@@ -1,5 +1,5 @@
-import { CioAutocompleteProps, Item, Section } from '../types';
-export declare const defaultSections: Section[];
+import { CioAutocompleteProps, Item, Section, UserDefinedSection } from '../types';
+export declare const defaultSections: UserDefinedSection[];
 export type UseCioAutocompleteOptions = Omit<CioAutocompleteProps, 'children'>;
 declare const useCioAutocomplete: (options: UseCioAutocompleteOptions) => {
     query: string;

package/lib/types/hooks/useDebouncedFetchSections.d.ts

@@ -1,5 +1,5 @@
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
 import { Nullable } from '@constructor-io/constructorio-client-javascript/lib/types/types';
-import { AutocompleteResultSections, Section } from '../types';
-declare const useDebouncedFetchSection: (query: string, cioClient: Nullable<ConstructorIOClient>, autocompleteSections?: Section[]) => AutocompleteResultSections;
+import { AutocompleteResultSections, UserDefinedSection, AdvancedParameters } from '../types';
+declare const useDebouncedFetchSection: (query: string, cioClient: Nullable<ConstructorIOClient>, autocompleteSections: UserDefinedSection[], advancedParameters: AdvancedParameters) => AutocompleteResultSections;
 export default useDebouncedFetchSection;

package/lib/types/typeGuards.d.ts

@@ -1,2 +1,4 @@
-import { Item, Product } from './types';
+import { CustomSection, InGroupSuggestion, Item, Product, UserDefinedSection } from './types';
 export declare function isProduct(item: Item): item is Product;
+export declare function isInGroupSuggestion(item: Item): item is InGroupSuggestion;
+export declare function isCustomSection(config: UserDefinedSection): config is CustomSection;

package/lib/types/types.d.ts

@@ -5,6 +5,10 @@ export type CioClientConfig = {
     apiKey?: string;
     cioJsClient?: ConstructorIOClient;
 };
+export type AdvancedParameters = {
+    numTermsWithGroupSuggestions?: number;
+    numGroupsSuggestedPerTerm?: number;
+};
 export type CioAutocompleteProps = CioClientConfig & {
     openOnFocus?: boolean;
     onSubmit: OnSubmit;
@@ -12,9 +16,10 @@ export type CioAutocompleteProps = CioClientConfig & {
     onChange?: () => void;
     placeholder?: string;
     children?: ReactNode;
-    sections?: Section[];
-    zeroStateSections?: Section[];
+    sections?: UserDefinedSection[];
+    zeroStateSections?: UserDefinedSection[];
     autocompleteClassName?: string;
+    advancedParameters?: AdvancedParameters;
 };
 export type AutocompleteSubmitEvent = {
     item: Item;
@@ -31,13 +36,13 @@ export type ItemPropsOptions = DownshiftGetItemPropsOptions & {
 };
 export type GetItemProps = (options: ItemPropsOptions) => object;
 export interface ItemBase extends Record<string, any> {
-    id?: string;
+    id: string;
+    section: string;
     url?: string;
     value?: string;
-    section: string;
     data?: Record<string, any>;
 }
-export type Item = Product | SearchSuggestion | ItemBase;
+export type Item = Product | SearchSuggestion | InGroupSuggestion | ItemBase;
 export type GetAutocompleteResultsOptions = {
     [sectionIdentifier: string]: {
         numResults: number;
@@ -56,11 +61,11 @@ export type SectionConfiguration = {
 };
 export interface AutocompleteSection extends SectionConfiguration {
     type?: 'autocomplete';
-    data?: Item[];
+    data: Item[];
 }
 export interface RecommendationsSection extends SectionConfiguration {
     type: 'recommendations';
-    data?: Item[];
+    data: Item[];
     itemIds?: string[];
     section?: string;
     term?: string;
@@ -70,7 +75,9 @@ export interface CustomSection extends SectionConfiguration {
     data: Item[];
 }
 export type Section = AutocompleteSection | RecommendationsSection | CustomSection;
-export type Product = {
+export type UserDefinedSection = CustomSection | SectionConfiguration;
+export type Product = ItemBase & {
+    section: 'Products';
     data: {
         facets: {
             name: string;
@@ -79,27 +86,27 @@ export type Product = {
         group_ids: string[];
         id: string;
         image_url: string;
-        price: number;
-        swatchColor: string;
         url: string;
-        variation_id: string;
+        variation_id?: string;
     };
     is_slotted: boolean;
     labels: Record<string, unknown>;
     matched_terms: string[];
     value: string;
-    section: 'Products';
 };
-export type SearchSuggestion = {
+export type SearchSuggestion = ItemBase & {
+    section: 'Search Suggestions';
     data: {
         id: string;
         url?: string;
     };
-    id: string;
     is_slotted: boolean;
     labels: Record<string, unknown>;
     matched_terms: string[];
     value: string;
-    section: 'Search Suggestions';
+};
+export type InGroupSuggestion = SearchSuggestion & {
+    groupId: string;
+    groupName: string;
 };
 export {};

package/lib/types/utils.d.ts

@@ -1,8 +1,8 @@
 import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';
-import { OnSubmit, Section, Item } from './types';
+import { OnSubmit, Item } from './types';
 export type GetItemPosition = (args: {
     item: Item;
-    activeSectionsWithData: Section[];
+    items: Item[];
 }) => {
     index: number;
     sectionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructor-io/constructorio-ui-autocomplete",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Constructor.io Autocomplete UI library for web applications",
   "main": "lib/cjs/index.js",
   "module": "lib/mjs/index.js",