@empathyco/x-components 3.0.0-alpha.27 → 3.0.0-alpha.271

package/docs/experience-search-and-discovery/my-history.md

@@ -0,0 +1,50 @@
+---
+title: My History UI
+---
+
+The My History UI component displays the complete list of history queries, allowing shoppers to reuse previously searched queries.  
+
+![My History](~@assets/media/features/overview-my-history.svg)
+
+::: interact
+
+Can't quite capture the concept? Learn more about [My History](/explore-empathy-platform/features/my-history-overview.md). 
+
+:::
+
+From the frontend perspective, My History is a UI component that specifically manages the display of a list of history search suggestions. To display a dashboard featuring shoppers' data privacy and control, My History is combined with other UI elements and components, such as a toggle switch for shoppers to enable or disable search history.
+
+::: note Search data storage
+
+To show the complete list of history queries, My History component uses the history records saved on the shopper’s browser local history. See [Interface X data privacy and browser local storage](/explore-empathy-platform/experience-search-and-discovery/web-local-storage.md) to check out the information stored locally on the shopper’s device.
+
+:::
+
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer.
+- Layout the list of history queries as you want. 
+- Customize date and time format.
+- Animate the display of My History dashboard at your ease.
+- Customize content. Show whatever you need: text, images, icons...
+
+::: note
+
+Configuration options here only apply to tailor the My History component, which provides a way to display the full list of history queries. Other UI elements that comprise the My History feature can be configured as well. Check a complete list of UI components in the [Interface X Components UI Reference](/develop-empathy-platform/ui-reference/).
+
+:::
+
+::: interact  
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/history-queries/x-components.my-history) your search history experience.  
+
+:::
+
+<!--Include link to twitch session here: Watch how XXX uses the My History UI component in a real project. -->
+
+
+
+
+
+

package/docs/experience-search-and-discovery/next-queries.md

@@ -0,0 +1,67 @@
+---
+title: Next Queries UI
+tags:
+  - popular next queries
+  - what's next
+---
+
+The Next Queries UI component provides shoppers with ideas on what to search for next based on their
+last search. Since next queries are related to the last query, they appear after performing a first
+search.
+
+![Next Queries](~@assets/media/interface/x-next-queries.gif)
+
+Next queries can be **organic**, using information on the most common searches that are performed
+successively or within a same session by shoppers, or **curated**, created manually by the
+merchandiser in the Empathy Platform Playboard.
+
+::: warning
+
+Organic next queries are generated using collective shopper behavior to identify query pairs that
+have been used together. For a correct performance, make sure that your current search service
+supports this feature.
+
+:::
+
+::: interact
+
+Can't quite capture the concept? Learn about [Next Queries](../features/next-queries-overview.md).
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer, although next queries usually display
+  below the search bar after the initial search.
+- Show as many next queries as you want.
+- Animate the display of next queries at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+- Display curated next queries differently to organic next queries.
+
+::: interact
+
+Want to know more? Learn how to
+[configure](/develop-empathy-platform/ui-reference/components/next-queries) your web experience.
+
+:::
+
+::: design
+
+Read how Empathy UX designer, Marlety García, designed the Next Queries experience for one of our
+customers in the post
+[Popular Next Queries: Towards a conversational search](https://empathy.co/blog/popular-next-searches/).
+
+:::
+
+## Extend the performance
+
+You can combine Next Queries with the [History Queries](history-queries.md) component to display
+next queries that shoppers haven't already used in the session.
+
+::: warning
+
+To display only new next queries, the [History Queries](/explore-empathy-platform/features/history-queries-overview.md)
+feature must be implemented.
+
+:::
+

package/docs/experience-search-and-discovery/popular-searches.md

@@ -0,0 +1,47 @@
+---
+title: Popular Searches UI
+tags:
+  - top searches
+  - top terms
+  - search trends
+  - top queries
+  - trending
+---
+
+The Popular Searches UI component displays what are the top search queries during a specific time.
+This type of suggestion can show up even before shoppers have started entering a query or when there
+are no search results to show.
+
+![Popular Searches](~@assets/media/interface/x-popular-searches.gif)
+
+::: warning
+
+Popular Searches are generated using shopper behavior to determine the top searches for a given
+period. For a correct performance, make sure that your current search service supports this type of
+feature.
+
+:::
+
+::: interact
+
+Can't quite capture the concept? Learn about
+[Popular Searches](../features/popular-searches-overview.md).
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer. Combine it with the
+  [Empathize](empathize.md) container to display Popular Searches below the search bar on shopper
+  interaction.
+- Show as many popular search terms results as you want.
+- Animate the display of Popular Searches at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/popular-searches) your web
+experience.
+
+:::
+

package/docs/experience-search-and-discovery/product-results-ui.md

@@ -0,0 +1,81 @@
+---
+title: Product results UI
+tags:
+  - results layout
+---
+
+After launching a search, some shoppers may just want to take a quick look around, reviewing only
+product thumbnails and quick info on the SERP. While others will prefer to have a more detailed
+overview of the product results with large and multiple images. That’s why the display of results is
+really issue.
+
+Results are rendered thanks to the combination of different X Components. This way, you can
+tailor the display to create the best product discovery experience for your shoppers. Decide the
+elements and product-related information you want to include when displaying product results such as
+the price, a picture, or even an add-to-cart button.
+
+![X Components for results display](~@assets/media/features/overview-product-results-card.svg)
+
+<FootNote>
+
+**X&nbsp;Components for results display** <br/> (A) Image, (B) Product information, (C) Price, (D)
+PDP Link, (E) Rating, (F) Add to cart
+
+</FootNote>
+
+::: interact
+
+To learn more about the display of results, see
+[Product results](/explore-empathy-platform/overview/product-results-overview.md).
+
+:::
+
+**A bunch of components for comprehensive product information**  
+Decide whether you want to include
+the description for the resulting product, a picture, or even rating information:
+
+- **Image**. Include a picture of the product for better product recognition.&nbsp;(A)
+- **Result data and product variants**. Retrieve the information to display about the product –name,
+  description, reference, brand, category, season, colors, types, sizes, or any data from your
+  catalogue.&nbsp;(B)
+- **Pricing**. Indicate the original price of the product, discounts, and special prices.&nbsp;(C)
+- **Product details**. Link your shoppers to the product detail page (PDP).&nbsp;(D)
+- **Rating**. Show how valued a product is among your shoppers.&nbsp;(E)
+- **Add to cart**. Allow your shoppers to add a product to the cart from the search engine results
+  page (SERP), without going through the PDP.&nbsp;(F)
+
+:::warning
+
+To include rating and add-to-cart options in results, rating and add-to-cart features must be
+implemented in your product catalogue.
+
+:::
+
+## Tailor the web experience
+
+- Customize content. Choose and display the product-related information available in your catalogue.
+- Add a PDP link to the product name or description, the picture, or to the entire product result.
+- Format the price of products with integers and decimals. Decide the length of decimals or whether
+  decimals should be rendered or not.
+- Select the desired currency for prices.
+- Customize the default rendering behavior of pictures when loading or broken.
+- Animate the display of product results.
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/) your web
+experience.
+
+:::
+
+## Extend the performance
+
+Traditionally, search results are displayed on the SERP after the query is launched or instantly as
+you type. However, result data is also used by features such as
+[Recommendations](/explore-empathy-platform/experience-search-and-discovery/recommendations.md) and
+[ID Results](/explore-empathy-platform/experience-search-and-discovery/id-results.md). You can combine
+results-related components with these modules to get advanced display options. Include additional
+product information in Recommendations and Identifier Results such as prices and pictures for better
+recognition and understanding of the products displayed.
+
+

package/docs/experience-search-and-discovery/query-suggestions.md

@@ -0,0 +1,45 @@
+---
+title: Query Suggestions UI
+tags:
+  - search suggestions
+  - search as you type
+---
+
+The Query Suggestions UI component helps your shoppers with hints of what to look for to get
+relevant results. They complete and nail down the query as shoppers type without needing to keep
+typing.
+
+![Query Suggestions](~@assets/media/interface/x-query-suggestions.gif)
+
+::: warning
+
+Query Suggestions are generated using collective shopper behavior, extracting the keywords used on a
+specific query. For a correct performance, make sure that your current search service supports this
+type of feature.
+
+:::
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[Query Suggestions](../features/query-suggestions-overview.md).
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer. Combine it with the
+  [Empathize](empathize.md) container to display suggestions below the search bar on shopper
+  interaction.
+- Show as many suggestions as you want.
+- Animate the display of Query Suggestions at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/query-suggestions/) your web
+experience.
+
+:::
+
+

package/docs/experience-search-and-discovery/recommendations.md

@@ -0,0 +1,49 @@
+---
+title: Recommendations UI
+tags:
+  - top clicked
+  - top searched
+  - trending
+  - trending products
+  - top products
+  - popular
+---
+
+The Recommendations UI component shows the most clicked products on the SERP, based on shopper
+interaction within a defined period. They help your shoppers to explore your product catalogue,
+guiding them to specific products without the need to launch any queries.
+
+![Recommendations](~@assets/media/interface/x-recommendations.gif)
+
+::: warning
+
+Recommendations are generated using collective shopper behavior, generating a feed with the most
+clicked products. For a correct performance, make sure that your current search service supports
+this type of feature.
+
+:::
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[Recommendations](/explore-empathy-platform/features/recommendations-overview.md).
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer, although they usually appear on the
+  results page.
+- Show as many recommendations as you want.
+- Animate the display of the component at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+- Extend the performance with results-related components.
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/recommendations/x-components.recommendations.md) your web
+experience.
+
+:::
+
+

package/docs/experience-search-and-discovery/related-tags.md

@@ -0,0 +1,49 @@
+---
+title: Related Tags UI
+tags:
+  - tags
+  - related keywords
+---
+
+The Related Tags UI component helps your shoppers to refine a specific search query and find what
+they’re looking for with just one click. They only appear after the search process is completed, and
+the results appear to fine-tune the search with extra information and get highly relevant results.
+They are shown as labels usually at the top of the results page, but can be displayed anywhere
+instead.
+
+![Related Tags](~@assets/media/interface/x-related-tags.gif)
+
+::: warning
+
+Related Tags are generated using collective shopper behavior to identify associated terms used to
+refine a search query. For a correct performance, make sure that your current search service
+supports this type of feature.
+
+:::
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[Related Tags](../features/related-tags-overview.md).
+
+:::
+
+<!-- You can configure the behavior of Related Tags and decide whether they’re selectable or not. If Related Tags aren’t selectable, they modify the initial query syntax by adding the related-search keywords to the query term initially typed in the search bar. Otherwise, the initial query syntax will still remain so that shoppers can select or deselect Related Tags at their ease, exploring different options and combinations. -->
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer, although Related Tags usually appear
+  below the search bar after completing the search.
+- Show as many Related Tags as you want.
+- Animate the display of Related Tags at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+<!-- - Choose if Related Tags are selectable or change the syntax of the initial query in the search box. -->
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/related-tags/) your web
+experience.
+
+:::
+
+

package/docs/experience-search-and-discovery/search-box.md

@@ -0,0 +1,95 @@
+---
+title: Search Box UI
+tags: 
+  - search input
+  - search bar
+  - search field
+  - input
+---
+
+The Search Box UI Component is the main entry point for search where shoppers can type what
+they're looking for in your shop. It usually includes an input field, a search button, and a clear
+button.
+
+![Search box](~@assets/media/interface/x-search-box.svg)
+
+::: interact
+
+Can't quite capture the concept? Learn more about [Search Box](../overview/search-box-overview.md).
+
+:::
+
+It can be combined with other X Components, such as [Query Suggestions](query-suggestions.md)
+or [Next Queries](next-queries.md), to update the query according to shoppers’ intent or behaviour.
+For example, if a shopper selects a query suggestion, the query is instantly updated in the input
+field to the selected suggestion and the search is launched.
+
+::: warning
+
+To modify the query syntax using [Query Suggestions](../features/query-suggestions-overview.md) or
+[Next Queries](../features/next-queries-overview.md), make sure that your current search service
+supports this type of feature.
+
+:::
+
+## Power-up behavior
+
+Every component has a power-up behavior under the hood that is visible to the user but not glaringly
+obvious. For example, in Interface X Components for web, see what happens when:
+
+- _A query with results is **submitted**_:
+
+  - Results are displayed
+  - Related tags are displayed
+  - Next queries are displayed
+  - The query can be displayed in the History Queries or Query Suggestions lists upon configuration
+
+- _A query with results is **cleared** using the clear button_:
+
+  - Any text in the search input is cleared
+  - The results are cleared
+  - The query suggestions are cleared
+  - The next queries are not cleared
+  - The related tags are cleared
+  - The searched query is displayed in history queries
+
+- _Using **instant search and a query is being typed** that has results_:
+
+  - No results are displayed before debounce time
+  - Results are displayed after debounce time
+  - Next queries are displayed after debounce time
+  - Related tags are displayed after debounce time
+
+- _Using **instant search and modifying the initial query**_:
+  - No results related to the second query are displayed before debounce time
+  - Results related to the second query are displayed after debounce time
+  - Displayed results are different from the previous ones
+
+::: warning
+
+Deactivating instant search means History Queries are not updated until the search button or Enter
+key is pressed, since the typed query is not submitted until one of these two actions is performed.
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer.
+- Customize content. Allow shoppers to search or clear their search using text or icons.
+- Determine the number of characters shoppers can enter in the search input.
+- Autofocus the input field when the search box is displayed.
+- Auto-accept the query without the need of using a search button or the Enter key. Determine the
+  debounce time to wait before instant search.
+- Configure what will happen after the search is triggered; for example, display Related Tags or
+  Next Queries.
+
+<!-- TO BE PUBLISHED IN FUTURE ITERATIONS WHEN THE SEARCH BOX POWER-UP ARE IMPLEMENTED: * Automatically suggest search terms to guide shoppers in constructing their search query. * Prompt shoppers to start their search with animated custom hint messages. -->
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/components/search-box/) your web
+experience.
+
+:::
+
+

package/docs/experience-search-and-discovery/serp-ui.md

@@ -0,0 +1,123 @@
+---
+title: SERP UI
+tags:
+  - results layout
+  - grid
+  - results grid
+---
+
+To handle and display search results, the layout of results and other related discovery features is
+paramount. For example, how to arrange results on the SERP or the features shoppers expect to easily
+navigate and organize results are key points to have in mind. <br/>
+
+![X Components for results layout](~@assets/media/interface/x-results-layout.svg)
+
+<FootNote>
+
+**X&nbsp;Components for results layout** <br/> (A) Grid, (B) Number of results, (C) Column Picker,
+(D) Sorting, and (E) Scrolling
+
+</FootNote>
+<br/>
+
+**Choice of the layout view**  
+Your shoppers should be able to select how they’d like the products
+displayed and how the number of products they’d like to see per page, for example.
+
+That’s why the **grid** (A) is the core element of the SERP. It displays the results returned by the
+search service using a grid layout. Its value relies on having a configurable and flexible space to
+place all types of results or even other layout components such as a carousel visualization for
+[Next Queries](next-queries.md) or [Recommendations](recommendations.md).
+
+However, the grid is not the only element to consider when designing the SERP:
+
+- Show the **number of results** (B).
+- Allow your shoppers to select the **number of columns** (C) to showcase results.
+- Provide a **[sorting system](/explore-empathy-platform/overview/sorting-overview.md)** (D) so that
+  your shoppers can arrange results according to different criteria such as relevance, price,
+  alphabetical order…
+- Include **[pagination](/explore-empathy-platform/overview/pagination-overview.md)** options to
+  browse results throughout the different result pages available or apply infinite scroll to ease
+  navigation.
+- Apply **infinite scroll** to ease navigation and add a **scroll-to-top button** (E) to quickly
+  move to the top of the results page.
+- Indicate your shoppers whether the
+  **[Spell Check](/explore-empathy-platform/features/spellcheck-overview.md)** feature is applied or
+  not.
+
+::: note
+
+Enhance the search experience, adding [Related Tags](related-tags.md) to the SERP so that your
+shoppers can select descriptive keywords to refine the initial query and get highly relevant
+results.
+
+:::
+
+::: design
+
+As most shoppers don’t like to spend time scrolling and moving between pages, a crucial element on
+the SERP for a great experience is to offer **faceted search**, letting shoppers specify the kind of
+product attributes they’re interested in.
+
+:::
+
+::: interact
+
+To learn more about the SERP, results display, and their layout, see
+[Results on the SERP](../overview/results-overview.md).
+
+:::
+
+## Tailor the web experience
+
+**Grid**
+
+- Customize the layout of the results. Decide whether to display results using a grid or the default
+  list layout.
+- Configure what to display: product results, promotion banners, promoted results, or even next
+  queries and recommendations.
+- Customize the location, style, and content for each type of result.
+- Automatically fill the grid rows with as many columns as it can fit or set the number of columns
+  to divide the grid.
+- Indicate the number of product results to render per page.
+- Animate the display of the grid at your ease.
+- Allow your users to select the number of columns to display. Define if your shoppers will be
+  provided with a dropdown menu or a list with the columns to pick for the grid.
+- Show the total number of product results displayed. Configure the content with text, images, or
+  icons.
+
+**Sorting**
+
+- Choose and configure the sorting options available. Highlight the selected sorting option.
+- Select the display of the sorting system: dropdown menu or a simple list with the sorting options
+  available.
+- Animate the display of the sorting dropdown menu.
+- Set a default sorting option.
+  <!-- TBC: Decide which sorting option to display based on product category. -->
+
+**Pagination & scrolling**
+
+- Customize the content and style for the controls to move between pages.
+- Include an infinite scroll to load more results when reaching the end of the page.
+
+**Scrolling to top**
+
+- Decide when it will be displayed: when reached a defined threshold or the page end.
+- Configure the position and place it wherever you prefer.
+- Customize content. Show whatever you need: text, images, icons.
+- Animate the display of the scroll-to-top button at your ease.
+
+**Spell check**
+
+- Display a message to inform your shoppers that the
+  [Spell Check](../features/spellcheck-overview.md) feature has been used to provide results for the
+  current query.
+- Customize the message content at your ease.
+
+::: interact
+
+Want to know more? Learn how to [configure](/develop-empathy-platform/ui-reference/) your web
+experience.
+
+:::
+

package/docs/experience-search-and-discovery/sidebar.js

@@ -0,0 +1,17 @@
+export const sidebar = {
+  children: [
+    '/search-box.md',
+    '/empathize.md',
+    '/query-suggestions.md',
+    '/history-queries.md',
+    '/my-history.md',
+    '/popular-searches.md',
+    '/id-results.md',
+    '/related-tags.md',
+    '/next-queries.md',
+    '/recommendations.md',
+    '/product-results-ui.md',
+    '/serp-ui.md',
+    '/facets-and-filters.md'
+  ]
+};

package/docs/experience-search-and-discovery/web-local-storage.md

@@ -0,0 +1,24 @@
+---
+title: Interface X data privacy and browser local storage
+tags:
+  - x components
+  - interface x
+  - cookies
+  - local storage
+  - history queries
+  - cookieless
+---
+
+Interface X for web **does not use cookies** for storing data. The
+[Interface X Components](readme.md#interface-x-and-interface-x-for-apps-the-solution) use the web browser's local storage to save the technical data
+required to provide the services associated with the search & discovery experience. The data remains
+in the shopper's device until the expiration time is reached or the shopper chooses to delete it.
+
+More specifically, Interface X Components store the following elements in the browser's
+local storage:
+
+| Key                    | Duration                                             | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ---------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `x-session-id`         | 30 minutes                                           | Short-term session ID to be sent to the Tagging API. It identifies short sessions in a device. It does not identify individual shoppers in any way. It's required for [Analytics](/explore-empathy-platform/understand-data-privacy/), [Next Queries](/explore-empathy-platform/features/history-queries-overview.html), and [Related Tags](/explore-empathy-platform/features/related-tags-overview.html) features |
+| `x-session-time-stamp` | 30 minutes                                           | Timestamp for the current session ID                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `x-history-queries`    | Stored until the shopper clears/disables the feature | List of the searches performed that the shopper has chosen to store, which are shown in different steps of the search journey.                                                                                                                                                                                                                                                                                                                                                            |

package/empathize/index.js

@@ -1,5 +1,5 @@
-export { empathizeXStoreModule } from '../js/x-modules/empathize/store/module.js';
+export { default as Empathize } from '../js/x-modules/empathize/components/empathize.vue.js';
 export { empathizeEmitters } from '../js/x-modules/empathize/store/emitters.js';
+export { empathizeXStoreModule } from '../js/x-modules/empathize/store/module.js';
 export { empathizeWiring } from '../js/x-modules/empathize/wiring.js';
-export { empathizeXModule } from '../js/x-modules/empathize/x-module.js';
-export { default as Empathize } from '../js/x-modules/empathize/components/empathize.vue.js';
+export { empathizeXModule } from '../js/x-modules/empathize/x-module.js';