instantsearch.js 4.54.1 → 4.56.0

package/dist/instantsearch.development.d.ts

@@ -10,7 +10,7 @@ import type { HighlightProps as HighlightProps_3 } from '@algolia/ui-components-
 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 { InsightsMethodMap as InsightsMethodMap_2 } from 'search-insights';
 import type * as Places from 'places.js';
 import type { PlainSearchParameters } from 'algoliasearch-helper';
 import { default as qs_2 } from 'qs';
@@ -438,6 +438,7 @@ declare type BreadcrumbWidgetParams = {
 };
 
 declare class BrowserHistory<TRouteState> implements Router<TRouteState> {
+    $$type: string;
     /**
      * Transforms a UI state into a title for the page.
      */
@@ -466,7 +467,7 @@ declare class BrowserHistory<TRouteState> implements Router<TRouteState> {
      */
     private readonly getLocation;
     private writeTimer?;
-    private _onPopState;
+    private _onPopState?;
     /**
      * Indicates if last action was back/forward in the browser.
      */
@@ -524,7 +525,7 @@ declare type BrowserHistoryArgs<TRouteState> = {
     writeDelay: number;
     createURL: CreateURL_2<TRouteState>;
     parseURL: ParseURL<TRouteState>;
-    getLocation(): Location;
+    getLocation: () => Location;
     start?: (onUpdate: () => void) => void;
     dispose?: () => void;
     push?: (url: string) => void;
@@ -901,7 +902,7 @@ declare function createInfiniteHitsSessionStorageCache(): InfiniteHitsCache;
 
 declare type CreateInsightsMiddleware = typeof createInsightsMiddleware;
 
-declare function createInsightsMiddleware<TInsightsClient extends null | InsightsClient>(props: InsightsProps<TInsightsClient>): InternalMiddleware;
+declare function createInsightsMiddleware<TInsightsClient extends ProvidedInsightsClient>(props?: InsightsProps<TInsightsClient>): InternalMiddleware;
 
 /**
  * Exposes the metadata of mounted widgets in a custom
@@ -910,7 +911,9 @@ declare function createInsightsMiddleware<TInsightsClient extends null | Insight
  * - widget name
  * - connector name
  */
-declare function createMetadataMiddleware(): InternalMiddleware;
+declare function createMetadataMiddleware({ $$internal, }?: {
+    $$internal?: boolean;
+}): InternalMiddleware;
 
 declare const createRouterMiddleware: <TUiState extends UiState = UiState, TRouteState = TUiState>(props?: RouterProps<TUiState, TRouteState>) => InternalMiddleware<TUiState>;
 
@@ -976,7 +979,7 @@ declare type CurrentRefinementsConnectorParamsItem = {
     /**
      * Removes the given refinement and triggers a new search.
      */
-    refine(refinement: CurrentRefinementsConnectorParamsRefinement): void;
+    refine: (refinement: CurrentRefinementsConnectorParamsRefinement) => void;
 };
 
 declare type CurrentRefinementsConnectorParamsRefinement = {
@@ -1057,7 +1060,7 @@ declare type CurrentRefinementsRenderState = {
     /**
      * Removes the given refinement and triggers a new search.
      */
-    refine(refinement: CurrentRefinementsConnectorParamsRefinement): void;
+    refine: (refinement: CurrentRefinementsConnectorParamsRefinement) => void;
     /**
      * Generates a URL for the next state.
      */
@@ -1114,10 +1117,10 @@ declare type DynamicWidgetsConnectorParams = {
      * Function to return a fallback widget when an attribute isn't found in
      * `widgets`.
      */
-    fallbackWidget?(args: {
+    fallbackWidget?: (args: {
         /** The attribute name to create a widget for. */
         attribute: string;
-    }): Widget;
+    }) => Widget;
     /**
      * Function to transform the items to render.
      * The function also exposes the full search response.
@@ -1171,12 +1174,12 @@ declare type DynamicWidgetsWidgetParams = {
      * Function to return a fallback widget when an attribute isn't found in
      * `widgets`.
      */
-    fallbackWidget?(args: {
+    fallbackWidget?: (args: {
         /** The attribute name to create a widget for. */
         attribute: string;
         /** CSS Selector or HTMLElement to insert the widget */
         container: HTMLElement;
-    }): Widget;
+    }) => Widget;
 };
 
 declare type Expand<T> = T extends infer O ? {
@@ -1261,7 +1264,7 @@ declare type GeoSearchMarker<TOptions> = {
      * See the documentation for more information:
      * https://developers.google.com/maps/documentation/javascript/reference/3/#MarkerOptions
      */
-    createOptions?(item: GeoHit): TOptions;
+    createOptions?: (item: GeoHit) => TOptions;
     /**
      * Object that takes an event type (ex: `click`, `mouseover`) as key and a
      * listener as value. The listener is provided with an object that contains:
@@ -1281,7 +1284,7 @@ declare type GeoSearchRenderState<THit extends BaseHit = Record<string, any>> =
     /**
      * Reset the current bounding box refinement.
      */
-    clearMapRefinement(): void;
+    clearMapRefinement: () => void;
     /**
      * The current bounding box of the search.
      */
@@ -1289,15 +1292,15 @@ declare type GeoSearchRenderState<THit extends BaseHit = Record<string, any>> =
     /**
      * Return true if the map has move since the last refinement.
      */
-    hasMapMoveSinceLastRefine(): boolean;
+    hasMapMoveSinceLastRefine: () => boolean;
     /**
      * Return true if the current refinement is set with the map bounds.
      */
-    isRefinedWithMap(): boolean;
+    isRefinedWithMap: () => boolean;
     /**
      * Return true if the user is able to refine on map move.
      */
-    isRefineOnMapMove(): boolean;
+    isRefineOnMapMove: () => boolean;
     /**
      * The matched hits from Algolia API.
      */
@@ -1309,7 +1312,7 @@ declare type GeoSearchRenderState<THit extends BaseHit = Record<string, any>> =
     /**
      * Sets a bounding box to filter the results from the given map bounds.
      */
-    refine(bounds: Bounds): void;
+    refine: (bounds: Bounds) => void;
     /**
      * Send event to insights middleware
      */
@@ -1319,11 +1322,11 @@ declare type GeoSearchRenderState<THit extends BaseHit = Record<string, any>> =
      * called on each map move. The call to the function triggers a new rendering
      * only when the value change.
      */
-    setMapMoveSinceLastRefine(): void;
+    setMapMoveSinceLastRefine: () => void;
     /**
      * Toggle the fact that the user is able to refine on map move.
      */
-    toggleRefineOnMapMove(): void;
+    toggleRefineOnMapMove: () => void;
 };
 
 declare type GeoSearchTemplates = Partial<{
@@ -2066,39 +2069,39 @@ declare type IndexUiState = Partial<ConnectorUiStates & WidgetUiStates>;
 declare type IndexWidget<TUiState extends UiState = UiState> = Omit<Widget<IndexWidgetDescription & {
     widgetParams: IndexWidgetParams;
 }>, 'getWidgetUiState' | 'getWidgetState'> & {
-    getIndexName(): string;
-    getIndexId(): string;
-    getHelper(): AlgoliaSearchHelper | null;
-    getResults(): SearchResults | null;
-    getPreviousState(): SearchParameters | null;
-    getScopedResults(): ScopedResult[];
-    getParent(): IndexWidget | null;
-    getWidgets(): Array<Widget | IndexWidget>;
-    createURL(state: SearchParameters): string;
-    addWidgets(widgets: Array<Widget | IndexWidget>): IndexWidget;
-    removeWidgets(widgets: Array<Widget | IndexWidget>): IndexWidget;
-    init(options: IndexInitOptions): void;
-    render(options: IndexRenderOptions): void;
-    dispose(): void;
+    getIndexName: () => string;
+    getIndexId: () => string;
+    getHelper: () => AlgoliaSearchHelper | null;
+    getResults: () => SearchResults | null;
+    getPreviousState: () => SearchParameters | null;
+    getScopedResults: () => ScopedResult[];
+    getParent: () => IndexWidget | null;
+    getWidgets: () => Array<Widget | IndexWidget>;
+    createURL: (state: SearchParameters) => string;
+    addWidgets: (widgets: Array<Widget | IndexWidget>) => IndexWidget;
+    removeWidgets: (widgets: Array<Widget | IndexWidget>) => IndexWidget;
+    init: (options: IndexInitOptions) => void;
+    render: (options: IndexRenderOptions) => void;
+    dispose: () => void;
     /**
      * @deprecated
      */
-    getWidgetState(uiState: UiState): UiState;
-    getWidgetUiState<TSpecificUiState extends UiState = TUiState>(uiState: TSpecificUiState): TSpecificUiState;
-    getWidgetSearchParameters(searchParameters: SearchParameters, searchParametersOptions: {
+    getWidgetState: (uiState: UiState) => UiState;
+    getWidgetUiState: <TSpecificUiState extends UiState = TUiState>(uiState: TSpecificUiState) => TSpecificUiState;
+    getWidgetSearchParameters: (searchParameters: SearchParameters, searchParametersOptions: {
         uiState: IndexUiState;
-    }): SearchParameters;
+    }) => SearchParameters;
     /**
      * Set this index' UI state back to the state defined by the widgets.
      * Can only be called after `init`.
      */
-    refreshUiState(): void;
+    refreshUiState: () => void;
     /**
      * Set this index' UI state and search. This is the equivalent of calling
      * a spread `setUiState` on the InstantSearch instance.
      * Can only be called after `init`.
      */
-    setIndexUiState(indexUiState: TUiState[string] | ((previousIndexUiState: TUiState[string]) => TUiState[string])): void;
+    setIndexUiState: (indexUiState: TUiState[string] | ((previousIndexUiState: TUiState[string]) => TUiState[string])) => void;
 };
 
 declare type IndexWidgetDescription = {
@@ -2313,20 +2316,39 @@ declare type InsightsClientPayload = {
     positions?: number[];
 };
 
-declare type InsightsEvent = {
-    insightsMethod?: InsightsClientMethod;
-    payload: any;
+declare type InsightsClientWithGlobals = InsightsClient & {
+    shouldAddScript?: boolean;
+    version?: string;
+};
+
+declare type InsightsEvent<TMethod extends InsightsMethod = InsightsMethod> = InsightsEvent_2<TMethod>;
+
+/**
+ * The event sent to the insights middleware.
+ */
+declare type InsightsEvent_2<TMethod extends InsightsMethod = InsightsMethod> = {
+    insightsMethod?: TMethod;
+    payload: InsightsMethodMap[TMethod][0];
     widgetType: string;
     eventType: string;
+    eventModifier?: string;
     hits?: Hit[];
     attribute?: string;
 };
 
-declare type InsightsProps<TInsightsClient extends null | InsightsClient = InsightsClient | null> = {
-    insightsClient: TInsightsClient;
+/**
+ * Method allowed by the insights middleware.
+ */
+declare type InsightsMethod = 'clickedObjectIDsAfterSearch' | 'clickedObjectIDs' | 'clickedFilters' | 'convertedObjectIDsAfterSearch' | 'convertedObjectIDs' | 'convertedFilters' | 'viewedObjectIDs' | 'viewedFilters';
+
+declare type InsightsMethodMap = InsightsMethodMap_2;
+
+declare type InsightsProps<TInsightsClient extends ProvidedInsightsClient = ProvidedInsightsClient> = {
+    insightsClient?: TInsightsClient;
     insightsInitParams?: {
         userHasOptedOut?: boolean;
         useCookie?: boolean;
+        anonymousUserToken?: boolean;
         cookieDuration?: number;
         region?: 'de' | 'us';
     };
@@ -2357,8 +2379,8 @@ declare class InstantSearch<TUiState extends UiState = UiState, TRouteState = TU
     _searchFunction?: InstantSearchOptions['searchFunction'];
     _mainHelperSearch?: AlgoliaSearchHelper['search'];
     middleware: Array<{
-        creator: Middleware;
-        instance: MiddlewareDefinition;
+        creator: Middleware<TUiState>;
+        instance: MiddlewareDefinition<TUiState>;
     }>;
     sendEventToInsights: (event: InsightsEvent) => void;
     /**
@@ -2378,11 +2400,11 @@ declare class InstantSearch<TUiState extends UiState = UiState, TRouteState = TU
     /**
      * Hooks a middleware into the InstantSearch lifecycle.
      */
-    use(...middleware: Middleware[]): this;
+    use(...middleware: Array<Middleware<TUiState>>): this;
     /**
      * Removes a middleware from the InstantSearch lifecycle.
      */
-    unuse(...middlewareToUnuse: Middleware[]): this;
+    unuse(...middlewareToUnuse: Array<Middleware<TUiState>>): this;
     EXPERIMENTAL_use(...middleware: Middleware[]): this;
     /**
      * Adds a widget to the search instance.
@@ -2428,12 +2450,12 @@ declare class InstantSearch<TUiState extends UiState = UiState, TRouteState = TU
      */
     dispose(): void;
     scheduleSearch: (() => void) & {
-        wait(): Promise<void>;
-        cancel(): void;
+        wait: () => Promise<void>;
+        cancel: () => void;
     };
     scheduleRender: ((shouldResetStatus?: boolean) => void) & {
-        wait(): Promise<void>;
-        cancel(): void;
+        wait: () => Promise<void>;
+        cancel: () => void;
     };
     scheduleStalledRender(): void;
     /**
@@ -2444,8 +2466,8 @@ declare class InstantSearch<TUiState extends UiState = UiState, TRouteState = TU
     setUiState(uiState: TUiState | ((previousUiState: TUiState) => TUiState), callOnStateChange?: boolean): void;
     getUiState(): TUiState;
     onInternalStateChange: (() => void) & {
-        wait(): Promise<void>;
-        cancel(): void;
+        wait: () => Promise<void>;
+        cancel: () => void;
     };
     createURL(nextState?: TUiState): string;
     refresh(): void;
@@ -2498,9 +2520,9 @@ declare type InstantSearchModule = {
  */
 declare type InstantSearchOptions<TUiState extends UiState = UiState, TRouteState = TUiState> = {
     /**
-     * The name of the main index
+     * The name of the main index. If no indexName is provided, you have to manually add an index widget.
      */
-    indexName: string;
+    indexName?: string;
     /**
      * The search client to plug to InstantSearch.js
      *
@@ -2549,7 +2571,7 @@ declare type InstantSearchOptions<TUiState extends UiState = UiState, TRouteStat
      */
     onStateChange?: (params: {
         uiState: TUiState;
-        setUiState(uiState: TUiState | ((previousUiState: TUiState) => TUiState)): void;
+        setUiState: (uiState: TUiState | ((previousUiState: TUiState) => TUiState)) => void;
     }) => void;
     /**
      * Injects a `uiState` to the `instantsearch` instance. You can use this option
@@ -2567,6 +2589,16 @@ declare type InstantSearchOptions<TUiState extends UiState = UiState, TRouteStat
      * client side persistence. Passing `true` will use the default URL options.
      */
     routing?: RouterProps<TUiState, TRouteState> | boolean;
+    /**
+     * Enables the Insights middleware and loads the Insights library
+     * if not already loaded.
+     *
+     * The Insights middleware sends view and click events automatically, and lets
+     * you set up your own events.
+     *
+     * @default false
+     */
+    insights?: InsightsProps | boolean;
     /**
      * the instance of search-insights to use for sending insights events inside
      * widgets like `hits`.
@@ -2702,7 +2734,7 @@ declare type MenuRenderState = {
     /**
      * Filter the search to item value.
      */
-    refine(value: string): void;
+    refine: (value: string) => void;
     /**
      * True if refinement can be applied.
      */
@@ -2714,7 +2746,7 @@ declare type MenuRenderState = {
     /**
      * Toggles the number of values displayed between `limit` and `showMore.limit`.
      */
-    toggleShowMore(): void;
+    toggleShowMore: () => void;
     /**
      * `true` if the toggleShowMore button can be activated (enough items to display more or
      * already displaying more than `limit` items)
@@ -2836,15 +2868,31 @@ declare type MenuWidgetParams = {
     cssClasses?: MenuCSSClasses;
 };
 
-declare type Middleware = (options: MiddlewareOptions) => AtLeastOne<MiddlewareDefinition>;
+declare type Middleware<TUiState extends UiState = UiState> = (options: MiddlewareOptions) => AtLeastOne<MiddlewareDefinition<TUiState>>;
 
 declare type MiddlewareDefinition<TUiState extends UiState = UiState> = {
-    onStateChange(options: {
+    /**
+     * string to identify the middleware
+     */
+    $$type: string;
+    /**
+     * Change handler called on every UiState change
+     */
+    onStateChange: (options: {
         uiState: TUiState;
-    }): void;
-    subscribe(): void;
-    started(): void;
-    unsubscribe(): void;
+    }) => void;
+    /**
+     * Called when the middleware is added to InstantSearch
+     */
+    subscribe: () => void;
+    /**
+     * Called when InstantSearch is started
+     */
+    started: () => void;
+    /**
+     * Called when the middleware is removed from InstantSearch
+     */
+    unsubscribe: () => void;
 };
 
 declare type MiddlewareOptions = {
@@ -2856,6 +2904,7 @@ declare namespace middlewares {
         createInsightsMiddleware,
         InsightsEvent,
         InsightsProps,
+        InsightsClientWithGlobals,
         CreateInsightsMiddleware,
         RouterProps,
         createRouterMiddleware,
@@ -3126,7 +3175,7 @@ declare type PaginationRenderState = {
     /** Creates URLs for the next state, the number is the page to generate the URL for. */
     createURL: CreateURL<number>;
     /** Sets the current page and triggers a search. */
-    refine(page: number): void;
+    refine: (page: number) => void;
     /** true if this search returned more than one page */
     canRefine: boolean;
     /** The number of the page currently displayed. */
@@ -3304,12 +3353,12 @@ declare type PanelWidgetParams<TWidgetFactory extends AnyWidgetFactory> = {
      * A function that is called on each render to determine if the
      * panel should be hidden based on the render options.
      */
-    hidden?(options: PanelRenderOptions<TWidgetFactory>): boolean;
+    hidden?: (options: PanelRenderOptions<TWidgetFactory>) => boolean;
     /**
      * A function that is called on each render to determine if the
      * panel should be collapsed based on the render options.
      */
-    collapsed?(options: PanelRenderOptions<TWidgetFactory>): boolean;
+    collapsed?: (options: PanelRenderOptions<TWidgetFactory>) => boolean;
     /**
      * The templates to use for the widget.
      */
@@ -3431,6 +3480,8 @@ declare type PoweredByWidgetParams = {
     cssClasses?: PoweredByCSSClasses;
 };
 
+declare type ProvidedInsightsClient = InsightsClient | null | undefined;
+
 declare const queryRuleContext: QueryRuleContextWidget;
 
 declare type QueryRuleContextWidget = WidgetFactory<QueryRulesWidgetDescription & {
@@ -3623,7 +3674,7 @@ declare type RangeRenderState = {
      * previously set bound or to set an infinite bound.
      * @param rangeValue tuple of [min, max] bounds
      */
-    refine(rangeValue: RangeBoundaries): void;
+    refine: (rangeValue: RangeBoundaries) => void;
     /**
      * Indicates whether this widget can be refined
      */
@@ -3645,8 +3696,8 @@ declare type RangeRenderState = {
      * Both functions take a `number` as input and should output a `string`.
      */
     format: {
-        from(fromValue: number): string;
-        to(toValue: number): string;
+        from: (fromValue: number) => string;
+        to: (toValue: number) => string;
     };
 };
 
@@ -3681,7 +3732,7 @@ declare type RangeSliderTooltipOptions = {
      * @example
      * { format(rawValue) {return '$' + Math.round(rawValue).toLocaleString() } }
      */
-    format(value: number): string;
+    format: (value: number) => string;
 };
 
 declare type RangeSliderWidget = WidgetFactory<Omit<RangeWidgetDescription, '$$type'> & {
@@ -3941,7 +3992,7 @@ declare type ReconfigurableOptions = Places.ReconfigurableOptions;
  */
 declare type Refine = (searchParameters: PlainSearchParameters) => void;
 
-declare type Refine_2 = (relevancyStrictness: number) => void;
+declare type Refine_2 = (relevancyStrictness: number | undefined) => void;
 
 /**
  * The refinement list widget is one of the most common widget that you can find
@@ -4155,7 +4206,7 @@ declare type RefinementListRenderState = {
     /**
      * Action to apply selected refinements.
      */
-    refine(value: string): void;
+    refine: (value: string) => void;
     /**
      * Send event to insights middleware
      */
@@ -4163,7 +4214,7 @@ declare type RefinementListRenderState = {
     /**
      * Searches for values inside the list.
      */
-    searchForItems(query: string): void;
+    searchForItems: (query: string) => void;
     /**
      * `true` if the values are from an index search.
      */
@@ -4184,7 +4235,7 @@ declare type RefinementListRenderState = {
     /**
      * Toggles the number of values displayed between `limit` and `showMoreLimit`.
      */
-    toggleShowMore(): void;
+    toggleShowMore: () => void;
 };
 
 declare type RefinementListSearchableCSSClasses = Partial<{
@@ -4538,30 +4589,34 @@ declare type Router<TRouteState = UiState> = {
      * In the case of the history / URL in a browser, the callback will be called
      * by `onPopState`.
      */
-    onUpdate(callback: (route: TRouteState) => void): void;
+    onUpdate: (callback: (route: TRouteState) => void) => void;
     /**
      * Reads the storage and gets a route object. It does not take parameters,
      * and should return an object
      */
-    read(): TRouteState;
+    read: () => TRouteState;
     /**
      * Pushes a route object into a storage. Takes the UI state mapped by the state
      * mapping configured in the mapping
      */
-    write(route: TRouteState): void;
+    write: (route: TRouteState) => void;
     /**
      * Transforms a route object into a URL. It receives an object and should
      * return a string. It may return an empty string.
      */
-    createURL(state: TRouteState): string;
+    createURL: (state: TRouteState) => string;
     /**
      * Called when InstantSearch is disposed. Used to remove subscriptions.
      */
-    dispose(): void;
+    dispose: () => void;
     /**
      * Called when InstantSearch is started.
      */
     start?: () => void;
+    /**
+     * Identifier for this router. Used to differentiate between routers.
+     */
+    $$type?: string;
 };
 
 declare type RouterProps<TUiState extends UiState = UiState, TRouteState = TUiState> = {
@@ -4781,7 +4836,7 @@ declare type SharedRenderOptions = {
     };
     status: InstantSearch['status'];
     error: InstantSearch['error'];
-    createURL(state: SearchParameters): string;
+    createURL: (state: SearchParameters) => string;
 };
 
 declare function simpleStateMapping<TUiState extends UiState = UiState>(): StateMapping<TUiState, TUiState>;
@@ -4986,13 +5041,17 @@ declare type StateMapping<TUiState = UiState, TRouteState = TUiState> = {
      * It should return an object of any form as long as this form can be read by
      * the `routeToState` function.
      */
-    stateToRoute(uiState: TUiState): TRouteState;
+    stateToRoute: (uiState: TUiState) => TRouteState;
     /**
      * Transforms route object into a UI state representation.
      * It receives an object that contains the UI state stored by the router.
      * The format is the output of `stateToRoute`.
      */
-    routeToState(routeState: TRouteState): TUiState;
+    routeToState: (routeState: TRouteState) => TUiState;
+    /**
+     * Identifier for this stateMapping. Used to differentiate between stateMappings.
+     */
+    $$type?: string;
 };
 
 declare namespace stateMappings {