instantsearch.js 4.68.0 → 4.69.0

package/dist/instantsearch.production.d.ts

@@ -4,6 +4,7 @@
 import type { AlgoliaSearchHelper } from 'algoliasearch-helper';
 import EventEmitter from '@algolia/events';
 import { FindAnswersOptions } from 'algoliasearch-helper/types/algoliasearch.js';
+import type { FrequentlyBoughtTogetherProps } from 'instantsearch-ui-components';
 import { h } from 'preact';
 import type { HighlightClassNames as HighlightClassNames_2 } from 'instantsearch-ui-components';
 import type { HighlightProps as HighlightProps_3 } from 'instantsearch-ui-components';
@@ -12,14 +13,19 @@ import type { HoganOptions } from 'hogan.js';
 import type { html } from 'htm/preact';
 import type { InsightsClient as InsightsClient_2 } from 'search-insights';
 import type { InsightsMethodMap as InsightsMethodMap_2 } from 'search-insights';
+import type { LookingSimilarProps } from 'instantsearch-ui-components';
 import type * as Places from 'places.js';
 import type { PlainSearchParameters } from 'algoliasearch-helper';
 import { default as qs_2 } from 'qs';
+import type { RecommendClassNames } from 'instantsearch-ui-components';
 import type { RecommendParameters } from 'algoliasearch-helper';
+import type { RecommendResultItem } from 'algoliasearch-helper';
+import type { RelatedProductsProps } from 'instantsearch-ui-components';
 import { SearchClient } from 'algoliasearch-helper/types/algoliasearch.js';
 import { SearchOptions } from 'algoliasearch-helper/types/algoliasearch.js';
 import type { SearchParameters } from 'algoliasearch-helper';
 import type { SearchResults } from 'algoliasearch-helper';
+import type { TrendingItemsProps } from 'instantsearch-ui-components';
 import { VNode } from 'preact';
 
 declare type AlgoliaHit<THit extends BaseHit = Record<string, any>> = {
@@ -735,6 +741,8 @@ declare const connectCurrentRefinements: CurrentRefinementsConnector;
 
 declare const connectDynamicWidgets: DynamicWidgetsConnector;
 
+declare const connectFrequentlyBoughtTogether: FrequentlyBoughtTogetherConnector;
+
 /**
  * The **GeoSearch** connector provides the logic to build a widget that will display the results on a map. It also provides a way to search for results based on their position. The connector provides functions to manage the search experience (search on map interaction or control the interaction for example).
  *
@@ -771,6 +779,8 @@ declare const connectInfiniteHits: InfiniteHitsConnector;
 
 declare const connectInfiniteHitsWithInsights: InfiniteHitsConnector<BaseHit>;
 
+declare const connectLookingSimilar: LookingSimilarConnector;
+
 /**
  * **Menu** connector provides the logic to build a widget that will give the user the ability to choose a single value for a specific facet. The typical usage of menu is for navigation in categories.
  *
@@ -820,11 +830,13 @@ declare namespace connectors {
         connectPagination,
         connectRange,
         connectRefinementList,
+        connectRelatedProducts,
         connectSearchBox,
         connectSortBy,
         connectRatingMenu,
         connectStats,
         connectToggleRefinement,
+        connectTrendingItems,
         connectBreadcrumb,
         connectGeoSearch,
         connectPoweredBy,
@@ -833,7 +845,9 @@ declare namespace connectors {
         connectAutocomplete,
         connectQueryRules,
         connectVoiceSearch,
-        connectRelevantSort
+        connectRelevantSort,
+        connectFrequentlyBoughtTogether,
+        connectLookingSimilar
     }
 }
 
@@ -889,6 +903,8 @@ declare const connectRatingMenu: RatingMenuConnector;
  */
 declare const connectRefinementList: RefinementListConnector;
 
+declare const connectRelatedProducts: RelatedProductsConnector;
+
 declare const connectRelevantSort: RelevantSortConnector;
 
 /**
@@ -913,6 +929,8 @@ declare const connectStats: StatsConnector;
  */
 declare const connectToggleRefinement: ToggleRefinementConnector;
 
+declare const connectTrendingItems: TrendingItemsConnector;
+
 declare const connectVoiceSearch: VoiceSearchConnector;
 
 declare function createInfiniteHitsSessionStorageCache(): InfiniteHitsCache;
@@ -1120,6 +1138,7 @@ declare const _default: PlacesWidget;
 declare type DisposeOptions = {
     helper: AlgoliaSearchHelper;
     state: SearchParameters;
+    recommendState: RecommendParameters;
     parent: IndexWidget;
 };
 
@@ -1229,6 +1248,91 @@ declare const EXPERIMENTAL_dynamicWidgets: DynamicWidgetsWidget;
 
 declare type FacetValue = string | boolean | number;
 
+declare const frequentlyBoughtTogether: FrequentlyBoughtTogetherWidget;
+
+declare type FrequentlyBoughtTogetherConnector<THit extends BaseHit = BaseHit> = Connector<FrequentlyBoughtTogetherWidgetDescription<THit>, FrequentlyBoughtTogetherConnectorParams<THit>>;
+
+declare type FrequentlyBoughtTogetherConnectorParams<THit extends BaseHit = BaseHit> = {
+    /**
+     * The objectIDs of the items to get the frequently bought together items for.
+     */
+    objectIDs: string[];
+    /**
+     * Threshold for the recommendations confidence score (between 0 and 100). Only recommendations with a greater score are returned.
+     */
+    threshold?: number;
+    /**
+     * The maximum number of recommendations to return.
+     */
+    limit?: number;
+    /**
+     * Parameters to pass to the request.
+     */
+    queryParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * Whether to escape HTML tags from items string values.
+     *
+     * @default true
+     */
+    escapeHTML?: boolean;
+    /**
+     * Function to transform the items passed to the templates.
+     */
+    transformItems?: TransformItems<Hit<THit>, {
+        results: RecommendResultItem;
+    }>;
+};
+
+declare type FrequentlyBoughtTogetherCSSClasses = Partial<RecommendClassNames>;
+
+declare type FrequentlyBoughtTogetherRenderState<THit extends BaseHit = BaseHit> = {
+    /**
+     * The matched recommendations from Algolia API.
+     */
+    items: Array<Hit<THit>>;
+};
+
+declare type FrequentlyBoughtTogetherTemplates = Partial<{
+    /**
+     * Template to use when there are no results.
+     */
+    empty: Template<RecommendResultItem>;
+    /**
+     * Template to use for the header of the widget.
+     */
+    header: Template<Pick<Parameters<NonNullable<FrequentlyBoughtTogetherProps<Hit>['headerComponent']>>[0], 'items'> & {
+        cssClasses: RecommendClassNames;
+    }>;
+    /**
+     * Template to use for each result. This template will receive an object containing a single record.
+     */
+    item: Template<Hit>;
+}>;
+
+declare type FrequentlyBoughtTogetherWidget = WidgetFactory<FrequentlyBoughtTogetherWidgetDescription & {
+    $$widgetType: 'ais.frequentlyBoughtTogether';
+}, FrequentlyBoughtTogetherConnectorParams, FrequentlyBoughtTogetherWidgetParams>;
+
+declare type FrequentlyBoughtTogetherWidgetDescription<THit extends BaseHit = BaseHit> = {
+    $$type: 'ais.frequentlyBoughtTogether';
+    renderState: FrequentlyBoughtTogetherRenderState<THit>;
+};
+
+declare type FrequentlyBoughtTogetherWidgetParams = {
+    /**
+     * CSS Selector or HTMLElement to insert the widget.
+     */
+    container: string | HTMLElement;
+    /**
+     * Templates to use for the widget.
+     */
+    templates?: FrequentlyBoughtTogetherTemplates;
+    /**
+     * CSS classes to add.
+     */
+    cssClasses?: FrequentlyBoughtTogetherCSSClasses;
+};
+
 declare type GeoHit<THit extends BaseHit = Record<string, any>> = Hit<THit> & Required<Pick<Hit, '_geoloc'>>;
 
 declare type GeoLoc = {
@@ -2100,6 +2204,7 @@ declare type IndexWidget<TUiState extends UiState = UiState> = Omit<Widget<Index
     getIndexId: () => string;
     getHelper: () => AlgoliaSearchHelper | null;
     getResults: () => SearchResults | null;
+    getResultsForWidget: (widget: IndexWidget | Widget) => SearchResults | RecommendResultItem | null;
     getPreviousState: () => SearchParameters | null;
     getScopedResults: () => ScopedResult[];
     getParent: () => IndexWidget | null;
@@ -2401,6 +2506,8 @@ declare class InstantSearch<TUiState extends UiState = UiState, TRouteState = TU
     _createURL: CreateURL<TUiState>;
     _searchFunction?: InstantSearchOptions['searchFunction'];
     _mainHelperSearch?: AlgoliaSearchHelper['search'];
+    _hasSearchWidget: boolean;
+    _hasRecommendWidget: boolean;
     _insights: InstantSearchOptions['insights'];
     middleware: Array<{
         creator: Middleware<TUiState>;
@@ -2656,6 +2763,95 @@ declare type InternalMiddleware<TUiState extends UiState = UiState> = (options:
 
 declare function isMetadataEnabled(): boolean;
 
+declare const lookingSimilar: LookingSimilarWidget;
+
+declare type LookingSimilarConnector<THit extends BaseHit = BaseHit> = Connector<LookingSimilarWidgetDescription<THit>, LookingSimilarConnectorParams<THit>>;
+
+declare type LookingSimilarConnectorParams<THit extends BaseHit = BaseHit> = {
+    /**
+     * The `objectIDs` of the items to get similar looking products from.
+     */
+    objectIDs: string[];
+    /**
+     * The number of recommendations to retrieve.
+     */
+    limit?: number;
+    /**
+     * The threshold for the recommendations confidence score (between 0 and 100).
+     */
+    threshold?: number;
+    /**
+     * List of search parameters to send.
+     */
+    fallbackParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * List of search parameters to send.
+     */
+    queryParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * Whether to escape HTML tags from items string values.
+     *
+     * @default true
+     */
+    escapeHTML?: boolean;
+    /**
+     * Function to transform the items passed to the templates.
+     */
+    transformItems?: TransformItems<Hit<THit>, {
+        results: RecommendResultItem;
+    }>;
+};
+
+declare type LookingSimilarCSSClasses = Partial<RecommendClassNames>;
+
+declare type LookingSimilarRenderState<THit extends BaseHit = BaseHit> = {
+    /**
+     * The matched recommendations from the Algolia API.
+     */
+    items: Array<Hit<THit>>;
+};
+
+declare type LookingSimilarTemplates = Partial<{
+    /**
+     * Template to use when there are no results.
+     */
+    empty: Template<RecommendResultItem>;
+    /**
+     * Template to use for the header of the widget.
+     */
+    header: Template<Pick<Parameters<NonNullable<LookingSimilarProps<Hit>['headerComponent']>>[0], 'items'> & {
+        cssClasses: RecommendClassNames;
+    }>;
+    /**
+     * Template to use for each result. This template will receive an object containing a single record.
+     */
+    item: Template<Hit>;
+}>;
+
+declare type LookingSimilarWidget = WidgetFactory<LookingSimilarWidgetDescription & {
+    $$widgetType: 'ais.lookingSimilar';
+}, LookingSimilarConnectorParams, LookingSimilarWidgetParams>;
+
+declare type LookingSimilarWidgetDescription<THit extends BaseHit = BaseHit> = {
+    $$type: 'ais.lookingSimilar';
+    renderState: LookingSimilarRenderState<THit>;
+};
+
+declare type LookingSimilarWidgetParams = {
+    /**
+     * CSS Selector or HTMLElement to insert the widget.
+     */
+    container: string | HTMLElement;
+    /**
+     * Templates to use for the widget.
+     */
+    templates?: LookingSimilarTemplates;
+    /**
+     * CSS classes to add.
+     */
+    cssClasses?: LookingSimilarCSSClasses;
+};
+
 declare type MatchingPatterns = {
     [attribute: string]: {
         /**
@@ -4021,11 +4217,18 @@ declare type Read<THit extends BaseHit> = ({ state, }: {
     state: PlainSearchParameters;
 }) => InfiniteHitsCachedHits<THit> | null;
 
-declare type RecommendWidgetLifeCycle<TWidgetDescription extends WidgetDescription> = {
-    dependsOn?: 'recommend';
+declare type RecommendRenderOptions = SharedRenderOptions & {
+    results: RecommendResultItem;
+};
+
+declare type RecommendWidget<TWidgetDescription extends WidgetDescription & WidgetParams> = {
+    dependsOn: 'recommend';
+    $$id?: number;
     getWidgetParameters: (state: RecommendParameters, widgetParametersOptions: {
         uiState: Expand<Partial<TWidgetDescription['indexUiState'] & IndexUiState>>;
     }) => RecommendParameters;
+    getRenderState: (renderState: Expand<IndexRenderState & Partial<TWidgetDescription['indexRenderState']>>, renderOptions: InitOptions | RecommendRenderOptions) => IndexRenderState & TWidgetDescription['indexRenderState'];
+    getWidgetRenderState: (renderOptions: InitOptions | RecommendRenderOptions) => Expand<WidgetRenderState<TWidgetDescription['renderState'], TWidgetDescription['widgetParams']>>;
 };
 
 declare type ReconfigurableOptions = Places.ReconfigurableOptions;
@@ -4367,6 +4570,95 @@ declare type RefinementListWidgetParams = {
     cssClasses?: RefinementListCSSClasses;
 };
 
+declare const relatedProducts: RelatedProductsWidget;
+
+declare type RelatedProductsConnector<THit extends BaseHit = BaseHit> = Connector<RelatedProductsWidgetDescription<THit>, RelatedProductsConnectorParams<THit>>;
+
+declare type RelatedProductsConnectorParams<THit extends BaseHit = BaseHit> = {
+    /**
+     * The `objectIDs` of the items to get related products from.
+     */
+    objectIDs: string[];
+    /**
+     * The number of recommendations to retrieve.
+     */
+    limit?: number;
+    /**
+     * The threshold for the recommendations confidence score (between 0 and 100).
+     */
+    threshold?: number;
+    /**
+     * List of search parameters to send.
+     */
+    fallbackParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * List of search parameters to send.
+     */
+    queryParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * Whether to escape HTML tags from items string values.
+     *
+     * @default true
+     */
+    escapeHTML?: boolean;
+    /**
+     * Function to transform the items passed to the templates.
+     */
+    transformItems?: TransformItems<Hit<THit>, {
+        results: RecommendResultItem;
+    }>;
+};
+
+declare type RelatedProductsCSSClasses = Partial<RecommendClassNames>;
+
+declare type RelatedProductsRenderState<THit extends BaseHit = BaseHit> = {
+    /**
+     * The matched recommendations from the Algolia API.
+     */
+    items: Array<Hit<THit>>;
+};
+
+declare type RelatedProductsTemplates = Partial<{
+    /**
+     * Template to use when there are no results.
+     */
+    empty: Template<RecommendResultItem>;
+    /**
+     * Template to use for the header of the widget.
+     */
+    header: Template<Pick<Parameters<NonNullable<RelatedProductsProps<Hit>['headerComponent']>>[0], 'items'> & {
+        cssClasses: RecommendClassNames;
+    }>;
+    /**
+     * Template to use for each result. This template will receive an object containing a single record.
+     */
+    item: Template<Hit>;
+}>;
+
+declare type RelatedProductsWidget = WidgetFactory<RelatedProductsWidgetDescription & {
+    $$widgetType: 'ais.relatedProducts';
+}, RelatedProductsConnectorParams, RelatedProductsWidgetParams>;
+
+declare type RelatedProductsWidgetDescription<THit extends BaseHit = BaseHit> = {
+    $$type: 'ais.relatedProducts';
+    renderState: RelatedProductsRenderState<THit>;
+};
+
+declare type RelatedProductsWidgetParams = {
+    /**
+     * CSS selector or `HTMLElement` to insert the widget into.
+     */
+    container: string | HTMLElement;
+    /**
+     * Templates to customize the widget.
+     */
+    templates?: RelatedProductsTemplates;
+    /**
+     * CSS classes to add to the widget elements.
+     */
+    cssClasses?: RelatedProductsCSSClasses;
+};
+
 declare const relevantSort: RelevantSortWidget;
 
 declare type RelevantSortConnector = Connector<RelevantSortWidgetDescription, RelevantSortConnectorParams>;
@@ -4488,7 +4780,7 @@ declare function renderTemplate({ templates, templateKey, compileOptions, helper
     data?: Record<string, any>;
     bindEvent?: BindEventForHits;
     sendEvent?: SendEventForHits;
-}): string | VNode<    {}> | VNode<    {}>[];
+}): string | VNode<    {}> | VNode<    {}>[] | null;
 
 declare type RequiredKeys<TObject, TKeys extends keyof TObject> = Expand<Required<Pick<TObject, TKeys>> & Omit<TObject, TKeys>>;
 
@@ -4538,7 +4830,7 @@ declare type RequiredUiStateLifeCycle<TWidgetDescription extends WidgetDescripti
     getWidgetSearchParameters: (state: SearchParameters, widgetSearchParametersOptions: {
         uiState: Expand<Partial<TWidgetDescription['indexUiState'] & IndexUiState>>;
     }) => SearchParameters;
-} & (SearchWidgetLifeCycle<TWidgetDescription> | RecommendWidgetLifeCycle<TWidgetDescription>);
+};
 
 declare type RequiredWidgetLifeCycle<TWidgetDescription extends WidgetDescription> = {
     /**
@@ -4561,7 +4853,7 @@ declare type RequiredWidgetLifeCycle<TWidgetDescription extends WidgetDescriptio
      * Called when this widget is unmounted. Used to remove refinements set by
      * during this widget's initialization and life time.
      */
-    dispose?: (options: DisposeOptions) => SearchParameters | void;
+    dispose?: (options: DisposeOptions) => SearchParameters | RecommendParameters | void;
 };
 
 declare type RequiredWidgetType<TWidgetDescription extends WidgetDescription> = {
@@ -4868,7 +5160,7 @@ declare type SearchBoxWidgetParams = {
     queryHook?: (query: string, hook: (value: string) => void) => void;
 };
 
-declare type SearchWidgetLifeCycle<TWidgetDescription extends WidgetDescription> = {
+declare type SearchWidget<TWidgetDescription extends WidgetDescription> = {
     dependsOn?: 'search';
     getWidgetParameters?: (state: SearchParameters, widgetParametersOptions: {
         uiState: Expand<Partial<TWidgetDescription['indexUiState'] & IndexUiState>>;
@@ -5227,7 +5519,7 @@ declare type StatsWidgetParams = {
 
 declare type Status = 'initial' | 'askingPermission' | 'waiting' | 'recognizing' | 'finished' | 'error';
 
-declare type Template<TTemplateData = void> = string | ((data: TTemplateData, params: TemplateParams) => VNode | VNode[] | string);
+declare type Template<TTemplateData = void> = string | ((data: TTemplateData, params: TemplateParams) => VNode | VNode[] | string | null);
 
 declare type TemplateParams = {
     html: typeof html;
@@ -5423,6 +5715,103 @@ declare type TransformItemsMetadata = {
 
 declare type TransformSearchParameters = (searchParameters: SearchParameters) => PlainSearchParameters;
 
+declare const trendingItems: TrendingItemsWidget;
+
+declare type TrendingItemsConnector<THit extends BaseHit = BaseHit> = Connector<TrendingItemsWidgetDescription<THit>, TrendingItemsConnectorParams<THit>>;
+
+declare type TrendingItemsConnectorParams<THit extends BaseHit = BaseHit> = ({
+    /**
+     * The facet attribute to get recommendations for.
+     */
+    facetName: string;
+    /**
+     * The facet value to get recommendations for.
+     */
+    facetValue: string;
+} | {
+    facetName?: never;
+    facetValue?: never;
+}) & {
+    /**
+     * The number of recommendations to retrieve.
+     */
+    limit?: number;
+    /**
+     * The threshold for the recommendations confidence score (between 0 and 100).
+     */
+    threshold?: number;
+    /**
+     * List of search parameters to send.
+     */
+    fallbackParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * List of search parameters to send.
+     */
+    queryParameters?: Omit<PlainSearchParameters, 'page' | 'hitsPerPage' | 'offset' | 'length'>;
+    /**
+     * Whether to escape HTML tags from items string values.
+     *
+     * @default true
+     */
+    escapeHTML?: boolean;
+    /**
+     * Function to transform the items passed to the templates.
+     */
+    transformItems?: TransformItems<Hit<THit>, {
+        results: RecommendResultItem;
+    }>;
+};
+
+declare type TrendingItemsCSSClasses = Partial<RecommendClassNames>;
+
+declare type TrendingItemsRenderState<THit extends BaseHit = BaseHit> = {
+    /**
+     * The matched recommendations from the Algolia API.
+     */
+    items: Array<Hit<THit>>;
+};
+
+declare type TrendingItemsTemplates = Partial<{
+    /**
+     * Template to use when there are no results.
+     */
+    empty: Template<RecommendResultItem>;
+    /**
+     * Template to use for the header of the widget.
+     */
+    header: Template<Pick<Parameters<NonNullable<TrendingItemsProps<Hit>['headerComponent']>>[0], 'items'> & {
+        cssClasses: RecommendClassNames;
+    }>;
+    /**
+     * Template to use for each result. This template will receive an object containing a single record.
+     */
+    item: Template<Hit>;
+}>;
+
+declare type TrendingItemsWidget = WidgetFactory<TrendingItemsWidgetDescription & {
+    $$widgetType: 'ais.trendingItems';
+}, TrendingItemsConnectorParams, TrendingItemsWidgetParams>;
+
+declare type TrendingItemsWidgetDescription<THit extends BaseHit = BaseHit> = {
+    $$type: 'ais.trendingItems';
+    renderState: TrendingItemsRenderState<THit>;
+};
+
+declare type TrendingItemsWidgetParams = {
+    /**
+     * CSS selector or `HTMLElement` to insert the widget into.
+     */
+    container: string | HTMLElement;
+    /**
+     * Templates to customize the widget.
+     */
+    templates?: TrendingItemsTemplates;
+    /**
+     * CSS classes to add to the widget elements.
+     */
+    cssClasses?: TrendingItemsCSSClasses;
+};
+
 declare type UiState = {
     [indexId: string]: IndexUiState;
 };
@@ -5528,7 +5917,7 @@ declare type VoiceSearchWidgetParams = {
 
 declare type Widget<TWidgetDescription extends WidgetDescription & WidgetParams = {
     $$type: string;
-}> = Expand<RequiredWidgetLifeCycle<TWidgetDescription> & WidgetType<TWidgetDescription> & UiStateLifeCycle<TWidgetDescription> & RenderStateLifeCycle<TWidgetDescription>>;
+}> = Expand<RequiredWidgetLifeCycle<TWidgetDescription> & WidgetType<TWidgetDescription> & UiStateLifeCycle<TWidgetDescription> & RenderStateLifeCycle<TWidgetDescription>> & (SearchWidget<TWidgetDescription> | RecommendWidget<TWidgetDescription>);
 
 declare type WidgetDescription = {
     $$type: string;
@@ -5585,6 +5974,7 @@ declare namespace widgets {
         poweredBy,
         queryRuleContext,
         queryRuleCustomData,
+        relatedProducts,
         rangeInput,
         rangeSlider,
         ratingMenu,
@@ -5594,7 +5984,10 @@ declare namespace widgets {
         sortBy,
         stats,
         toggleRefinement,
-        voiceSearch
+        trendingItems,
+        voiceSearch,
+        frequentlyBoughtTogether,
+        lookingSimilar
     }
 }