@searchstax-inc/searchstudio-ux-js 1.1.40 → 2.0.0

package/README.md

@@ -19,6 +19,7 @@ Initialization object needs to be of type: `ISearchstaxConfig`
 interface ISearchstaxConfig {
   sessionId?: string; // session id that is used for tracking. if not defined random value will be generated
   language: string; // language code. Example: 'en'
+  model?: string; // Site Search model name.
   searchURL: string; // Site Search select endpoint
   suggesterURL: string; //Site Search suggest endpoint
   trackApiKey: string; // Api key used for tracking events
@@ -40,6 +41,7 @@ Initialization example
 ```
 searchstax.initialize({
     language: "en",
+    model: "Main Profile",
     searchURL: "",
     suggesterURL: "",
     trackApiKey: "",
@@ -124,74 +126,33 @@ Following widgets are available:
 [Data flow subscriptions](#data-flow-subscriptions)
 
 ### Answer Widget ###
-Initialization properties
+SearchStax Site Search solution offers Native JS widgets to assist in building your custom search page.
 
-a. id of container where widget will be rendered
+The SearchstaxAnswerWidget component for JS provides an AI answer widget for your searches.
 
-b. Answer widget config object of type: [ISearchstaxAnswerConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-answer-interfaces)
+**Usage**
 
-example of answer widget initialization with minimum options
 ```
 searchstax.addAnswerWidget("searchstax-answer-container", {
-  showShowMoreAfterWordCount: 100
+  showShowMoreAfterWordCount: 100,
+  feedbackwidget: feedbackConfig
 });
 ```
 
+**Props**
 
-example of answer widget initialization with lightweight feedback widget
-```
+- showShowMoreAfterWordCount - number(default 100) determining after how many symbols UI will show “Read More” view.
+- feedbackWidget – an optional object that configures thumbs-up and thumbs-down feedback functionality.
+- templates - template override. look at examples below
 
-searchstax.addAnswerWidget("searchstax-answer-container", {
-    showShowMoreAfterWordCount: 100,
-    templates: {
-      main: {
-          template: `
-        {{#shouldShowAnswer}}
-        <div class="searchstax-answer-wrap">
-            <div class="searchstax-answer-icon"></div>
-            <div>
-                <div class="searchstax-answer-container {{#showMoreButtonVisible}}searchstax-answer-show-more{{/showMoreButtonVisible}}">
-                    <div class="searchstax-answer-title">Smart Answers</div>
-                    {{#shouldShowAnswerError}}
-                        <div class="searchstax-answer-error">{{{answerErrorMessage}}}</div>
-                    {{/shouldShowAnswerError}}
-                    <div class="searchstax-answer-description">
-                        {{{fullAnswerFormatted}}}
-                        {{^showMoreButtonVisible}}
-                            {{#answerLoading}}
-                                <div class="searchstax-answer-loading"></div>
-                            {{/answerLoading}}
-                        {{/showMoreButtonVisible}}
-                    </div>
-
-                </div>
-
-                {{#showMoreButtonVisible}}
-                    <div class="searchstax-answer-load-more-button-container">
-                        {{#answerLoading}}
-                            <div class="searchstax-answer-loading"></div>
-                        {{/answerLoading}}
-                        <button class="searchstax-answer-load-more-button">Read More</button>
-                    </div>
-                {{/showMoreButtonVisible}}
-            </div>
-            <div class="searchstax-answer-footer">
-                <div id="feedbackWidgetContainer"></div>
-                <div class="searchstax-lightweight-widget-separator-inline"></div>
-                <p class="searchstax-disclaimer">Generative AI is Experimental</p>
-            </div>
-            </div>
-        {{/shouldShowAnswer}}
-        `,
-          answerContainerId: ``,
-      },
-    },
-    feedbackwidget: {
-      renderFeedbackWidget: true,
-      emailOverride: () => '',
-      thumbsUpValue: 10,
-      thumbsDownValue: 0,
-      lightweightTemplateOverride: `
+Example of feedbackWidget config:
+```
+const feedbackConfig = {
+    renderFeedbackWidget: true,
+    emailOverride: searchstaxEmailOverride,
+    thumbsUpValue: 10,
+    thumbsDownValue: 0,
+    lightweightTemplateOverride: `
      <div class="searchstax-lightweight-widget-container">
      <div class="searchstax-lightweight-widget-thumbs-up {{#thumbsUpActive}}active{{/thumbsUpActive}}">
      <svg width="17" height="17" viewBox="0 0 17 17" fill="none" xmlns="http://www.w3.org/2000/svg">
@@ -207,11 +168,26 @@ searchstax.addAnswerWidget("searchstax-answer-container", {
      </div>
      </div>
       `,
-    }
-  });
+  }
 ```
 
-example of answer widget initialization without feedback widget
+
+**searchAnswerTemplate**
+
+The templates prop allows customizing the answer UI.
+
+It receives the following props:
+
+- shouldShowAnswer – boolean
+- answerErrorMessage – string
+- fullAnswerFormatted – string
+- showMoreButtonVisible – boolean
+- answerLoading – boolean
+
+**Example**
+
+This example is based on [sitesearch-ux-js](https://www.npmjs.com/package/@searchstax-inc/searchstudio-ux-js#answer-widget):
+
 ```
 
 searchstax.addAnswerWidget("searchstax-answer-container", {
@@ -259,25 +235,46 @@ searchstax.addAnswerWidget("searchstax-answer-container", {
           answerContainerId: ``,
       },
     },
+    feedbackwidget: feedbackConfig
   });
 ```
-### Input Widget ###
-Initialization properties
 
-a. id of container where widget will be rendered
-
-b. Input widget config object of type: [ISearchstaxSearchInputConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-search-input-interfaces)
+### Input Widget ###
 
+The SearchStax Site Search solution’s Input widget provides the search input field with autosuggest/autocomplete capabilities.
 
-example of input widget initialization with minimum options
+**Usage**
 ```
 searchstax.addSearchInputWidget("searchstax-input-container", {
     suggestAfterMinChars: 3,
  });
 ```
 
+**Props**
+
+- suggestAfterMinChars - default 3. Number of characters needed for autosuggest to start triggering
+- hooks.beforeAutosuggest - callback function that gets called before firing autosuggest. autosuggestProps are being passed as a property and can be modified, if passed along further search will execute with modified properties, if null is returned then event gets canceled and search never fires.
+- hooks.afterAutosuggest - callback function that gets called after autosuggest has values but before rendering. It needs to return same type of data but it can be modified.
+- templates - template override. look at examples below
 
-example of input widget initialization with various options
+
+**inputWidgetTemplate**
+
+The templates prop allows customizing the input UI.
+
+It receives the following props:
+
+- locationEnabled – boolean
+
+**inputWidgetAutosuggestTemplate**
+
+The templates prop allows customizing the input autosuggest UI.
+
+It receives the following props:
+
+- term – suggested term
+
+**example**
 ```
  searchstax.addSearchInputWidget("searchstax-input-container", {
     suggestAfterMinChars: 3,
@@ -317,13 +314,12 @@ example of input widget initialization with various options
 ```
 ### Location Widget ###
 
-Initialization properties
+SearchStax Site Search solution offers a native JS search-location widget to assist with your custom search page.
 
-a. id of container where widget will be rendered
+The SearchstaxLocationWidget provides a location search input with location-based search functionality.
 
-b. Input widget config object of type: [ISearchstaxLocationConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-search-results-interfaces)
+**Usage**
 
-example of results widget initialization with minimum options
 ```
 function locationDecodeFunction(term: string): Promise<ISearchstaxLocation>{
         return new Promise((resolve) => {
@@ -355,7 +351,24 @@ function locationDecodeFunction(term: string): Promise<ISearchstaxLocation>{
     },
 });
 ```
-example of result widget initialization with various options
+
+**Props**
+
+- hooks.locationDecode - callback function to override location decoding
+- hooks.locationDecodeCoordinatesToAddress - callback function to override location decoding
+
+**Template Override**
+
+The templates prop allows customizing the location input UI.
+
+It receives the following props:
+
+- locationSearchDistanceValues – location distance values
+- shouldShowLocationDistanceDropdown – boolean determining if distance dropdown should be shown
+
+
+**Example**
+
 ```
 searchstax.addSearchLocationWidget("searchstax-location-container", {
   templates:{
@@ -389,27 +402,72 @@ searchstax.addSearchLocationWidget("searchstax-location-container", {
   },
 });
 ```
+
 ### Result Widget ###
-Initialization properties
 
-a. id of container where widget will be rendered
+The SearchStax Site Search solution’s Results Widget for UX-JS displays the search results.
 
-b. Result widget config object of type: [ISearchstaxSearchResultsConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-search-results-interfaces)
+**Usage**
 
-example of results widget initialization with minimum options
 ```
 searchstax.addSearchResultsWidget("searchstax-results-container", {});
 ```
 
-example of result widget initialization with various options
+**Main Template Override**
+
+The template prop allows customizing the result UI.
+
+It receives no props:
+
+**Search Result Template Override**
+
+The template prop allows customizing the result UI.
+
+It receives following props:
+
+- custom?: any - custom properties that may be added through aftersearchHook
+- ribbon: string | null
+- paths: string | null;
+- url: string | null;
+- title: string | null;
+- titleTracking: string | null;
+- promoted: boolean | null;
+- thumbnail: string | null;
+- date: string | null;
+- snippet: string | null;
+- description: string | null;
+- uniqueId: string;
+- position: number;
+- distance: number | null;
+- unit: string | null;
+- unmappedFields: {
+   key: string;
+   value: string | string[] | boolean;
+   isImage?: boolean;
+ }[] - fields that were not mapped.
+- allFields: { key: string; value: string | string[] | boolean }[] - all fields
+
+**No Results Template Override**
+
+The template prop allows customizing the result UI.
+
+It receives following props:
+
+- spellingSuggestion - suggestion of corrected spelling
+- searchExecuted - boolean if search was executed
+- searchTerm - term that was searched
+
+**Example of default render method**
 ```
  searchstax.addSearchResultsWidget("searchstax-results-container", {
     templates: {
       mainTemplate: {
       template: `
-    <div class="searchstax-search-results-container" id="searchstax-search-results-container" data-test-id="searchstax-search-results-container">
-        <div class="searchstax-search-results" id="searchstax-search-results"></div>
-    </div>
+        <section aria-label="search results container" tabindex="0">
+            <div class="searchstax-search-results-container" id="searchstax-search-results-container" data-test-id="searchstax-search-results-container">
+                <div class="searchstax-search-results" id="searchstax-search-results"></div>
+            </div>
+        </section>
             `,
         searchResultsContainerId: "searchstax-search-results",
       },
@@ -499,15 +557,17 @@ example of result widget initialization with various options
   });
 ```
 
-example of result widget initialization with infinite scroll enabled. This will render pagination widget with infiniteScrollTemplate
+**Example of infinite scroll render method**
 ```
  searchstax.addSearchResultsWidget("searchstax-results-container", {
     templates: {
       mainTemplate: {
       template: `
-    <div class="searchstax-search-results-container" id="searchstax-search-results-container" data-test-id="searchstax-search-results-container">
-        <div class="searchstax-search-results" id="searchstax-search-results"></div>
-    </div>
+        <section aria-label="search results container" tabindex="0">
+            <div class="searchstax-search-results-container" id="searchstax-search-results-container" data-test-id="searchstax-search-results-container">
+                <div class="searchstax-search-results" id="searchstax-search-results"></div>
+            </div>
+        </section>
             `,
         searchResultsContainerId: "searchstax-search-results",
       },
@@ -599,18 +659,50 @@ example of result widget initialization with infinite scroll enabled. This will
 ```
 
 ### Pagination Widget ###
-Initialization properties
 
-a. id of container where widget will be rendered
+The SearchStax Site Search solution’s Pagination Widget displays a pagination control for UX-JS.
 
-b. Pagination widget config object of type: [ISearchstaxSearchPaginationConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-pagination-interfaces)
+**Usage**
 
-example of pagination widget initialization with minimum options
 ```
 searchstax.addPaginationWidget("searchstax-pagination-container", {});
 ```
 
-example of pagination widget initialization with various options
+**Multiple Instances**
+
+Multiple instances of the Pagination widget can be added by calling the addPaginationWidget method multiple times with different target containers:
+
+```
+searchstax.addPaginationWidget('container1', options1);
+
+searchstax.addPaginationWidget('container2', options2);
+
+```
+
+Each instance can be configured separately via its options object. This allows for the widget to be added to different locations on the page as needed.
+
+
+
+**Main Template Override**
+
+Main template for the pagination controls.
+
+It receives following props:
+
+- nextPageLink - link of next page;
+- previousPageLink - link of previous page;
+
+
+**Infinite Scroll Template Override**
+
+Main template for the pagination controls in infinite scroll mode.
+
+It receives following props:
+- isLastPage - boolean, true if its last page
+- results - results.length can be used if there are results
+
+**Example**
+
 ```
  searchstax.addPaginationWidget("searchstax-pagination-container", {
     templates: {
@@ -652,13 +744,15 @@ example of pagination widget initialization with various options
 ```
 
 ### Facets Widget ###
-Initialization properties
 
-a. id of container where widget will be rendered
+The SearchStax Site Search solution’s Facets Widget for UX-JS displays faceted filters for search.
+
+**Facet Selection and Order**
+
+Facet lists are configured and ordered on the Site Search [Faceting Tab](https://www.searchstax.com/docs/searchstudio/faceting-tab/).
 
-b. Facets widget config object of type: [ISearchstaxSearchFacetsConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-facets-interfaces)
+**Usage**
 
-example of facets widget initialization with minimum options
 ```
  searchstax.addFacetsWidget("searchstax-facets-container", {
     facetingType: "and",
@@ -667,8 +761,94 @@ example of facets widget initialization with minimum options
  });
 ```
 
+**Multiple Instances**
+
+Multiple instances of the Facets widget can be added by calling the addFacetsWidget method multiple times with different target containers:
+
+```
+searchstax.addFacetsWidget('container1', options1);
+
+searchstax.addFacetsWidget('container2', options2);
 
-example of facets widget initialization with various options
+```
+
+Each instance can be configured separately via its options object. This allows for the widget to be added to different locations on the page as needed.
+
+
+**Props**
+
+- facetingType: "and" | "or" | "showUnavailable" | "tabs"; // type that determines how facets will behave
+- specificFacets?: string[]; // optional array of facet names that if provided will only render those facets
+- itemsPerPageDesktop: number; // default expanded facets for desktop
+- itemsPerPageMobile: number; // default expanded facets for mobile
+- templates - see examples below
+
+
+**Main Template Desktop Override**
+
+Main wrapper template for desktop facets display.
+
+It receives following props from [IFacetsTemplateData](https://www.searchstax.com/docs/searchstudio/interfaces/#h-facets-interfaces)
+
+
+**Main Template Mobile Override**
+
+Main wrapper template for mobile facets display.
+
+It receives following props from [IFacetsTemplateData](https://www.searchstax.com/docs/searchstudio/interfaces/#h-facets-interfaces)
+
+**Show More Button Container Override**
+
+Template for show more button
+
+It receives following props:
+
+- showingAllFacets - boolean true if showing all facets
+
+**Facet Item Container Template Override**
+
+Template for facet item container.
+
+It receives following props:
+
+- label - label of facet
+
+
+**Clear Facets Template Override**
+
+Template for clear facets.
+
+It receives following props:
+
+- shouldShow - boolean, true if it should be displayed
+
+**Facet Item Template Override**
+
+Template for facet item.
+
+It receives following props:
+
+- disabled - boolean, true if disabled
+- isChecked - boolean, true if checked
+- value - string, value of facet
+- count - number of items for that facet
+
+**Filter By Template Override**
+
+Template for filter by.
+
+It receives no props
+
+**Selected Facets Template Override**
+
+Template for selected facets.
+
+It receives following props:
+
+- value - string, value of facet
+- count - number of items for that facet
+
+**Example**
 ```
  searchstax.addFacetsWidget("searchstax-facets-container", {
     facetingType: "and",
@@ -776,20 +956,44 @@ example of facets widget initialization with various options
 ```
 
 ### SearchFeedback Widget ###
-Initialization properties
 
-a. id of container where widget will be rendered
+The SearchStax Site Search solution’s Feedback Widget displays search feedback and stats for UX-JS.
 
-b. SearchFeedback widget config object of type: [ISearchstaxSearchFeedbackConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-search-feedback-interfaces)
+**Usage**
 
-
-example of search feedback widget initialization with minimum options
 ```
 searchstax.addSearchFeedbackWidget("search-feedback-container", {});
 ```
 
+**Multiple Instances**
+
+Multiple instances of the SearchFeedback widget can be added by calling the addSearchFeedbackWidget method multiple times with different target containers:
+
+```
+searchstax.addSearchFeedbackWidget('container1', options1);
+
+searchstax.addSearchFeedbackWidget('container2', options2);
+
+```
+
+Each instance can be configured separately via its options object. This allows for the widget to be added to different locations on the page as needed.
+
+
+**Main Template Override**
+
+Main template for the search feedback message.
+
+It receives following props:
+- searchExecuted - boolean, true if search was executed
+- hasResults - boolean, true if search has results
+- startResultIndex - number, start of page results
+- endResultIndex - number, end of page results
+- totalResults - number, total results
+- searchTerm - term that was searched
+- autoCorrectedQuery - query that search was autocorrected to
+- originalQuery - original query
 
-example of search feedback widget initialization with various options
+**Example**
 ```
 searchstax.addSearchFeedbackWidget("search-feedback-container", {
     templates: {
@@ -815,15 +1019,11 @@ searchstax.addSearchFeedbackWidget("search-feedback-container", {
   });
 ```
 
-## RelatedSearches widget
-Initialization properties
+### RelatedSearches widget ###
 
-a. id of container where widget will be rendered
+The SearchStax Site Search solution’s Related Searches Widget displays related searches for UX-JS.
 
-b. RelatedSearches widget config object of type: [ISearchstaxRelatedSearchesConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-related-searches-interfaces)
-
-
-example of search feedback widget initialization with minimum options
+**Usage**
 ```
   searchstax.addRelatedSearchesWidget("searchstax-related-searches-container", {
      relatedSearchesURL: "URL",
@@ -831,8 +1031,27 @@ example of search feedback widget initialization with minimum options
   })
 ```
 
+**Main Template Override**
+
+Main template for related searches.
+
+It receives following props:
+
+- hasRelatedSearches - boolean, true if has related searches
+- relatedSearches - array of related searches
+
+
+**Related Search Template Override**
+
+Related Search template.
+
+It receives following props:
+
+- related_search - string, related searc
+- last - boolean, true if last related search
+
+**Example**
 
-example of search feedback widget initialization with various options
 ```
 searchstax.addRelatedSearchesWidget("searchstax-related-searches-container", {
      relatedSearchesURL: "URL",
@@ -866,20 +1085,35 @@ searchstax.addRelatedSearchesWidget("searchstax-related-searches-container", {
 ```
 
 ### ExternalPromotions widget ###
-Initialization properties
-
-a. id of container where widget will be rendered
 
-b. ExternalPromotions widget config object of type: [ISearchstaxExternalPromotionsConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#:~:text=%7D-,export%20interface%20IExternalPromotion%20%7B,%7D,-export%20interface%20ISearchstaxMetadata)
+SearchStax Site Search solution’s External Promotions Widget displays external promotions for UX-JS.
 
+**Usage**
 
-example of search feedback widget initialization with minimum options
 ```
   searchstax.addExternalPromotionsWidget("searchstax-external-promotions-layout-container", {})
 ```
 
+**Main Template Override**
 
-example of search feedback widget initialization with various options
+Main template for external promotions.
+
+It receives following props:
+
+- hasExternalPromotions - boolean, true if has external promotions
+
+**External promotion Template Override**
+
+Template for external promotion item.
+
+It receives following props:
+
+- url - url of external promotion
+- uniqueId - unique id
+- name - name of promotion
+- description - description
+
+**Example**
 ```
 searchstax.addExternalPromotionsWidget("searchstax-external-promotions-layout-container",  {
     templates: {
@@ -922,20 +1156,27 @@ searchstax.addExternalPromotionsWidget("searchstax-external-promotions-layout-co
 
 
 ### Sorting Widget ###
-Initialization properties
-
-a. id of container where widget will be rendered
 
-b. Sorting widget config object of type: [ISearchstaxSearchSortingConfig](https://www.searchstax.com/docs/searchstudio/interfaces/#h-sorting-interfaces)
+The SearchStax Site Search solution’s Sorting Widget allows sorting of search results for UX-JS.
 
+**Usage**
 
-example of sorting widget initialization with minimum options
 ```
   searchstax.addSearchSortingWidget("search-sorting-container", {});
 ```
 
+**Main Template Override**
+
+Main template for sorting widget.
+
+It receives following props:
+
+- searchExecuted - boolean, true if search was executed
+- hasResultsOrExternalPromotions - boolean, true if there are results or external promotions
+- sortOptions - array of sort options, has key/value
+
+**Example**
 
-example of sorting widget initialization with various options
 ```
 searchstax.addSearchSortingWidget("search-sorting-container", {
     templates: {