instantsearch.js 4.54.0 → 4.55.0

package/dist/instantsearch.production.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.
      */
@@ -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>;
 
@@ -1774,6 +1777,9 @@ declare type HierarchicalMenuWidgetParams = {
 
 declare function Highlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: HighlightProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the Highlight component instead
+ */
 declare function highlight({ attribute, highlightedTagName, hit, cssClasses, }: HighlightOptions): string;
 
 declare type HighlightClassNames = HighlightClassNames_2;
@@ -2310,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';
     };
@@ -2475,9 +2500,13 @@ declare type InstantSearchModule = {
     routers: typeof routers;
     stateMappings: typeof stateMappings;
     createInfiniteHitsSessionStorageCache: typeof createInfiniteHitsSessionStorageCache;
+    /** @deprecated use html tagged templates and the Highlight component instead */
     highlight: typeof helpers.highlight;
+    /** @deprecated use html tagged templates and the ReverseHighlight component instead */
     reverseHighlight: typeof helpers.reverseHighlight;
+    /** @deprecated use html tagged templates and the Snippet component instead */
     snippet: typeof helpers.snippet;
+    /** @deprecated use html tagged templates and the ReverseSnippet component instead */
     reverseSnippet: typeof helpers.reverseSnippet;
     /**
      * @deprecated use createInsightsMiddleware
@@ -2560,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`.
@@ -2832,11 +2871,27 @@ declare type MenuWidgetParams = {
 declare type Middleware = (options: MiddlewareOptions) => AtLeastOne<MiddlewareDefinition>;
 
 declare type MiddlewareDefinition<TUiState extends UiState = UiState> = {
+    /**
+     * string to identify the middleware
+     */
+    $$type: string;
+    /**
+     * Change handler called on every UiState change
+     */
     onStateChange(options: {
         uiState: TUiState;
     }): 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;
 };
 
@@ -2849,6 +2904,7 @@ declare namespace middlewares {
         createInsightsMiddleware,
         InsightsEvent,
         InsightsProps,
+        InsightsClientWithGlobals,
         CreateInsightsMiddleware,
         RouterProps,
         createRouterMiddleware,
@@ -3140,19 +3196,26 @@ declare type PaginationTemplates = Partial<{
     /**
      * Label for the Previous link.
      */
-    previous: string;
+    previous: Template;
     /**
      * Label for the Next link.
      */
-    next: string;
+    next: Template;
+    /**
+     * Label for the link of a certain page
+     * Page is one-based, so `page` will be `1` for the first page.
+     */
+    page: Template<{
+        page: number;
+    }>;
     /**
      * Label for the First link.
      */
-    first: string;
+    first: Template;
     /**
      * Label for the Last link.
      */
-    last: string;
+    last: Template;
 }>;
 
 declare type PaginationWidget = WidgetFactory<PaginationWidgetDescription & {
@@ -3417,6 +3480,8 @@ declare type PoweredByWidgetParams = {
     cssClasses?: PoweredByCSSClasses;
 };
 
+declare type ProvidedInsightsClient = InsightsClient | null | undefined;
+
 declare const queryRuleContext: QueryRuleContextWidget;
 
 declare type QueryRuleContextWidget = WidgetFactory<QueryRulesWidgetDescription & {
@@ -4459,6 +4524,9 @@ declare type RequiredWidgetType<TWidgetDescription extends WidgetDescription> =
 
 declare function ReverseHighlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseHighlightProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the ReverseHighlight component instead
+ */
 declare function reverseHighlight({ attribute, highlightedTagName, hit, cssClasses, }: ReverseHighlightOptions): string;
 
 declare type ReverseHighlightClassNames = HighlightClassNames_2;
@@ -4484,6 +4552,9 @@ declare type ReverseHighlightProps_2 = Omit<HighlightProps_3, 'classNames'> & {
 
 declare function ReverseSnippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseSnippetProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the ReverseSnippet component instead
+ */
 declare function reverseSnippet({ attribute, highlightedTagName, hit, cssClasses, }: ReverseSnippetOptions): string;
 
 declare type ReverseSnippetClassNames = HighlightClassNames_2;
@@ -4542,6 +4613,10 @@ declare type Router<TRouteState = UiState> = {
      * 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> = {
@@ -4770,6 +4845,9 @@ declare function singleIndexStateMapping<TUiState extends UiState = UiState>(ind
 
 declare function Snippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: SnippetProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the Snippet component instead
+ */
 declare function snippet({ attribute, highlightedTagName, hit, cssClasses, }: SnippetOptions): string;
 
 declare type SnippetClassNames = HighlightClassNames_2;
@@ -4970,6 +5048,10 @@ declare type StateMapping<TUiState = UiState, TRouteState = TUiState> = {
      * The format is the output of `stateToRoute`.
      */
     routeToState(routeState: TRouteState): TUiState;
+    /**
+     * Identifier for this stateMapping. Used to differentiate between stateMappings.
+     */
+    $$type?: string;
 };
 
 declare namespace stateMappings {

package/dist/instantsearch.production.min.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.
      */
@@ -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>;
 
@@ -1774,6 +1777,9 @@ declare type HierarchicalMenuWidgetParams = {
 
 declare function Highlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: HighlightProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the Highlight component instead
+ */
 declare function highlight({ attribute, highlightedTagName, hit, cssClasses, }: HighlightOptions): string;
 
 declare type HighlightClassNames = HighlightClassNames_2;
@@ -2310,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';
     };
@@ -2475,9 +2500,13 @@ declare type InstantSearchModule = {
     routers: typeof routers;
     stateMappings: typeof stateMappings;
     createInfiniteHitsSessionStorageCache: typeof createInfiniteHitsSessionStorageCache;
+    /** @deprecated use html tagged templates and the Highlight component instead */
     highlight: typeof helpers.highlight;
+    /** @deprecated use html tagged templates and the ReverseHighlight component instead */
     reverseHighlight: typeof helpers.reverseHighlight;
+    /** @deprecated use html tagged templates and the Snippet component instead */
     snippet: typeof helpers.snippet;
+    /** @deprecated use html tagged templates and the ReverseSnippet component instead */
     reverseSnippet: typeof helpers.reverseSnippet;
     /**
      * @deprecated use createInsightsMiddleware
@@ -2560,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`.
@@ -2832,11 +2871,27 @@ declare type MenuWidgetParams = {
 declare type Middleware = (options: MiddlewareOptions) => AtLeastOne<MiddlewareDefinition>;
 
 declare type MiddlewareDefinition<TUiState extends UiState = UiState> = {
+    /**
+     * string to identify the middleware
+     */
+    $$type: string;
+    /**
+     * Change handler called on every UiState change
+     */
     onStateChange(options: {
         uiState: TUiState;
     }): 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;
 };
 
@@ -2849,6 +2904,7 @@ declare namespace middlewares {
         createInsightsMiddleware,
         InsightsEvent,
         InsightsProps,
+        InsightsClientWithGlobals,
         CreateInsightsMiddleware,
         RouterProps,
         createRouterMiddleware,
@@ -3140,19 +3196,26 @@ declare type PaginationTemplates = Partial<{
     /**
      * Label for the Previous link.
      */
-    previous: string;
+    previous: Template;
     /**
      * Label for the Next link.
      */
-    next: string;
+    next: Template;
+    /**
+     * Label for the link of a certain page
+     * Page is one-based, so `page` will be `1` for the first page.
+     */
+    page: Template<{
+        page: number;
+    }>;
     /**
      * Label for the First link.
      */
-    first: string;
+    first: Template;
     /**
      * Label for the Last link.
      */
-    last: string;
+    last: Template;
 }>;
 
 declare type PaginationWidget = WidgetFactory<PaginationWidgetDescription & {
@@ -3417,6 +3480,8 @@ declare type PoweredByWidgetParams = {
     cssClasses?: PoweredByCSSClasses;
 };
 
+declare type ProvidedInsightsClient = InsightsClient | null | undefined;
+
 declare const queryRuleContext: QueryRuleContextWidget;
 
 declare type QueryRuleContextWidget = WidgetFactory<QueryRulesWidgetDescription & {
@@ -4459,6 +4524,9 @@ declare type RequiredWidgetType<TWidgetDescription extends WidgetDescription> =
 
 declare function ReverseHighlight<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseHighlightProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the ReverseHighlight component instead
+ */
 declare function reverseHighlight({ attribute, highlightedTagName, hit, cssClasses, }: ReverseHighlightOptions): string;
 
 declare type ReverseHighlightClassNames = HighlightClassNames_2;
@@ -4484,6 +4552,9 @@ declare type ReverseHighlightProps_2 = Omit<HighlightProps_3, 'classNames'> & {
 
 declare function ReverseSnippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: ReverseSnippetProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the ReverseSnippet component instead
+ */
 declare function reverseSnippet({ attribute, highlightedTagName, hit, cssClasses, }: ReverseSnippetOptions): string;
 
 declare type ReverseSnippetClassNames = HighlightClassNames_2;
@@ -4542,6 +4613,10 @@ declare type Router<TRouteState = UiState> = {
      * 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> = {
@@ -4770,6 +4845,9 @@ declare function singleIndexStateMapping<TUiState extends UiState = UiState>(ind
 
 declare function Snippet<THit extends Hit<BaseHit>>({ hit, attribute, cssClasses, ...props }: SnippetProps<THit>): h.JSX.Element;
 
+/**
+ * @deprecated use html tagged templates and the Snippet component instead
+ */
 declare function snippet({ attribute, highlightedTagName, hit, cssClasses, }: SnippetOptions): string;
 
 declare type SnippetClassNames = HighlightClassNames_2;
@@ -4970,6 +5048,10 @@ declare type StateMapping<TUiState = UiState, TRouteState = TUiState> = {
      * The format is the output of `stateToRoute`.
      */
     routeToState(routeState: TRouteState): TUiState;
+    /**
+     * Identifier for this stateMapping. Used to differentiate between stateMappings.
+     */
+    $$type?: string;
 };
 
 declare namespace stateMappings {