instantsearch.js 4.44.1 → 4.46.0

package/dist/instantsearch.production.d.ts

@@ -3,6 +3,11 @@
 import type { AlgoliaSearchHelper } from 'algoliasearch-helper';
 import EventEmitter from '@algolia/events';
 import { FindAnswersOptions } from 'algoliasearch-helper/types/algoliasearch.js';
+import { h } from 'preact';
+import type { HighlightClassNames as HighlightClassNames_2 } from '@algolia/ui-components-highlight-vdom';
+import type { HighlightProps as HighlightProps_3 } from '@algolia/ui-components-highlight-vdom';
+import type { HoganOptions } from 'hogan.js';
+import type { html } from 'htm/preact';
 import type { InsightsClient as InsightsClient_2 } from 'search-insights';
 import type { InsightsMethodMap } from 'search-insights';
 import type * as Places from 'places.js';
@@ -11,6 +16,7 @@ import { default as qs_2 } from 'qs';
 import { SearchClient } from 'algoliasearch-helper/types/algoliasearch.js';
 import type { SearchParameters } from 'algoliasearch-helper';
 import type { SearchResults } from 'algoliasearch-helper';
+import { VNode } from 'preact';
 
 declare type AlgoliaHit<THit extends BaseHit = Record<string, any>> = {
     objectID: string;
@@ -173,7 +179,7 @@ declare type AnswersRenderState = {
     /**
      * The matched hits from Algolia API.
      */
-    hits: Hits;
+    hits: Hit[];
     /**
      * Whether it's still loading the results from the Answers API.
      */
@@ -264,7 +270,7 @@ declare type AutocompleteRenderState = {
         /**
          * The resolved hits from the index matching the query.
          */
-        hits: Hits;
+        hits: Hit[];
         /**
          * The full results object from the Algolia API.
          */
@@ -518,11 +524,11 @@ declare type BrowserHistoryArgs<TRouteState> = {
     getLocation(): Location;
 };
 
-declare type BuiltInBindEventForHits = (eventType: string, hits: Hit | Hits, eventName?: string) => string;
+declare type BuiltInBindEventForHits = (eventType: string, hits: Hit | Hit[], eventName?: string) => string;
 
 declare type BuiltInSendEventForFacet = (eventType: string, facetValue: string, eventName?: string) => void;
 
-declare type BuiltInSendEventForHits = (eventType: string, hits: Hit | Hits, eventName?: string) => void;
+declare type BuiltInSendEventForHits = (eventType: string, hits: Hit | Hit[], eventName?: string) => void;
 
 declare type BuiltInSendEventForToggle = (eventType: string, isRefined: boolean, eventName?: string) => void;
 
@@ -584,7 +590,9 @@ declare type ClearRefinementsTemplates = Partial<{
     /**
      * Template for the content of the button
      */
-    resetLabel: Template;
+    resetLabel: Template<{
+        hasRefinements: boolean;
+    }>;
 }>;
 
 declare type ClearRefinementsWidget = WidgetFactory<ClearRefinementsWidgetDescription & {
@@ -1588,6 +1596,8 @@ declare type HierarchicalMenuTemplates = Partial<{
         count: number;
         isRefined: boolean;
         url: string;
+        label: string;
+        cssClasses: HierarchicalMenuCSSClasses;
     }>;
     /**
      * Template used for the show more text, provided with `isShowingMore` data property.
@@ -1738,8 +1748,12 @@ declare type HierarchicalMenuWidgetParams = {
     cssClasses?: HierarchicalMenuCSSClasses;
 };
 
+declare function Highlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: HighlightProps<THit>): h.JSX.Element;
+
 declare function highlight({ attribute, highlightedTagName, hit, cssClasses, }: HighlightOptions): string;
 
+declare type HighlightClassNames = HighlightClassNames_2;
+
 declare type HighlightOptions = {
     attribute: string | string[];
     highlightedTagName?: string;
@@ -1749,6 +1763,16 @@ declare type HighlightOptions = {
     }>;
 };
 
+declare type HighlightProps<THit extends Hit<BaseHit>> = {
+    hit: THit;
+    attribute: keyof THit | string[];
+    cssClasses?: HighlightProps_2['classNames'];
+} & PartialKeys<Omit<HighlightProps_2, 'parts' | 'classNames'>, 'highlightedTagName' | 'nonHighlightedTagName' | 'separator'>;
+
+declare type HighlightProps_2 = Omit<HighlightProps_3, 'classNames'> & {
+    classNames?: Partial<HighlightClassNames>;
+};
+
 declare function historyRouter<TRouteState = UiState>({ createURL, parseURL, writeDelay, windowTitle, getLocation, }?: Partial<BrowserHistoryArgs<TRouteState>>): BrowserHistory<TRouteState>;
 
 declare type Hit<THit extends BaseHit = Record<string, any>> = {
@@ -1769,11 +1793,6 @@ declare type HitHighlightResult = {
     [attribute: string]: HitAttributeHighlightResult | HitAttributeHighlightResult[] | HitHighlightResult[] | HitHighlightResult;
 };
 
-/**
- * @deprecated use Hit[] directly instead
- */
-declare type Hits = Hit[];
-
 declare const hits: HitsWidget;
 
 declare type HitsConnector<THit extends BaseHit = BaseHit> = Connector<HitsWidgetDescription<THit>, HitsConnectorParams<THit>>;
@@ -1872,8 +1891,13 @@ declare type HitsPerPageRenderState = {
     refine: (value: number) => void;
     /**
      * Indicates whether or not the search has results.
+     * @deprecated Use `canRefine` instead.
      */
     hasNoResults: boolean;
+    /**
+     * Indicates if search state can be refined.
+     */
+    canRefine: boolean;
 };
 
 declare type HitsPerPageRenderStateItem = {
@@ -1942,7 +1966,7 @@ declare type HitsTemplates = Partial<{
      *
      * @default 'No Results'
      */
-    empty: Template;
+    empty: Template<SearchResults>;
     /**
      * Template to use for each result. This template will receive an object containing a single record.
      *
@@ -1980,11 +2004,13 @@ declare type HitsWidgetParams = {
     cssClasses?: HitsCSSClasses;
 };
 
+declare type HoganHelpers<TKeys extends string = string> = Record<TKeys, (text: string, render: (value: string) => string) => string>;
+
 declare type HTMLMarkerArguments = {
     __id: string;
     position: google.maps.LatLngLiteral;
     map: google.maps.Map;
-    template: string;
+    template: ReturnType<typeof renderTemplate>;
     title?: string;
     className: string;
     anchor?: {
@@ -2163,9 +2189,7 @@ declare type InfiniteHitsTemplates = Partial<{
     /**
      * The template to use when there are no results.
      */
-    empty: Template<{
-        results: SearchResults;
-    }>;
+    empty: Template<SearchResults>;
     /**
      * The template to use for the “Show previous” label.
      */
@@ -2401,6 +2425,10 @@ declare type InstantSearchModule = {
     reverseHighlight: typeof helpers.reverseHighlight;
     snippet: typeof helpers.snippet;
     reverseSnippet: typeof helpers.reverseSnippet;
+    /**
+     * @deprecated use createInsightsMiddleware
+     * @link https://www.algolia.com/doc/api-reference/widgets/insights/js/
+     */
     insights: typeof helpers.insights;
 };
 
@@ -2855,8 +2883,16 @@ declare type NumericMenuRenderState = {
     createURL: CreateURL<NumericMenuRenderStateItem['value']>;
     /**
      * `true` if the last search contains no result
+     * @deprecated Use `canRefine` instead.
      */
     hasNoResults: boolean;
+    /**
+     * Indicates if search state can be refined.
+     *
+     * This is `true` if the last search contains no result and
+     * "All" range is selected
+     */
+    canRefine: boolean;
     /**
      * Sets the selected value and trigger a new search
      */
@@ -3223,6 +3259,11 @@ declare type ParseURL<TRouteState> = (args: {
     location: Location;
 }) => TRouteState;
 
+/**
+ * Make certain keys of an object optional.
+ */
+declare type PartialKeys<TObj, TKeys extends keyof TObj> = Omit<TObj, TKeys> & Partial<Pick<TObj, TKeys>>;
+
 declare type PlacesInstance = Places.PlacesInstance;
 
 declare type PlacesWidget = WidgetFactory<PlacesWidgetDescription, PlacesWidgetParams, PlacesWidgetParams>;
@@ -3721,6 +3762,8 @@ declare type RatingMenuRenderState = {
     refine: (value: string) => void;
     /**
      * `true` if the last search contains no result.
+     *
+     * @deprecated Use `canRefine` instead.
      */
     hasNoResults: boolean;
     /**
@@ -3735,9 +3778,15 @@ declare type RatingMenuTemplates = Partial<{
      */
     item: Template<{
         name: string;
+        label: string;
+        value: string;
         count: number;
         isRefined: boolean;
         url: string;
+        stars: [boolean, boolean, boolean, boolean, boolean];
+        cssClasses: RatingMenuCSSClasses;
+        attribute?: string;
+        isFromSearch?: boolean;
     }>;
 }>;
 
@@ -3940,6 +3989,10 @@ declare type RefinementListItemData = {
      * Object containing all the classes computed for the item.
      */
     cssClasses: RefinementListCSSClasses;
+    /**
+     * Whether the `items` prop contains facet values from the global search or from the search inside the items.
+     */
+    isFromSearch: boolean;
 };
 
 declare type RefinementListOwnCSSClasses = Partial<{
@@ -4005,7 +4058,9 @@ declare type RefinementListOwnTemplates = Partial<{
     /**
      * Template used for the show more text, provided with `isShowingMore` data property.
      */
-    showMoreText: Template;
+    showMoreText: Template<{
+        isShowingMore: boolean;
+    }>;
     /**
      * Templates to use for search for facet values when there are no results.
      */
@@ -4240,7 +4295,7 @@ declare type RendererOptions<TWidgetParams> = {
      * The mutable list of hits. The may change depending
      * of the given transform items function.
      */
-    hits?: Hits;
+    hits?: Hit[];
     /**
      * The current insights client, if any.
      */
@@ -4257,6 +4312,16 @@ declare type RenderState = {
 
 declare type RenderStateLifeCycle<TWidgetDescription extends WidgetDescription & WidgetParams> = TWidgetDescription extends RequiredKeys<WidgetDescription, 'renderState' | 'indexRenderState'> & WidgetParams ? RequiredRenderStateLifeCycle<TWidgetDescription> : Partial<RequiredRenderStateLifeCycle<TWidgetDescription>>;
 
+declare function renderTemplate({ templates, templateKey, compileOptions, helpers, data, bindEvent, sendEvent, }: {
+    templates: Templates;
+    templateKey: string;
+    compileOptions?: HoganOptions;
+    helpers?: HoganHelpers;
+    data?: Record<string, any>;
+    bindEvent?: BindEventForHits;
+    sendEvent?: SendEventForHits;
+}): string | VNode<    {}> | VNode<    {}>[];
+
 declare type RequiredKeys<TObject, TKeys extends keyof TObject> = Expand<Required<Pick<TObject, TKeys>> & Omit<TObject, TKeys>>;
 
 declare type RequiredRenderStateLifeCycle<TWidgetDescription extends WidgetDescription & WidgetParams> = {
@@ -4334,8 +4399,12 @@ declare type RequiredWidgetType<TWidgetDescription extends WidgetDescription> =
     $$widgetType: TWidgetDescription['$$widgetType'];
 };
 
+declare function ReverseHighlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseHighlightProps<THit>): h.JSX.Element;
+
 declare function reverseHighlight({ attribute, highlightedTagName, hit, cssClasses, }: ReverseHighlightOptions): string;
 
+declare type ReverseHighlightClassNames = HighlightClassNames_2;
+
 declare type ReverseHighlightOptions = {
     attribute: string | string[];
     highlightedTagName?: string;
@@ -4345,8 +4414,22 @@ declare type ReverseHighlightOptions = {
     }>;
 };
 
+declare type ReverseHighlightProps<THit extends Hit<BaseHit>> = {
+    hit: THit;
+    attribute: keyof THit | string[];
+    cssClasses?: ReverseHighlightProps_2['classNames'];
+} & PartialKeys<Omit<ReverseHighlightProps_2, 'parts' | 'classNames'>, 'highlightedTagName' | 'nonHighlightedTagName' | 'separator'>;
+
+declare type ReverseHighlightProps_2 = Omit<HighlightProps_3, 'classNames'> & {
+    classNames?: Partial<ReverseHighlightClassNames>;
+};
+
+declare function ReverseSnippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseSnippetProps<THit>): h.JSX.Element;
+
 declare function reverseSnippet({ attribute, highlightedTagName, hit, cssClasses, }: ReverseSnippetOptions): string;
 
+declare type ReverseSnippetClassNames = HighlightClassNames_2;
+
 declare type ReverseSnippetOptions = {
     attribute: string | string[];
     highlightedTagName?: string;
@@ -4356,6 +4439,16 @@ declare type ReverseSnippetOptions = {
     }>;
 };
 
+declare type ReverseSnippetProps<THit extends Hit<BaseHit>> = {
+    hit: THit;
+    attribute: keyof THit | string[];
+    cssClasses?: ReverseSnippetProps_2['classNames'];
+} & PartialKeys<Omit<ReverseSnippetProps_2, 'parts' | 'classNames'>, 'highlightedTagName' | 'nonHighlightedTagName' | 'separator'>;
+
+declare type ReverseSnippetProps_2 = Omit<HighlightProps_3, 'classNames'> & {
+    classNames?: Partial<ReverseSnippetClassNames>;
+};
+
 /**
  * The router is the part that saves and reads the object from the storage.
  * Usually this is the URL.
@@ -4408,6 +4501,8 @@ declare type ScopedResult = {
 
 declare const searchBox: SearchBoxWidget;
 
+declare type SearchBoxComponentCSSClasses = ComponentCSSClasses<SearchBoxCSSClasses>;
+
 declare type SearchBoxConnector = Connector<SearchBoxWidgetDescription, SearchBoxConnectorParams>;
 
 declare type SearchBoxConnectorParams = {
@@ -4493,15 +4588,21 @@ declare type SearchBoxTemplates = Partial<{
     /**
      * Template used for displaying the submit button. Can accept a function or a Hogan string.
      */
-    submit: Template;
+    submit: Template<{
+        cssClasses: SearchBoxComponentCSSClasses;
+    }>;
     /**
      * Template used for displaying the reset button. Can accept a function or a Hogan string.
      */
-    reset: Template;
+    reset: Template<{
+        cssClasses: SearchBoxComponentCSSClasses;
+    }>;
     /**
      * Template used for displaying the loading indicator. Can accept a function or a Hogan string.
      */
-    loadingIndicator: Template;
+    loadingIndicator: Template<{
+        cssClasses: SearchBoxComponentCSSClasses;
+    }>;
 }>;
 
 /**
@@ -4600,8 +4701,12 @@ declare function simpleStateMapping<TUiState extends UiState = UiState>(): State
 
 declare function singleIndexStateMapping<TUiState extends UiState = UiState>(indexName: keyof TUiState): StateMapping<TUiState, TUiState[typeof indexName]>;
 
+declare function Snippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: SnippetProps<THit>): h.JSX.Element;
+
 declare function snippet({ attribute, highlightedTagName, hit, cssClasses, }: SnippetOptions): string;
 
+declare type SnippetClassNames = HighlightClassNames_2;
+
 declare type SnippetOptions = {
     attribute: string | string[];
     highlightedTagName?: string;
@@ -4611,6 +4716,16 @@ declare type SnippetOptions = {
     };
 };
 
+declare type SnippetProps<THit extends Hit<BaseHit>> = {
+    hit: THit;
+    attribute: keyof THit | string[];
+    cssClasses?: SnippetProps_2['classNames'];
+} & PartialKeys<Omit<SnippetProps_2, 'parts' | 'classNames'>, 'highlightedTagName' | 'nonHighlightedTagName' | 'separator'>;
+
+declare type SnippetProps_2 = Omit<HighlightProps_3, 'classNames'> & {
+    classNames?: Partial<SnippetClassNames>;
+};
+
 /**
  * Transforms the given items.
  */
@@ -4683,8 +4798,13 @@ declare type SortByRenderState = {
     refine: (value: string) => void;
     /**
      * `true` if the last search contains no result.
+     * @deprecated Use `canRefine` instead.
      */
     hasNoResults: boolean;
+    /**
+     * `true` if we can refine.
+     */
+    canRefine: boolean;
 };
 
 declare type SortByWidget = WidgetFactory<SortByWidgetDescription & {
@@ -4858,13 +4978,9 @@ declare type StatsRenderState = {
 
 declare type StatsTemplates = Partial<{
     /**
-     * Text template, provided with `hasManyResults`, `hasNoResults`, `hasOneResult`, `hitsPerPage`, `nbHits`, `nbSortedHits`, `nbPages`, `areHitsSorted`, `page`, `processingTimeMS`, `query`.
+     * Text template, provided with `hasManyResults`, `hasNoResults`, `hasOneResult`, `hasNoSortedResults`, `hasOneSortedResults`, `hasManySortedResults`, `hitsPerPage`, `nbHits`, `nbSortedHits`, `nbPages`, `areHitsSorted`, `page`, `processingTimeMS`, `query`.
      */
-    text: Template<{
-        hasManyResults: boolean;
-        hasNoResults: boolean;
-        hasOneResult: boolean;
-    } & StatsRenderState>;
+    text: Template<TextTemplateProps & StatsRenderState>;
 }>;
 
 declare type StatsWidget = WidgetFactory<StatsWidgetDescription & {
@@ -4896,9 +5012,33 @@ declare type StatsWidgetParams = {
 
 declare type Status = 'initial' | 'askingPermission' | 'waiting' | 'recognizing' | 'finished' | 'error';
 
-declare type Template<TTemplateData = void> = string | ((data: TTemplateData) => string);
+declare type Template<TTemplateData = void> = string | ((data: TTemplateData, params: TemplateParams) => VNode | VNode[] | string);
+
+declare type TemplateParams = BindEventForHits & {
+    html: typeof html;
+    components: {
+        Highlight: typeof Highlight;
+        ReverseHighlight: typeof ReverseHighlight;
+        Snippet: typeof Snippet;
+        ReverseSnippet: typeof ReverseSnippet;
+    };
+    sendEvent?: SendEventForHits;
+};
 
-declare type TemplateWithBindEvent<TTemplateData = void> = string | ((data: TTemplateData, bindEvent: BindEventForHits) => string);
+declare type Templates = {
+    [key: string]: Template<any> | TemplateWithBindEvent<any> | undefined;
+};
+
+declare type TemplateWithBindEvent<TTemplateData = void> = string | ((data: TTemplateData, params: TemplateParams) => VNode | VNode[] | string);
+
+declare type TextTemplateProps = {
+    hasManyResults: boolean;
+    hasNoResults: boolean;
+    hasOneResult: boolean;
+    hasNoSortedResults: boolean;
+    hasOneSortedResults: boolean;
+    hasManySortedResults: boolean;
+};
 
 /**
  * The toggleRefinement widget lets the user either:
@@ -4999,7 +5139,9 @@ declare type ToggleRefinementTemplates = Partial<{
     /**
      * the text that describes the toggle action
      */
-    labelText: Template<ToggleRefinementValue>;
+    labelText: Template<ToggleRefinementValue & {
+        name: string;
+    }>;
 }>;
 
 declare type ToggleRefinementValue = {