@searchstax-inc/searchstudio-ux-js 0.0.9 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change Log
+
+All notable changes to the "vite-vanilla-ts-lib-starter" project will be documented in this file.
+
+## [0.0.1] - 2023-01-18
+
+- Update all packages to the latest versions (update to vite 4.x)
+
+## [0.0.1] - 2022-09-08
+
+- Update all packages to the latest versions (update to vite 3.x)
+
+## [0.0.0] - 2022-03-28
+
+- Initial release

package/README.md

@@ -59,6 +59,32 @@ searchstax.initialize({
   });
 ```
 
+## Initial layout
+Our base theme is designed with this layout in mind but it is optional as all widgets have id parameters and can be attached to any element.
+```
+<div class="searchstax-page-layout-container">
+      <div id="searchstax-input-container"></div>
+
+      <div class="search-details-container">
+        <div id="search-feedback-container"></div>
+        <div id="search-sorting-container"></div>
+      </div>
+
+      <div class="searchstax-page-layout-facet-result-container">
+        <div class="searchstax-page-layout-facet-container">
+          <div id="searchstax-facets-container"></div>
+        </div>
+
+        <div class="searchstax-page-layout-result-container">
+          <div id="searchstax-external-promotions-layout-container"></div>
+          <div id="searchstax-results-container"></div>
+          <div id="searchstax-related-searches-container"></div>
+          <div id="searchstax-pagination-container"></div>
+        </div>
+      </div>
+</div>
+```
+
 ## Input widget
 Initialization properties
 
@@ -70,17 +96,19 @@ b. {
 
   `templates?: {` - optional object that defines template override options
 
-    `mainTemplate?: string;` - main template in Mustache templating language
-
-    `searchInputId?: string;` - id of search input within the mainTemplate
-
-    `autosuggestItemTemplate?: string;` - autosuggest item template in Mustache
+    `mainTemplate?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `searchInputId: string;` - id of search input within the mainTemplate
+    `};`
 
+    `autosuggestItemTemplate?: {` - autosuggest item template in Mustache
+      `template: string;` - autosuggest template in Mustache templating language
+    `};`
   `};`
 
   `hooks?: {` - optional object that provides various hook options
 
-    `beforeSearch?: (props: ISearchstaxSearchProps) => ISearchstaxSearchProps | null;` - this function gets called before firing search. searchProps 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.
+    `beforeSearch?: (props: ISearchObject) => ISearchObject | null;` - this function gets called before firing search. searchProps 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.
 
     `afterSearch?: (results: ISearchstaxParsedResult[]) => ISearchstaxParsedResult[];` - this function gets called after firing search and before rendering. It needs to return array of results that are either modified or untouched.
 
@@ -93,12 +121,20 @@ b. {
 }
 
 
+example of input widget initialization with minimum options
+```
+searchstax.addSearchInputWidget("searchstax-input-container", {
+    suggestAfterMinChars: 3,
+ });
+```
+
+
 example of input widget initialization with various options
 ```
  searchstax.addSearchInputWidget("searchstax-input-container", {
     suggestAfterMinChars: 3,
     hooks: {
-      beforeSearch: function (props: ISearchstaxSearchProps) {
+      beforeSearch: function (props: ISearchObject) {
         const propsCopy = { ...props };
         return propsCopy;
       },
@@ -109,7 +145,6 @@ example of input widget initialization with various options
       },
       afterAutosuggest: function (result: ISearchstaxSuggestResponse) {
         const copy = { ...result };
-        console.log("copy", copy);
         return copy;
       },
       beforeAutosuggest: function (props: ISearchstaxSuggestProps) {
@@ -121,14 +156,22 @@ example of input widget initialization with various options
       },
     },
     templates: {
-    mainTemplate: `<div class="searchstax-search-input-container">
-    <div class="searchstax-search-input-wrapper">
-      <input type="text" id="searchstax-search-input" class="searchstax-search-input" placeholder="SEARCH FOR..." />
-      <button class="searchstax-spinner-icon" id="searchstax-search-input-action-button"></button>
-    </div>
-    </div>`,
-    searchInputId: "searchstax-input-container",
-    autosuggestItemTemplate: `<div class="searchstax-autosuggest-item-term-container">{{{term}}}</div>`,
+    mainTemplate: {
+        template: `
+        <div class="searchstax-search-input-container">
+            <div class="searchstax-search-input-wrapper">
+                <input type="text" id="searchstax-search-input" class="searchstax-search-input" placeholder="SEARCH FOR..." />
+                <button class="searchstax-spinner-icon" id="searchstax-search-input-action-button"></button>
+            </div>
+        </div>
+        `,
+        searchInputId: "searchstax-search-input"
+    }
+    autosuggestItemTemplate: {
+        template: `
+        <div class="searchstax-autosuggest-item-term-container">{{{term}}}</div>
+        `,
+    }
     },
   });
 ```
@@ -139,17 +182,23 @@ a. id of container where widget will be rendered
 
 b. {
 
-  `searchResultsContainerId?: string;` - this is needed only if mainTemplate is overridden. It points to an element in the template where results need to be rendered
-
-  `searchResultUniqueIdAttribute?: string;` - this is needed only if searchResultTemplate is overridden. searchResultTemplate needs to have unique result id property. Default is data-searchstax-unique-result-id="{{uniqueId}}". see example below on how it is used
+  `searchResultUniqueIdAttribute?: string;` - this is needed only if searchResultTemplate is overridden. searchResultTemplate needs to have unique result id property. Default is data-searchstax-unique-result-id="uniqueId". see example below on how it is used
 
   `templates?: {` - optional object that defines template override options
 
-    `mainTemplate?: string;` - main template in Mustache templating language.
+    `mainTemplate?: {`
+        template: string; - main template in Mustache templating language.,
+        searchResultsContainerId: string;` - this is needed only if mainTemplate is overridden. It points to an element in the template where results need to be rendered
+    }
 
-    `searchResultTemplate?: string;` - result template using Mustache. ISearchstaxParsedResult is passed to the template and all its properties are available to be used when rendering
+    `searchResultTemplate?: {`
+        template: string - result template using Mustache. ISearchstaxParsedResult is passed to the template and all its properties are available to be used when rendering;
+        searchResultUniqueIdAttribute?: string - this is needed only if searchResultTemplate is overridden. searchResultTemplate needs to have unique result id property. Default is data-searchstax-unique-result-id="niqueId". see example below on how it is used
+    }
 
-    `noSearchResultTemplate?: string;` - Mustache template for no results section override. spellingSuggestion and searchTerm are values available in the template
+    `noSearchResultTemplate?: {`
+        template: string - Mustache template for no results section override. spellingSuggestion and searchTerm are values available in the template
+    }
 
   `};`
 
@@ -160,57 +209,90 @@ b. {
   `};`
 }
 
+example of results widget initialization with minimum options
+```
+searchstax.addSearchResultsWidget("searchstax-results-container", {});
+```
+
 example of result widget initialization with various options
 ```
  searchstax.addSearchResultsWidget("searchstax-results-container", {
-    // searchResultUniqueIdAttribute: ' data-searchstax-unique-result-id', if custom result template is used
-    // points to an attribute that will be used to identify a result
-    searchResultsContainerId: "searchstax-result-container", // if main template is over ridden this points to an
-    // id in the main element where results need to be rendered
     templates: {
-      mainTemplate: `
-          <div class="searchstax-search-results-container">
-            <div id="searchstax-result-container"></div>
-          </div>
-               `,
-      searchResultTemplate: `<div class="searchstax-search-result">
-      {{#url}}
-      <a href="{{url}}" data-searchstax-unique-result-id="{{uniqueId}}" class="searchstax-result-item-link"></a>
-      {{/url}}
-      {{#ribbon}}
-      <div class="searchstax-search-result-ribbon">
-        {{ribbon}}
-      </div>
-      {{/ribbon}}
-      {{#thumbnail}}
-        <img :src="thumbnail" class="searchstax-thumbnail">
-      {{/thumbnail}}
-      <div class="searchstax-search-result-title-container">
-        <span class="searchstax-search-result-title">{{title}}</span>
-      </div>
-      {{#paths}}
-        <p class="searchstax-search-result-common">
-          {{paths}}
-        </p>
-      {{/paths}}
-      {{#description}}
-      <p class="searchstax-search-result-description searchstax-search-result-common">
-        {{description}}
-      </p>
-      {{/description}}
-      {{#unmappedFields}}
-        {{#isImage}}
-          <div class="searchstax-search-result-image-container">
-            <img :src="result[value]" class="searchstax-result-image">
-          </div>
-        {{/isImage}}
-        {{^isImage}}
-          <p class="searchstax-search-result-common">
-            {{value}}
-          </p>
-        {{/isImage}}
-      {{/unmappedFields}}
-      </div>`,
+      mainTemplate: {
+      template: `
+            <div class="searchstax-search-results-container">
+                <div class="searchstax-search-results" id="searchstax-search-results"></div>
+            </div>
+            `,
+        searchResultsContainerId: "searchstax-search-results",
+      },
+      searchResultTemplate: {
+        template: `
+            <div class="searchstax-search-result {{#thumbnail}} has-thumbnail {{/thumbnail}}">
+                {{#promoted}}
+                    <div class="searchstax-search-result-promoted"></div>
+                {{/promoted}}
+
+                {{#url}}
+                    <a href="{{url}}" data-searchstax-unique-result-id="{{uniqueId}}" class="searchstax-result-item-link"></a>
+                {{/url}}
+
+                {{#ribbon}}
+                    <div class="searchstax-search-result-ribbon">
+                    {{ribbon}}
+                    </div>
+                {{/ribbon}}
+
+                {{#thumbnail}}
+                    <img src="{{thumbnail}}" class="searchstax-thumbnail">
+                {{/thumbnail}}
+                <div class="searchstax-search-result-title-container">
+                    <span class="searchstax-search-result-title">{{title}}</span>
+                </div>
+
+                {{#paths}}
+                    <p class="searchstax-search-result-common">
+                        {{paths}}
+                    </p>
+                {{/paths}}
+
+                {{#description}}
+                    <p class="searchstax-search-result-description searchstax-search-result-common">
+                        {{description}}
+                    </p>
+                {{/description}}
+
+                {{#unmappedFields}}
+                    {{#isImage}}
+                        <div class="searchstax-search-result-image-container">
+                        <img src="{{value}}" class="searchstax-result-image">
+                        </div>
+                    {{/isImage}}
+                    {{^isImage}}
+                        <p class="searchstax-search-result-common">
+                        {{value}}
+                        </p>
+                    {{/isImage}}
+                {{/unmappedFields}}
+            </div>
+            `,
+        searchResultUniqueIdAttribute: "data-searchstax-unique-result-id"
+      },
+      noSearchResultTemplate: {
+        template: `
+            <div class="searchstax-no-results">
+                Showing <strong>no results</strong> for <strong>"{{ searchTerm }}"</strong>
+                <br>
+                {{#spellingSuggestion}}
+                    <span>&nbsp;Did you mean <a href="#" class="searchstax-suggestion-term">{{ spellingSuggestion }}</a>?</span>
+                {{/spellingSuggestion}}
+            </div>
+            <div>
+                <p>Try searching for search related terms or topics. We offer a wide variety of content to help you get the information you need.</p>
+                <p>Lost? Click on the ‘X” in the Search Box to reset your search.</p>
+            </div>
+            `
+      }
     },
     hooks: {
       afterLinkClick: function (result: ISearchstaxParsedResult) {
@@ -223,6 +305,235 @@ example of result widget initialization with various options
   });
 ```
 
+## Pagination widget
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+  `templates?: {` - optional object that defines template override options
+
+    `mainTemplate?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `previousButtonClass: string;` - class of previous page link within template,
+        `nextButtonClass: string;` - class of next page link within template,
+    `};`
+  `};`
+
+}
+
+example of pagination widget initialization with minimum options
+```
+searchstax.addPaginationWidget("searchstax-pagination-container", {});
+```
+
+example of pagination widget initialization with various options
+```
+ searchstax.addPaginationWidget("searchstax-pagination-container", {
+    templates: {
+        mainTemplate: {
+            template: `
+      {{#results.length}}
+        <div class="searchstax-pagination-container">
+          <div class="searchstax-pagination-content">
+            <a class="searchstax-pagination-previous {{#isFirstPage}}disabled{{/isFirstPage}}" id="searchstax-pagination-previous">< Previous</a>
+            <div class="searchstax-pagination-details">
+              {{startResultIndex}} - {{endResultIndex}} of {{totalResults}}
+            </div>
+              <a class="searchstax-pagination-next {{#isLastPage}}disabled{{/isLastPage}}" id="searchstax-pagination-next">Next ></a>
+          </div>
+        </div>
+      {{/results.length}}
+      `,
+            previousButtonClass: "searchstax-pagination-previous",
+            nextButtonClass: "searchstax-pagination-next"
+        }
+    },
+  });
+```
+
+## Facets widget
+Initialization properties
+
+a. id of container where widget will be rendered
+
+b. {
+
+   `facetingType`: "and" | "or" | "showUnavailable" - type that determines how facets will behave,
+
+   `itemsPerPageDesktop`: number - default expanded facets for desktop,
+
+   `itemsPerPageMobile`: number - default expanded facets for mobile,
+
+  `templates?: {` - optional object that defines template override options
+
+    `mainTemplateDesktop?: {` - optional object for overriding main template
+        `template: string;` - main template in Mustache templating language
+        `facetsContainerClass: string;` - class of container where facets will be placed
+    `},`
+
+    `mainTemplateMobile?: {` - optional object for overriding main mobile template
+        `template: string;` - main template in Mustache templating language
+        `facetsContainerId: string;` - id of container where facets will be placed
+        `closeOverlayTriggerClasses: string[];` - class list of all elements that should trigger mobile overlay close action
+        `filterByContainerId: string` - id of container where "Filter By" button will be rendered
+        'selectedFacetsContainerId: string' - id of container where selected facets will be listed
+    `},`
+
+    `showMoreButtonContainerTemplate?: {` - optional object for overriding facet section show more/less template
+        `template: string;` - main template in Mustache templating language
+        `showMoreButtonClass: string;` - class of container where show more/less button will be placed
+    `},`
+
+    `facetItemContainerTemplate?: {` - optional object for overriding facet container template
+        `template: string;` - main template in Mustache templating language
+        'facetListTitleContainerClass: string;' - container class where facet category title will be rendered within template
+        `facetListContainerClass: string;` - container class where facet items will be listed
+       `},`
+
+      `clearFacetsTemplate?: {` - optional object for overriding clear facets container template
+        `template: string;` - main template in Mustache templating language
+        'containerId: string;' - container id where clear facets button will be rendered
+       `},`
+
+      `facetItemTemplate?: {` - optional object for overriding clear facet item template
+        `template: string;` - main template in Mustache templating language
+        'inputCheckboxClass: string;' - class of checkboxes
+        'checkTriggerClasses: string[];' - class list of elements that trigger facet select/unselect action
+       `},`
+
+       `filterByTemplate?: {` - optional object for overriding filter by button template
+        `template: string;` - main template in Mustache templating language
+        'containerId: string;' - id where button will be placed within the template
+       `},`
+
+       `selectedFacetsTemplate?: {` - optional object for overriding selected facets template
+        `template: string;` - main template in Mustache templating language
+        'containerId: string;' - id where selected facets will be placed within the template
+       `},`
+  `};`
+
+}
+
+example of facets widget initialization with minimum options
+```
+ searchstax.addFacetsWidget("searchstax-facets-container", {
+    facetingType: "and",
+    itemsPerPageDesktop: 3,
+    itemsPerPageMobile: 99,
+ });
+```
+
+
+example of facets widget initialization with various options
+```
+ searchstax.addFacetsWidget("searchstax-facets-container", {
+    facetingType: "and",
+    itemsPerPageDesktop: 3,
+    itemsPerPageMobile: 99,
+    templates: {
+        mainTemplateDesktop: {
+            template: `
+      {{#hasResultsOrExternalPromotions}}
+        <div class="searchstax-facets-container-desktop"></div>
+      {{/hasResultsOrExternalPromotions}}
+      `,
+            facetsContainerId: "",
+        },
+        mainTemplateMobile: {
+            template: `
+        <div class="searchstax-facets-pills-container">
+          <div class="searchstax-facets-pills-selected">
+          </div>
+        </div>
+
+        <div class="searchstax-facets-mobile-overlay {{#overlayOpened}} searchstax-show{{/overlayOpened}}" >
+          <div class="searchstax-facets-mobile-overlay-header">
+            <div class="searchstax-facets-mobile-overlay-header-title">Filter By</div>
+            <div class="searchstax-search-close"></div>
+          </div>
+          <div class="searchstax-facets-container-mobile"></div>
+          <button class="searchstax-facets-mobile-overlay-done">Done</button>
+        </div>
+      </div>
+      `,
+            facetsContainerId: ``,
+            closeOverlayTriggerClasses: ["searchstax-facets-mobile-overlay-done","searchstax-search-close",],
+            filterByContainerId: ``,
+            selectedFacetsContainerId: ``,
+        },
+        showMoreButtonContainerTemplate: {
+            template: `
+      <div class="searchstax-facet-show-more-container">
+      {{#showingAllFacets}}
+        <div class="searchstax-facet-show-less-button searchstax-facet-show-button">less</div>
+      {{/showingAllFacets}}
+      {{^showingAllFacets}}
+        <div class="searchstax-facet-show-more-button  searchstax-facet-show-button">more {{onShowMoreLessClick}}</div>
+      {{/showingAllFacets}}
+    </div>
+      `,
+            showMoreButtonClass: `searchstax-facet-show-more-container`,
+        },
+        facetItemContainerTemplate: {
+            template: `
+      <div>
+        <div class="searchstax-facet-title-container">
+            <div class="searchstax-facet-title">
+            {{label}}
+            </div>
+            <div class="searchstax-facet-title-arrow active"></div>
+        </div>
+        <div class="searchstax-facet-values-container"></div>
+      </div>
+      `,
+            facetListTitleContainerClass: `searchstax-facet-title-container`,
+            facetListContainerClass: `searchstax-facet-values-container`,
+        },
+        clearFacetsTemplate: {
+            template: `
+      {{#shouldShow}}}
+        <div class="searchstax-facets-pill searchstax-clear-filters searchstax-facets-pill-clear-all">
+        <div class="searchstax-facets-pill-label">Clear Filters</div>
+        </div>
+      {{/shouldShow}}
+      `,
+            containerId: ``,
+        },
+        facetItemTemplate: {
+            template: `
+      <div class="searchstax-facet-input">
+        <input type="checkbox" class="searchstax-facet-input-checkbox" {{#disabled}}disabled{{/disabled}} {{#isChecked}}checked{{/isChecked}}/>
+      </div>
+      <div class="searchstax-facet-value-label">{{value}}</div>
+      <div class="searchstax-facet-value-count">({{count}})</div>
+      `,
+            inputCheckboxClass: `searchstax-facet-input-checkbox`,
+            checkTriggerClasses: ["searchstax-facet-value-label","searchstax-facet-value-count",],
+        },
+        filterByTemplate: {
+            template: `
+      <div class="searchstax-facets-pill searchstax-facets-pill-filter-by">
+        <div class="searchstax-facets-pill-label">Filter By</div>
+      </div>
+      `,
+            containerId: ``,
+        },
+        selectedFacetsTemplate: {
+            template: `
+      <div class="searchstax-facets-pill searchstax-facets-pill-facets">
+        <div class="searchstax-facets-pill-label">{{value}} ({{count}})</div>
+        <div class="searchstax-facets-pill-icon-close"></div>
+      </div>
+      `,
+            containerId: ``,
+        },
+
+    },
+  });
+```
+
 ## Template overrides
 Templates use mustache templating. For more info see https://github.com/janl/mustache.js