feat(recommend): add Trending-Facets model

examples/js/getting-started/src/app.js

@@ -8,7 +8,7 @@ import {
   panel,
   refinementList,
   searchBox,
-  trendingItems,
+  trendingFacets,
 } from 'instantsearch.js/es/widgets';
 
 import 'instantsearch.css/themes/satellite.css';
@@ -56,19 +56,14 @@ search.addWidgets([
   pagination({
     container: '#pagination',
   }),
-  trendingItems({
+  trendingFacets({
     container: '#trending',
     limit: 6,
+    facetName: 'brand',
     templates: {
       item: (item, { html }) => html`
         <div>
-          <article>
-            <div>
-              <img src="${item.image}" />
-              <h2>${item.name}</h2>
-            </div>
-            <a href="/products.html?pid=${item.objectID}">See product</a>
-          </article>
+          <h2>${item.facetName}: ${item.facetValue}</h2>
         </div>
       `,
       layout: carousel(),

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

@@ -9,7 +9,7 @@ import {
   Pagination,
   RefinementList,
   SearchBox,
-  TrendingItems,
+  TrendingFacets,
   Carousel,
 } from 'react-instantsearch';
 
@@ -61,8 +61,8 @@ export function App() {
                 <Pagination />
               </div>
               <div>
-                <TrendingItems
-                  itemComponent={ItemComponent}
+                <TrendingFacets
+                  facetName="brand"
                   limit={6}
                   layoutComponent={Carousel}
                 />
@@ -96,17 +96,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/instantsearch-ui-components/src/components/Carousel.tsx

@@ -2,6 +2,7 @@
 import { cx } from '../lib';
 
 import { createDefaultItemComponent } from './recommend-shared';
+import { isTrendingFacetHit } from './TrendingFacets';
 
 import type {
   ComponentProps,
@@ -11,6 +12,7 @@ import type {
   Renderer,
   SendEventForHits,
 } from '../types';
+import type { TrendingFacetHit } from './TrendingFacets';
 
 export type CarouselProps<
   TObject,
@@ -20,7 +22,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 +234,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,167 @@
+/** @jsx createElement */
+
+import { cx } from '../lib';
+
+import {
+  createDefaultEmptyComponent,
+  createDefaultHeaderComponent,
+  createDefaultItemComponent,
+} from './recommend-shared';
+
+import type {
+  ComponentProps,
+  RecommendClassNames,
+  RecommendInnerComponentProps,
+  RecommendItemComponentProps,
+  RecommendStatus,
+  RecommendTranslations,
+  RecordWithObjectID,
+  Renderer,
+  SendEventForHits,
+} from '../types';
+import type { TrendingFacetHit as Base } from 'algoliasearch/lite';
+
+export type TrendingFacetHit = Base & {
+  __position: number;
+  __queryID?: string;
+};
+
+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 = createDefaultItemComponent({
+        createElement,
+        Fragment,
+      }),
+      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';

packages/instantsearch.js/src/connectors/index.ts

@@ -54,3 +54,5 @@ export { default as connectVoiceSearch } from './voice-search/connectVoiceSearch
 export { default as connectRelevantSort } from './relevant-sort/connectRelevantSort';
 export { default as connectFrequentlyBoughtTogether } from './frequently-bought-together/connectFrequentlyBoughtTogether';
 export { default as connectLookingSimilar } from './looking-similar/connectLookingSimilar';
+export { default as connectTrendingFacets } from './trending-facets/connectTrendingFacets';
+export type { TrendingFacetHit } from './trending-facets/connectTrendingFacets';