@searchcraft/react-sdk 0.10.1 → 0.10.3

package/dist/server/index.d.ts

@@ -42,7 +42,7 @@ export type SearchResultFieldName = {
 	numberFormatLocale?: string;
 	/**
 	 * If it's a number, the number format to apply.
-	 * reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat
+	 * Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat
 	 */
 	numberFormatOptions?: Intl.NumberFormatOptions;
 	/**
@@ -50,9 +50,14 @@ export type SearchResultFieldName = {
 	 */
 	numberScale?: number;
 	/**
-	 * TODO: Implement DateFormatOptions, for date formatting
+	 * The locale to use when formatting dataType: `date`.
 	 */
-	dateFormatOptions?: unknown;
+	dateFormatLocale?: string;
+	/**
+	 * If it's a date, the date format to apply.
+	 * Reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
+	 */
+	dateFormatOptions?: Intl.DateTimeFormatOptions;
 };
 /**
  * A data type representing the mapping of index fields, for the purpose of rendering them
@@ -112,6 +117,7 @@ export interface ExactMatchToggleFilterItem extends FilterItem {
 	};
 }
 export interface MostRecentToggleFilterItem extends FilterItem {
+	fieldName: string;
 	type: "mostRecentToggle";
 	options: {
 		subLabel?: string;
@@ -120,6 +126,7 @@ export interface MostRecentToggleFilterItem extends FilterItem {
 export type TemplateHtml = (strings: TemplateStringsArray, ...values: (string | number | undefined)[]) => string;
 export type SearchResultTemplate<T> = (data: T, index: number, utils: {
 	html: TemplateHtml;
+	source_index?: string;
 }) => string;
 export type SearchResultTemplateData = any;
 export type ResultsInfoTemplate = (data: {
@@ -138,7 +145,12 @@ export type CustomAdTemplate = (data: {
 }, utils: {
 	html: TemplateHtml;
 }) => string;
-export type PopoverButtonTemplate = (data: boolean, utils: {
+export type PopoverButtonTemplate = (data: {
+	isPopoverVisible: boolean;
+}, utils: {
+	html: TemplateHtml;
+}) => string;
+export type ADMAdTemplate = (data: ADMAd, utils: {
 	html: TemplateHtml;
 }) => string;
 /**
@@ -146,11 +158,11 @@ export type PopoverButtonTemplate = (data: boolean, utils: {
  */
 export interface SearchcraftConfig {
 	/**
-	 * Host IP Address and port number configured and created using Vektron
+	 * Host IP Address and port number configured and created using Vektron.
 	 */
 	endpointURL: string;
 	/**
-	 * Name or names of search indices configured using Vektron. Given as an array of strings
+	 * Name or names of search indices configured using Vektron. Given as an array of strings.
 	 */
 	index: string[];
 	/**
@@ -189,6 +201,10 @@ export interface SearchcraftConfig {
 	 * The amount of debounce delay to add before calling the ad_container_rendered event
 	 */
 	adContainerRenderedDebounceDelay?: number;
+	/**
+	 * A callback function responsible for rendering the ADM ad containers.
+	 */
+	admAdTemplate?: ADMAdTemplate;
 	/**
 	 * The number of custom ads to render at the start of the search results page.
 	 */
@@ -250,6 +266,17 @@ export interface AdClientResponseItem {
 	id: string;
 	adSource: SearchcraftAdSource;
 }
+export interface ADMAd {
+	adv_id: number;
+	adv_name: string;
+	click_url?: string;
+	image_url?: string;
+	impression_url?: string;
+	price?: number;
+	price_currency?: string;
+	sale_price?: number;
+	term: string;
+}
 /**
  * A Facet object returned in a search response.
  */
@@ -301,6 +328,56 @@ export interface MeasureRequestUser {
 	latitude?: number;
 	longitude?: number;
 }
+export interface FacetPathsForIndexField {
+	fieldName: string;
+	value: string;
+}
+export interface RangeValueForIndexField {
+	fieldName: string;
+	value: string;
+}
+export interface SearchClientRequestProperties {
+	/**
+	 * The search mode, which can be either 'fuzzy' or 'exact'.
+	 */
+	mode: "fuzzy" | "exact";
+	/**
+	 * The starting point for the results, used for pagination.
+	 * Optional parameter.
+	 */
+	offset?: number;
+	/**
+	 * The number of results returned.
+	 * Optional parameter.
+	 */
+	limit?: number;
+	/**
+	 * The field to order the results by (e.g., 'date_published', 'title', etc.).
+	 * Optional parameter.
+	 */
+	order_by?: string | null;
+	/**
+	 * The search term provided by the user.
+	 */
+	searchTerm: string;
+	/**
+	 * The sort order, which can be either 'asc' or 'desc'.
+	 * Optional parameter.
+	 */
+	sort?: "asc" | "desc" | null;
+	/**
+	 * The facet path value(s) specified by the `facets` filter items that the `searchcraft-filter-panel` renders.
+	 * There may be multiple rendered within a single filter panel.
+	 * Optional parameter.
+	 */
+	facetPathsForIndexFields?: Record<string, FacetPathsForIndexField>;
+	/**
+	 * The date range slider value(s) specified by the `dateRange` filter items that the `searchcraft-filter-panel` renders.
+	 * There may be multiple rendered within a single filter panel.
+	 * Optional parameter.
+	 */
+	rangeValueForIndexFields?: Record<string, RangeValueForIndexField>;
+}
 /**
  * The structure of a response returned from a Searchcraft operation.
  */
@@ -327,16 +404,17 @@ export type SearchcraftResponseError = {
 export interface SearchcraftResponseData {
 	count?: number;
 	facets?: FacetPrime;
-	hits?: SearchIndexEntry[];
+	hits?: SearchIndexHit[];
 	time_taken?: number;
 }
 /**
  * Represents an entry in the search index returned as part of a search result.
  */
-export interface SearchIndexEntry {
+export interface SearchIndexHit {
 	doc?: SearchDocument;
 	document_id?: string;
 	score?: number;
+	source_index?: string;
 }
 /**
  * Data document returned within a SearchResult.
@@ -348,55 +426,14 @@ export interface SearchDocument extends Record<string, string | number> {
 export interface SearchClientResponseItem {
 	id: string;
 	document: SearchDocument;
+	source_index?: string;
 }
-export type FacetPathsForIndexField = {
-	fieldName: string;
-	value: string;
-};
-export type RangeValueForIndexField = {
-	fieldName: string;
-	value: string;
-};
-/**
- * Parameters required to make a successful Search request.
- */
-export type SearchParams = {
-	/**
-	 * The search mode, which can be either 'fuzzy' or 'exact'.
-	 */
-	mode: "fuzzy" | "exact";
-	/**
-	 * The starting point for the results, used for pagination.
-	 * Optional parameter.
-	 */
-	offset?: number;
-	/**
-	 * The number of results returned.
-	 * Optional parameter.
-	 */
-	limit?: number;
-	/**
-	 * The field to order the results by (e.g., 'date_published', 'title', etc.).
-	 * Optional parameter.
-	 */
-	order_by?: string;
-	/**
-	 * The search term provided by the user.
-	 */
-	searchTerm: string;
-	/**
-	 * The sort order, which can be either 'asc' or 'desc'.
-	 * Optional parameter.
-	 */
-	sort?: "asc" | "desc";
-	facetPathsForIndexFields?: Record<string, FacetPathsForIndexField>;
-	rangeValueForIndexFields?: Record<string, RangeValueForIndexField>;
-};
 export interface SubscriptionEventMap {
 	ad_container_rendered: AdContainerRenderedSubscriptionEvent;
 	ad_container_viewed: AdContainerViewedSubscriptionEvent;
 	query_fetched: QueryFetchedEvent;
 	query_submitted: QuerySubmittedEvent;
+	initialized: InitializedEvent;
 	input_cleared: InputClearedEvent;
 	no_results_returned: NoResultsReturnedEvent;
 }
@@ -434,6 +471,9 @@ export interface InputClearedEvent extends SubscriptionEvent {
 export interface NoResultsReturnedEvent extends SubscriptionEvent {
 	name: "no_results_returned";
 }
+export interface InitializedEvent extends SubscriptionEvent {
+	name: "initialized";
+}
 export type SubscriptionEventName = keyof SubscriptionEventMap;
 export type SubscriptionEventCallback<T extends SubscriptionEventName> = (event: SubscriptionEventMap[T]) => void;
 export type UnsubscribeFunction = () => void;
@@ -443,9 +483,9 @@ export interface SubscriptionEvent {
 declare class AdClient {
 	config: SearchcraftConfig;
 	constructor(config: SearchcraftConfig);
-	getAdsForSearchParams(_params: SearchParams): Promise<AdClientResponseItem[]>;
-	onQuerySubmitted(_params: SearchParams): Promise<void>;
-	onQueryFetched(_params: SearchParams, _response: SearchcraftResponse): Promise<void>;
+	getAds(_properties: SearchClientRequestProperties): Promise<AdClientResponseItem[]>;
+	onQuerySubmitted(_properties: SearchClientRequestProperties): Promise<void>;
+	onQueryFetched(_properties: SearchClientRequestProperties, _response: SearchcraftResponse): Promise<void>;
 	onInputCleared(): Promise<void>;
 	onAdContainerRendered(_data: {
 		adClientResponseItem?: AdClientResponseItem;
@@ -466,7 +506,7 @@ declare class MeasureClient {
 	private config;
 	private sdkInfo;
 	private userId;
-	private sessionId;
+	sessionId: string;
 	constructor(config: SearchcraftConfig, sdkInfo: SearchcraftSDKInfo, userId: string);
 	/**
 	 * Getter for the base url used by the /measure endpoints.
@@ -496,10 +536,19 @@ declare class SearchClient {
 	 */
 	private get baseSearchUrl();
 	/**
-	 * Performs a search operation.
-	 * @param {SearchParams} searchParams - The parameters for the search.
+	 * Make the request to get the search results.
+	 * @param {properties} properties - The properties for the search.
+	 * @returns
+	 */
+	getSearchResponseItems: (properties: SearchClientRequestProperties | string) => Promise<SearchcraftResponse>;
+	private handleGetSearchResponseItemsWithString;
+	private handleGetSearchResponseItemsWithObject;
+	/**
+	 * Builds a query object for the SearchClient request.
+	 * @param {properties} properties - The properties for the search.
+	 * @returns {SearchClientQuery} - A properly formatted SearchClient query object.
 	 */
-	getSearchResponse: (searchParams: SearchParams) => Promise<SearchcraftResponse>;
+	private formatParamsForRequest;
 }
 /**
  * Javascript Class providing the functionality to interact with the Searchcraft BE
@@ -543,30 +592,36 @@ export declare class SearchcraftCore {
 	 * Perform various actions when the input is cleared
 	 */
 	handleInputCleared(): void;
-	/**
-	 * Gets items from the SearchClient and the AdClient.
-	 */
-	getItems: (searchParams: SearchParams, itemsCallback: (response: SearchcraftResponse, items: SearchClientResponseItem[]) => void, adCallback: (adClientResponseItems: AdClientResponseItem[]) => void) => void;
+	getResponseItems: (properties: SearchClientRequestProperties | string, searchCallback: (response: SearchcraftResponse, items: SearchClientResponseItem[]) => void, adCallback: (items: AdClientResponseItem[]) => void) => void;
 }
 /**
  * Callable functions made available by the SearchcraftStore.
  */
 export interface SearchcraftStateFunctions {
-	addFacetPathsForIndexField: (data: FacetPathsForIndexField) => void;
-	addRangeValueForIndexField: (data: RangeValueForIndexField) => void;
-	getSearchcraftInstance: () => SearchcraftCore | undefined;
-	initialize: (searchcraft: unknown, debug?: boolean) => void;
+	addFacetPathsForIndexField: (field: FacetPathsForIndexField) => void;
+	addRangeValueForIndexField: (field: RangeValueForIndexField) => void;
+	getSearchcraftCore: () => SearchcraftCore | undefined;
+	init: (searchcraft: SearchcraftCore | undefined, debug?: boolean) => void;
 	removeFacetPathsForIndexField: (fieldName: string) => void;
 	removeRangeValueForIndexField: (fieldName: string) => void;
 	resetFacetPaths: () => void;
 	search: () => Promise<void>;
+	set: (state: Partial<SearchcraftState> | ((state: SearchcraftState) => Partial<SearchcraftState>)) => SearchcraftState;
+	setAdClientResponseItems: (items: AdClientResponseItem[]) => void;
+	setSearchClientResponseItemsFromResponse: (response: SearchcraftResponse, items: SearchClientResponseItem[]) => void;
+	setInitialSearchClientResponseItemsFromResponse: (response: SearchcraftResponse, items: SearchClientResponseItem[]) => void;
+	setInitialQuery: (query: string) => void;
 	setPopoverVisibility: (isVisible: boolean) => void;
-	setSearchClientResponseItems: (results: SearchClientResponseItem[]) => void;
+	setSearchResultsCount: (count: number) => void;
+	setSearchClientResponseItems: (items: SearchClientResponseItem[]) => void;
 	setSearchResultsPage: (page: number) => void;
 	setSearchResultsPerPage: (perPage: number) => void;
 	setSearchTerm: (searchTerm: string) => void;
 	setSearchMode: (mode: "fuzzy" | "exact") => void;
-	setSortType: (type: "asc" | "desc") => void;
+	setSortOrder: (props: {
+		orderByField: string | null;
+		sortType: "asc" | "desc" | null;
+	}) => void;
 	setHotKeyAndHotKeyModifier: (hotkey?: string, hotkeyModifier?: "ctrl" | "meta" | "alt" | "option") => void;
 }
 /**
@@ -579,6 +634,8 @@ export interface SearchcraftStateValues {
 	hotkeyModifier: "ctrl" | "meta" | "alt" | "option";
 	logger: Logger | undefined;
 	facetPathsForIndexFields: Record<string, FacetPathsForIndexField>;
+	initialQuery: string;
+	initialSearchClientResponseItems: SearchClientResponseItem[];
 	isPopoverVisible: boolean;
 	isSearchInProgress: boolean;
 	rangeValueForIndexFields: Record<string, RangeValueForIndexField>;
@@ -590,13 +647,13 @@ export interface SearchcraftStateValues {
 	searchResultsPage: number;
 	searchResultsPerPage: number;
 	searchTerm: string;
-	sortType: "asc" | "desc";
+	orderByField: string | undefined | null;
+	sortType: "asc" | "desc" | undefined | null;
+	afterInit: (state: SearchcraftState) => void;
 }
 export interface SearchcraftState extends SearchcraftStateFunctions, SearchcraftStateValues {
 }
 export declare const searchcraftStore: import("zustand").StoreApi<SearchcraftState>;
-export declare function parseCustomStyles(styles: string | Record<string, string>): Record<string, string>;
-export declare function serializeStyles(styles: Record<string, Record<string, string>>): string;
 export type SearchcraftSelectOption = {
 	label: string;
 	value: string | number;
@@ -800,13 +857,13 @@ export namespace Components {
 	 * ```js
 	 * // index.js
 	 * const popoverButton = document.querySelector('searchcraft-popover-button');
-	 * popoverButton.template = (isPopoverVisible, { html }) => html`
+	 * popoverButton.template = ({ isPopoverVisible }, { html }) => html`
 	 *   <span>Click me</span>
 	 * `;
 	 * ```
 	 * @react-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   template={(isPopoverVisible, { html }) => html`
+	 *   template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -815,7 +872,7 @@ export namespace Components {
 	 * ```
 	 * @vue-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   :template={(isPopoverVisible, { html }) => html`
+	 *   :template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -1011,6 +1068,10 @@ export namespace Components {
 	 * ```
 	 */
 	interface SearchcraftSearchResults {
+		/**
+		  * A query that will appears when the component initializes or the search term is ''..
+		 */
+		"initialQuery"?: string;
 		/**
 		  * A callback function responsible for rendering a result. Passed to `searchcraft-search-result`.
 		 */
@@ -1363,13 +1424,13 @@ declare global {
 	 * ```js
 	 * // index.js
 	 * const popoverButton = document.querySelector('searchcraft-popover-button');
-	 * popoverButton.template = (isPopoverVisible, { html }) => html`
+	 * popoverButton.template = ({ isPopoverVisible }, { html }) => html`
 	 *   <span>Click me</span>
 	 * `;
 	 * ```
 	 * @react-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   template={(isPopoverVisible, { html }) => html`
+	 *   template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -1378,7 +1439,7 @@ declare global {
 	 * ```
 	 * @vue-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   :template={(isPopoverVisible, { html }) => html`
+	 *   :template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -1910,13 +1971,13 @@ declare namespace LocalJSX {
 	 * ```js
 	 * // index.js
 	 * const popoverButton = document.querySelector('searchcraft-popover-button');
-	 * popoverButton.template = (isPopoverVisible, { html }) => html`
+	 * popoverButton.template = ({ isPopoverVisible }, { html }) => html`
 	 *   <span>Click me</span>
 	 * `;
 	 * ```
 	 * @react-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   template={(isPopoverVisible, { html }) => html`
+	 *   template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -1925,7 +1986,7 @@ declare namespace LocalJSX {
 	 * ```
 	 * @vue-example ```jsx
 	 * <SearchcraftPopoverButton
-	 *   :template={(isPopoverVisible, { html }) => html`
+	 *   :template={({ isPopoverVisible }, { html }) => html`
 	 *     <span>Click me</span>
 	 *   `}
 	 * >
@@ -2121,6 +2182,10 @@ declare namespace LocalJSX {
 	 * ```
 	 */
 	interface SearchcraftSearchResults {
+		/**
+		  * A query that will appears when the component initializes or the search term is ''..
+		 */
+		"initialQuery"?: string;
 		/**
 		  * A callback function responsible for rendering a result. Passed to `searchcraft-search-result`.
 		 */
@@ -2409,13 +2474,13 @@ declare module "@stencil/core" {
 			 * ```js
 			 * // index.js
 			 * const popoverButton = document.querySelector('searchcraft-popover-button');
-			 * popoverButton.template = (isPopoverVisible, { html }) => html`
+			 * popoverButton.template = ({ isPopoverVisible }, { html }) => html`
 			 *   <span>Click me</span>
 			 * `;
 			 * ```
 			 * @react-example ```jsx
 			 * <SearchcraftPopoverButton
-			 *   template={(isPopoverVisible, { html }) => html`
+			 *   template={({ isPopoverVisible }, { html }) => html`
 			 *     <span>Click me</span>
 			 *   `}
 			 * >
@@ -2424,7 +2489,7 @@ declare module "@stencil/core" {
 			 * ```
 			 * @vue-example ```jsx
 			 * <SearchcraftPopoverButton
-			 *   :template={(isPopoverVisible, { html }) => html`
+			 *   :template={({ isPopoverVisible }, { html }) => html`
 			 *     <span>Click me</span>
 			 *   `}
 			 * >