feat(autocomplete): support header template for autocomplete index

bundlesize.config.json

@@ -10,7 +10,7 @@
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.production.min.js",
-      "maxSize": "87.75 kB"
+      "maxSize": "88 kB"
     },
     {
       "path": "./packages/instantsearch.js/dist/instantsearch.development.js",
@@ -46,7 +46,7 @@
     },
     {
       "path": "./packages/instantsearch.css/themes/algolia-min.css",
-      "maxSize": "8 kB"
+      "maxSize": "8.25 kB"
     },
     {
       "path": "./packages/instantsearch.css/themes/reset.css",
@@ -62,7 +62,7 @@
     },
     {
       "path": "./packages/instantsearch.css/themes/satellite-min.css",
-      "maxSize": "9 kB"
+      "maxSize": "9.25 kB"
     },
     {
       "path": "./packages/instantsearch.css/components/chat.css",

packages/instantsearch-ui-components/src/components/autocomplete/AutocompleteIndex.tsx

@@ -8,6 +8,7 @@ export type AutocompleteIndexProps<
   T = { objectID: string; __indexName: string } & Record<string, unknown>
 > = {
   items: T[];
+  HeaderComponent?: (props: { items: T[] }) => JSX.Element;
   ItemComponent: (props: { item: T; onSelect: () => void }) => JSX.Element;
   getItemProps: (
     item: T,
@@ -25,6 +26,10 @@ export type AutocompleteIndexClassNames = {
    * Class names to apply to the list element
    */
   list: string | string[];
+  /**
+   * Class names to apply to the header element
+   */
+  header: string | string[];
   /**
    * Class names to apply to each item element
    */
@@ -33,10 +38,21 @@ export type AutocompleteIndexClassNames = {
 
 export function createAutocompleteIndexComponent({ createElement }: Renderer) {
   return function AutocompleteIndex(userProps: AutocompleteIndexProps) {
-    const { items, ItemComponent, getItemProps, classNames = {} } = userProps;
+    const {
+      items,
+      HeaderComponent,
+      ItemComponent,
+      getItemProps,
+      classNames = {},
+    } = userProps;
 
     return (
       <div className={cx('ais-AutocompleteIndex', classNames.root)}>
+        {HeaderComponent && (
+          <div className={cx('ais-AutocompleteIndexHeader', classNames.header)}>
+            <HeaderComponent items={items} />
+          </div>
+        )}
         <ol className={cx('ais-AutocompleteIndexList', classNames.list)}>
           {items.map((item, index) => {
             const { className, onSelect, ...itemProps } = getItemProps(

packages/instantsearch.css/src/components/autocomplete.scss

@@ -303,6 +303,47 @@
   }
 }
 
+// Header
+.ais-AutocompleteIndexHeader {
+  margin: var(--ais-autocomplete-spacing-half) 0.5em var(--ais-autocomplete-spacing-half) 0;
+  padding: 0;
+  position: relative;
+
+
+  &:empty {
+    display: none;
+  }
+}
+
+.ais-AutocompleteIndexHeaderTitle {
+  background: rgba(
+    var(--ais-autocomplete-background-color-rgb),
+    var(--ais-autocomplete-background-color-alpha)
+  );
+  color: rgba(var(--ais-autocomplete-primary-color-rgb), 1);
+  display: inline-block;
+  font-size: 0.8em;
+  font-weight: var(--ais-autocomplete-font-weight-semibold);
+  margin: 0;
+  padding: 0 var(--ais-autocomplete-spacing-half) 0 0;
+  position: relative;
+  z-index: var(--ais-autocomplete-base-z-index);
+}
+
+.ais-AutocompleteIndexHeaderLine {
+  border-bottom: solid 1px rgba(var(--ais-autocomplete-primary-color-rgb), 1);
+  display: block;
+  height: 2px;
+  left: 0;
+  margin: 0;
+  opacity: 0.3;
+  padding: 0;
+  position: absolute;
+  right: 0;
+  top: var(--ais-autocomplete-spacing-half);
+  z-index: calc(var(--ais-autocomplete-base-z-index) - 1);
+}
+
 // Items
 .ais-AutocompleteIndexItem {
   align-items: center;

packages/instantsearch.js/src/widgets/autocomplete/autocomplete.tsx

@@ -230,6 +230,22 @@ function AutocompleteWrapper<TItem extends BaseHit>({
               templates: indicesConfig[i].templates,
             });
           }
+          const headerComponent = indicesConfig[i].templates?.header
+            ? ({
+                items,
+              }: Parameters<
+                NonNullable<AutocompleteIndexProps['HeaderComponent']>
+              >[0]) => {
+                return (
+                  <TemplateComponent
+                    {...renderState.indexTemplateProps[i]}
+                    templateKey="header"
+                    rootTagName="fragment"
+                    data={{ items }}
+                  />
+                );
+              }
+            : undefined;
           const itemComponent = ({
             item,
             onSelect,
@@ -247,6 +263,7 @@ function AutocompleteWrapper<TItem extends BaseHit>({
           return (
             <AutocompleteIndex
               key={indexId}
+              HeaderComponent={headerComponent}
               ItemComponent={itemComponent}
               items={hits.map((item) => ({ ...item, __indexName: indexId }))}
               getItemProps={getItemProps}
@@ -267,6 +284,10 @@ export type AutocompleteTemplates<TItem extends BaseHit> = Partial<
 
 type IndexConfig<TItem extends BaseHit> = AutocompleteIndexConfig<TItem> & {
   templates?: Partial<{
+    /**
+     * Template to use for the header, before the list of items.
+     */
+    header: Template<{ items: TItem[] }>;
     /**
      * Template to use for each result. This template will receive an object containing a single record.
      */
@@ -344,22 +365,28 @@ export function EXPERIMENTAL_autocomplete<TItem extends BaseHit = BaseHit>(
 
   const indicesConfig = [...indices];
   if (showSuggestions?.indexName) {
-    const suggestionsSuit = component('AutocompleteSuggestions');
     indicesConfig.unshift({
       indexName: showSuggestions.indexName,
       templates: {
-        // Temporarily force casting until the coming refactoring
-        item: (showSuggestions.templates?.item ||
-          AutocompleteSuggestion) as unknown as Template<{ item: TItem }>,
+        // @ts-expect-error
+        item: AutocompleteSuggestion,
+        ...showSuggestions.templates,
       },
       cssClasses: {
-        root: cx(suggestionsSuit(), showSuggestions.cssClasses?.root),
+        root: cx(
+          'ais-AutocompleteSuggestions',
+          showSuggestions.cssClasses?.root
+        ),
         list: cx(
-          suggestionsSuit({ descendantName: 'list' }),
+          'ais-AutocompleteSuggestionsList',
           showSuggestions.cssClasses?.list
         ),
+        header: cx(
+          'ais-AutocompleteSuggestionsHeader',
+          showSuggestions.cssClasses?.header
+        ),
         item: cx(
-          suggestionsSuit({ descendantName: 'item' }),
+          'ais-AutocompleteSuggestionsItem',
           showSuggestions.cssClasses?.item
         ),
       },

packages/react-instantsearch/src/widgets/Autocomplete.tsx

@@ -30,8 +30,9 @@ import type {
   AutocompleteIndexConfig,
   Pragma,
   AutocompleteClassNames,
+  AutocompleteIndexProps,
 } from 'instantsearch-ui-components';
-import type { BaseHit, Hit, IndexUiState } from 'instantsearch.js';
+import type { BaseHit, IndexUiState } from 'instantsearch.js';
 import type { ComponentProps } from 'react';
 
 const Autocomplete = createAutocompleteComponent({
@@ -62,13 +63,9 @@ const usePropGetters = createAutocompletePropGetters({
   useState,
 });
 
-type ItemComponentProps<TItem extends BaseHit> = React.ComponentType<{
-  item: Hit<TItem>;
-  onSelect: () => void;
-}>;
-
 type IndexConfig<TItem extends BaseHit> = AutocompleteIndexConfig<TItem> & {
-  itemComponent: ItemComponentProps<TItem>;
+  headerComponent?: AutocompleteIndexProps<TItem>['HeaderComponent'];
+  itemComponent: AutocompleteIndexProps<TItem>['ItemComponent'];
   classNames?: Partial<AutocompleteIndexClassNames>;
 };
 
@@ -77,7 +74,11 @@ export type AutocompleteProps<TItem extends BaseHit> = ComponentProps<'div'> & {
   showSuggestions?: Partial<
     Pick<
       IndexConfig<{ query: string }>,
-      'indexName' | 'getURL' | 'itemComponent' | 'classNames'
+      | 'indexName'
+      | 'getURL'
+      | 'headerComponent'
+      | 'itemComponent'
+      | 'classNames'
     >
   >;
   getSearchPageURL?: (nextUiState: IndexUiState) => string;
@@ -109,9 +110,10 @@ export function EXPERIMENTAL_Autocomplete<TItem extends BaseHit = BaseHit>({
   if (showSuggestions?.indexName) {
     indicesConfig.unshift({
       indexName: showSuggestions.indexName,
-      // Temporarily force casting until the coming refactoring
+      headerComponent:
+        showSuggestions.headerComponent as unknown as AutocompleteIndexProps<TItem>['HeaderComponent'],
       itemComponent: (showSuggestions.itemComponent ||
-        AutocompleteSuggestion) as unknown as ItemComponentProps<TItem>,
+        AutocompleteSuggestion) as unknown as AutocompleteIndexProps<TItem>['ItemComponent'],
       classNames: {
         root: cx(
           'ais-AutocompleteSuggestions',
@@ -121,6 +123,10 @@ export function EXPERIMENTAL_Autocomplete<TItem extends BaseHit = BaseHit>({
           'ais-AutocompleteSuggestionsList',
           showSuggestions?.classNames?.list
         ),
+        header: cx(
+          'ais-AutocompleteSuggestionsHeader',
+          showSuggestions?.classNames?.header
+        ),
         item: cx(
           'ais-AutocompleteSuggestionsItem',
           showSuggestions?.classNames?.item
@@ -206,6 +212,8 @@ function InnerAutocomplete<TItem extends BaseHit = BaseHit>({
           <AutocompleteIndex
             key={indexId}
             // @ts-expect-error - there seems to be problems with React.ComponentType and this, but it's actually correct
+            HeaderComponent={indicesConfig[index].headerComponent}
+            // @ts-expect-error - there seems to be problems with React.ComponentType and this, but it's actually correct
             ItemComponent={indicesConfig[index].itemComponent}
             items={hits.map((item) => ({
               ...item,

tests/common/widgets/autocomplete/index.ts

@@ -1,6 +1,7 @@
 import { fakeAct, skippableDescribe } from '../../common';
 
 import { createOptionsTests } from './options';
+import { createTemplatesTests } from './templates';
 
 import type { TestOptions, TestSetup } from '../../common';
 import type { AutocompleteConnectorParams } from 'instantsearch.js/es/connectors/autocomplete/connectAutocomplete';
@@ -38,6 +39,7 @@ export function createAutocompleteWidgetTests(
 
   skippableDescribe('Autocomplete widget common tests', skippedTests, () => {
     createOptionsTests(setup, { act, skippedTests, flavor });
+    createTemplatesTests(setup, { act, skippedTests, flavor });
   });
 }
 createAutocompleteWidgetTests.flavored = true;