feat(recommend): add Trending-Facets model

examples/react/getting-started/src/App.tsx

@@ -9,7 +9,7 @@ import {
   Pagination,
   RefinementList,
   SearchBox,
-  TrendingItems,
+  TrendingFacets,
   Carousel,
 } from 'react-instantsearch';
 
@@ -61,10 +61,15 @@ export function App() {
                 <Pagination />
               </div>
               <div>
-                <TrendingItems
-                  itemComponent={ItemComponent}
+                <TrendingFacets
+                  facetName="brand"
                   limit={6}
                   layoutComponent={Carousel}
+                  itemComponent={({ item }) => (
+                    <div>
+                      {item.facetName}:{item.facetValue}
+                    </div>
+                  )}
                 />
               </div>
             </div>
@@ -96,17 +101,3 @@ function HitComponent({ hit }: { hit: HitType }) {
     </article>
   );
 }
-
-function ItemComponent({ item }: { item: Hit }) {
-  return (
-    <div>
-      <article>
-        <div>
-          <img src={item.image} />
-          <h2>{item.name}</h2>
-        </div>
-        <a href={`/products.html?pid=${item.objectID}`}>See product</a>
-      </article>
-    </div>
-  );
-}

packages/algoliasearch-helper/types/algoliasearch.d.ts

@@ -182,6 +182,24 @@ export type RecommendResponses<T> = PickForClient<{
   v5: AlgoliaSearch.GetRecommendationsResponse;
 }>;
 
+export type TrendingFacetHit = PickForClient<{
+  v3: any;
+  // @ts-ignore
+  v4: {
+    readonly _score: number;
+    readonly facetName: string;
+    readonly facetValue: string;
+  } & {
+    __position: number;
+    __queryID?: string;
+  };
+  // @ts-ignore
+  v5: RecommendClient.TrendingFacetHit & {
+    __position: number;
+    __queryID?: string;
+  };
+}>;
+
 // We remove `indexName` from the Recommend query types as the helper
 // will fill in this value before sending the queries
 type _OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

packages/instantsearch-ui-components/src/components/Carousel.tsx

@@ -1,7 +1,9 @@
 /** @jsx createElement */
+
 import { cx } from '../lib';
 
 import { createDefaultItemComponent } from './recommend-shared';
+import { isTrendingFacetHit } from './TrendingFacets';
 
 import type {
   ComponentProps,
@@ -10,6 +12,7 @@ import type {
   RecordWithObjectID,
   Renderer,
   SendEventForHits,
+  TrendingFacetHit,
 } from '../types';
 
 export type CarouselProps<
@@ -20,7 +23,7 @@ export type CarouselProps<
   nextButtonRef: MutableRef<HTMLButtonElement | null>;
   previousButtonRef: MutableRef<HTMLButtonElement | null>;
   carouselIdRef: MutableRef<string>;
-  items: Array<RecordWithObjectID<TObject>>;
+  items: Array<RecordWithObjectID<TObject> | TrendingFacetHit>;
   itemComponent?: (
     props: RecommendItemComponentProps<RecordWithObjectID<TObject>> &
       TComponentProps
@@ -232,22 +235,41 @@ export function createCarouselComponent({ createElement, Fragment }: Renderer) {
             }
           }}
         >
-          {items.map((item, index) => (
-            <li
-              key={item.objectID}
-              className={cx(cssClasses.item)}
-              aria-roledescription="slide"
-              aria-label={`${index + 1} of ${items.length}`}
-              onClick={() => {
-                sendEvent('click:internal', item, 'Item Clicked');
-              }}
-              onAuxClick={() => {
-                sendEvent('click:internal', item, 'Item Clicked');
-              }}
-            >
-              <ItemComponent item={item} sendEvent={sendEvent} />
-            </li>
-          ))}
+          {items.map((item, index) =>
+            isTrendingFacetHit(item) ? (
+              <li
+                key={item.facetName + item.facetValue}
+                className={cx(cssClasses.item)}
+                aria-roledescription="slide"
+                aria-label={`${index + 1} of ${items.length}`}
+              >
+                <ItemComponent
+                  item={
+                    {
+                      ...item,
+                      objectID: item.facetName + item.facetValue,
+                    } as RecordWithObjectID<any>
+                  }
+                  sendEvent={sendEvent}
+                />
+              </li>
+            ) : (
+              <li
+                key={item.objectID}
+                className={cx(cssClasses.item)}
+                aria-roledescription="slide"
+                aria-label={`${index + 1} of ${items.length}`}
+                onClick={() => {
+                  sendEvent('click:internal', item, 'Item Clicked');
+                }}
+                onAuxClick={() => {
+                  sendEvent('click:internal', item, 'Item Clicked');
+                }}
+              >
+                <ItemComponent item={item} sendEvent={sendEvent} />
+              </li>
+            )
+          )}
         </ol>
 
         <button

packages/instantsearch-ui-components/src/components/TrendingFacets.tsx

@@ -0,0 +1,158 @@
+/** @jsx createElement */
+
+import { cx } from '../lib';
+
+import {
+  createDefaultEmptyComponent,
+  createDefaultHeaderComponent,
+} from './recommend-shared';
+
+import type {
+  ComponentProps,
+  RecommendClassNames,
+  RecommendInnerComponentProps,
+  RecommendItemComponentProps,
+  RecommendStatus,
+  RecommendTranslations,
+  RecordWithObjectID,
+  Renderer,
+  SendEventForHits,
+  TrendingFacetHit,
+} from '../types';
+
+type TrendingFacetLayoutProps<TClassNames extends Record<string, string>> = {
+  classNames: TClassNames;
+  itemComponent: (
+    props: RecommendItemComponentProps<TrendingFacetHit>
+  ) => JSX.Element;
+  items: TrendingFacetHit[];
+  sendEvent: SendEventForHits;
+};
+
+export type TrendingFacetsComponentProps<
+  TComponentProps extends Record<string, unknown> = Record<string, unknown>
+> = {
+  itemComponent: (
+    props: RecommendItemComponentProps<TrendingFacetHit> & TComponentProps
+  ) => JSX.Element;
+  items: TrendingFacetHit[];
+  sendEvent: SendEventForHits;
+  classNames?: Partial<RecommendClassNames>;
+  emptyComponent?: (props: TComponentProps) => JSX.Element;
+  headerComponent?: (
+    props: RecommendInnerComponentProps<TrendingFacetHit> & TComponentProps
+  ) => JSX.Element;
+  status: RecommendStatus;
+  translations?: Partial<RecommendTranslations>;
+  layout?: (
+    props: TrendingFacetLayoutProps<Record<string, string>> & TComponentProps
+  ) => JSX.Element;
+};
+
+export type TrendingFacetsProps<
+  TComponentProps extends Record<string, unknown> = Record<string, unknown>
+> = ComponentProps<'div'> & TrendingFacetsComponentProps<TComponentProps>;
+
+export function createTrendingFacetsComponent({
+  createElement,
+  Fragment,
+}: Renderer) {
+  return function TrendingFacets(userProps: TrendingFacetsProps) {
+    const {
+      classNames = {},
+      emptyComponent: EmptyComponent = createDefaultEmptyComponent({
+        createElement,
+        Fragment,
+      }),
+      headerComponent: HeaderComponent = createDefaultHeaderComponent({
+        createElement,
+        Fragment,
+      }),
+      itemComponent: ItemComponent,
+      layout: Layout = createListComponent({ createElement, Fragment }),
+      items,
+      status,
+      translations: userTranslations,
+      sendEvent,
+      ...props
+    } = userProps;
+
+    const translations: Required<RecommendTranslations> = {
+      title: 'Trending facets',
+      sliderLabel: 'Trending facets',
+      ...userTranslations,
+    };
+
+    const cssClasses: RecommendClassNames = {
+      root: cx('ais-TrendingFacets', classNames.root),
+      emptyRoot: cx(
+        'ais-TrendingFacets',
+        classNames.root,
+        'ais-TrendingFacets--empty',
+        classNames.emptyRoot,
+        props.className
+      ),
+      title: cx('ais-TrendingFacets-title', classNames.title),
+      container: cx('ais-TrendingFacets-container', classNames.container),
+      list: cx('ais-TrendingFacets-list', classNames.list),
+      item: cx('ais-TrendingFacets-item', classNames.item),
+    };
+
+    if (items.length === 0 && status === 'idle') {
+      return (
+        <section {...props} className={cssClasses.emptyRoot}>
+          <EmptyComponent />
+        </section>
+      );
+    }
+
+    return (
+      <section {...props} className={cssClasses.root}>
+        <HeaderComponent
+          classNames={cssClasses}
+          items={items}
+          translations={translations}
+        />
+
+        <Layout
+          classNames={cssClasses}
+          itemComponent={ItemComponent}
+          items={items}
+          sendEvent={sendEvent}
+        />
+      </section>
+    );
+  };
+}
+
+export function createListComponent({ createElement }: Renderer) {
+  return function List(
+    userProps: TrendingFacetLayoutProps<Partial<RecommendClassNames>>
+  ) {
+    const {
+      classNames = {},
+      itemComponent: ItemComponent,
+      items,
+      sendEvent,
+    } = userProps;
+
+    return (
+      <div className={classNames.container}>
+        <ol className={classNames.list}>
+          {items.map((item) => (
+            <li
+              key={item.facetName + item.facetValue}
+              className={classNames.item}
+            >
+              <ItemComponent item={item} sendEvent={sendEvent} />
+            </li>
+          ))}
+        </ol>
+      </div>
+    );
+  };
+}
+
+export const isTrendingFacetHit = (
+  item: RecordWithObjectID<any> | TrendingFacetHit
+): item is TrendingFacetHit => !item.objectID && 'facetValue' in item;

packages/instantsearch-ui-components/src/components/index.ts

@@ -5,3 +5,4 @@ export * from './Hits';
 export * from './LookingSimilar';
 export * from './RelatedProducts';
 export * from './TrendingItems';
+export * from './TrendingFacets';