@empathyco/x-components 3.0.0-alpha.34 → 3.0.0-alpha.341

package/docs/experience-search-and-discovery/facets-and-filters.md

@@ -0,0 +1,150 @@
+---
+title: Facets & Filters UI
+tag:
+  - faceted
+---
+
+Facets and Filters allow your shoppers to organize your product catalogue in different categories
+and narrow the search results to better find what they are looking for. Shoppers can set filters
+according to the categories or facets defined in the faceted menu, which is usually located on the
+left or upper side of the search engine results page or product listing page.
+
+![Facets](~@assets/x/interface/x-facets.gif)
+
+X Components for facets present how you have categorized your products, displaying the
+different aspects available (brand, price, color…), while the filter-related components render the
+values for those aspects that shoppers can use to filter by ("Nestlé", "Kellogg’s" for _brand_;
+“€0 - €10”, “€10 - €50” for _price_; “blue”, “black”, “white” for _color_), allowing you to
+determine how to display them.
+
+<!--Originally, the X&nbsp;Components for facets and filters were designed for **search**. However,
+since they can precisely organize and filter your product catalogue to bring out the products that
+best fit your shoppers’ needs, you can also use them for **catalogue navigation** and **product
+discovery**. You can guide shoppers through your product catalogue faster, allowing them to navigate
+and browse different product classifications directly from the faceted menu in your shop, without
+having to search.-->
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[Facets and Filters](../overview/facets-and-filters-overview.md).
+
+:::
+
+## Build a faceted experience with X Components
+
+There is no need to reinvent the wheel to design a good faceting experience, but rather it’s better
+to understand the shopper’s journey and the frontend options available.
+
+Facets and filters can display as different UI element types (select list, search, range…) using the
+numerous X&nbsp;Components available. Flexibly combine X&nbsp;Components to build the connection
+with the product attributes in your catalogue. **Guide** shoppers towards relevant results in record
+time, giving them the opportunity to establish a **dialogue** with your product catalogue and easily
+decide what results to display by adding and clearing filters, or make information on product
+results **clearer and more accessible**, meeting different types of faceting layouts.
+
+![Facets](~@assets/x/interface/x-facets.svg)
+
+::: details Rendering facets and filters
+
+X&nbsp;Components for facets and filters not only enhances your shoppers’ experience by supporting
+and rendering faceted search and navigation, but also provides different ways to display a faceted
+experience:
+
+</br>
+
+- **Standard facets**: a single-select list that offers a way to describe a product attribute,
+  together with the values available to filter by. For example, a _Color_ facet can include values
+  such as “red”, “blue”, “white”, “black”, or “green”.
+- **Hierarchical facets**: present filter values organized hierarchically, providing a parent-child
+  filtering relationship. Shoppers can filter using the parent subfacet or choose the child subfacet
+  as a more precise filter. For example, the _Category_ facet in a jewellery store can display
+  “Button”, “Short”, and “Long” as child filters for the “Earrings” parent filter.
+- **Number range facets**: allow shoppers to select a range of numerical values and narrow the
+  results within those ranges. Intended for price or size facets that have numeric value type
+  attributes. For example, the _Price_ facet in a grocery store can display “< €0.99”, “€1 – €4.99”,
+  “€5 – €9.99”, or “€10 – €19.99”. Implement **editable number range facets** and let your shoppers
+  define the numerical ranges they want to filter by. Shoppers can type the desired price range to
+  filter by in the _From_ - _To_ or _Min_ - _Max_ input fields available.
+
+:::
+
+::: details Extending facets and filters UI
+
+Apart from the main X&nbsp;Components for facets and filters that render product categories and
+their corresponding attributes in different ways, there are components available offering advanced
+options to enhance the faceted experience.
+
+</br>
+
+- **Collapse & expand** to initially display facets collapsed on page load with a predetermined
+  number of filter values. Use a Show more button to expand the full list.
+- **Search box** to perform a text-based search on the filter values so that shoppers quickly find
+  the filters to apply to the results set.
+- **Selected filters list** to keep track of the shopper’s selection and understand the results
+  displayed. Selected filters can be displayed together under the same list or be organized by
+  facets. Shoppers can deselect any of the previously applied filters or clear all at once to try
+  different filtering values.
+- **Selected filters first** to change the order in which filters are initially displayed within a
+  facet so that the selected filters come first in the list. Note that the order of facets and
+  filters is determined by your Search microservice, usually showing the filters with the highest
+  number of products.
+- **Product count** to display the number of matches or occurrences next to the facet filter.
+  Shoppers can instantly see how many products each filter contains, offering a valuable insight on
+  your product catalog.
+- **Zero count** to only display filter values for those filters that **match a product result**,
+  omitting all those filters that have zero occurrences. For example, the query “skirts” in a retail
+  shop returns a large number of results for women and kids, but none for men. In this case, the
+  _Category_ facet only displays the filters “Woman”, “Girl”, and “Baby”.
+
+</br>
+
+Besides, you can use X&nbsp;Components to customize other attributes and behaviors. Transform a
+value returned from the Search microservice of “20 - 50” into “€20 - €50” or turn a numerical value
+into icons or images such as stars for average rating-based filtering, for example.
+
+</br>
+
+You can also change the default single-select behavior and activate **multi-select** controls so
+that shoppers can select more than one filter value at a time from the same facet to expand results.
+
+:::
+
+## Tailor the web experience
+
+**Layout, location, and display**:
+
+- Place the facets menu wherever you prefer. However, facets are commonly positioned in the left
+  sidebar or as top horizontal facets.
+- Hide or show the facets & filter menu when search results are displayed. Display facets and
+  filters as collapsed lists at first.
+- Animate the display of different elements: facets, filters, and related lists (e.g. selected
+  filters list).
+- Build the layout of facets and filters at your ease: from dropdowns and checkboxes to switches,
+  tags, and sliders.
+
+**Data and content**:
+
+- Select which facets defined in your product catalogue you want to display according to your
+  business strategy or your shoppers’ needs.
+- Configure the content of filters. Allow shoppers to filter results using text, icons, or
+  checkboxes.
+- Configure the content of related buttons (e.g. Show more button). Show whatever you need: text or
+  icons.
+- Customize labels in the facets and filters list. Add a custom title for facets, filters, and
+  related lists (e.g. selected filters list).
+- Customize facet data at your ease. You can opt to render facets defined in your product catalogue
+  automatically, display custom facets, or even render a mix of them.
+
+::: warning
+
+Make sure your current Search microservice is compatible with this kind of configuration.
+
+:::
+
+::: interact
+
+Want to know more? Learn how to
+[configure](/develop-empathy-platform/ui-reference/components/facets/) your web experience.
+
+:::

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

@@ -0,0 +1,66 @@
+---
+title: History Queries UI
+---
+
+The History Queries UI component displays the search history, allowing shoppers to check previous
+searches and revisit products they’ve viewed before in a few clicks.
+
+![History Queries](~@assets/x/interface/x-history-queries.gif)
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[History Queries](../features/history-queries-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 under the search bar on shopper
+  interaction.
+- Show as many history suggestions as you want.
+- Choose the number of search records to store in the browser’s local storage to refresh the history
+  list.
+- Animate the display of History Queries at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+- Display History Queries only from successful searches. No result, no search record stored. (Search
+  X module required.)
+- Configure clear buttons at your convenience. Let shoppers clear previous searches one-by-one,
+  all-at-once, or either way.
+- Display only the refined queries to match shopper intent. For example, if “dress” is the initial
+  search, and it’s narrowed down using “long dress”, the history queries list only displays “long
+  dress” since it represents the shopper’s real intention.
+
+::: interact
+
+Want to know more? Learn how to
+[configure](/develop-empathy-platform/ui-reference/components/history-queries/) your web experience.
+
+:::
+
+## Extend the performance
+
+You can extend search history performance by combining it with the [Next Queries](next-queries.md)
+component. All suggestions for shoppers about what to look next can be filtered against the
+shopper’s search history so that only those suggestions that haven’t been used before in that
+session will display.
+
+Combine History Queries with the
+[Search module](/develop-empathy-platform/ui-reference/components/search/) to ease shoppers'
+frustrations. That way, you can configure it to display only successful history searches.
+
+::: note Search history tracking
+
+Use the [My History](my-history.md) component to access and control search history. Shoppers can
+view a complete list of history queries and decide to stop saving search history. If search history
+is disabled, the History Queries list is cleared.
+
+:::
+
+::: interact
+
+To know more about which data is stored in the browser’s data storage, check out
+[Interface X data privacy and browser local storage](web-local-storage.md).
+
+:::

package/docs/experience-search-and-discovery/id-results.md

@@ -0,0 +1,45 @@
+---
+title: ID Results UI
+tags:
+  - identifier results
+---
+
+The Identifier Results UI component presents a type of search results intended for product reference
+codes. When shoppers start typing, a reference code query type is detected, and a list displays
+instantly with query-matching product results. When shoppers select an identifier result hint from
+the list, they go directly to the product detail page (PDP).
+
+![ID Results](~@assets/x/interface/x-id-results.gif)
+
+:::warning
+
+ID Results are generated using a Search service that searches the product catalogue by ID. For a
+correct performance, make sure that your current search service supports this type of feature.
+
+:::
+
+::: interact
+
+Don't quite understand ID results? Learn more about
+[ID Results](../features/id-results-overview.md).
+
+:::
+
+## Tailor the web experience
+
+- Configure the position and place it wherever you prefer. Combine it with the
+  [Empathize](empathize.md) container display the ID Results below the search bar on shopper
+  interaction.
+- Show as many ID Results as you want.
+- Animate the display of ID Results at your ease.
+- Customize content. Show whatever you need: text, images, icons.
+- Extend the performance with [results-related components](product-results-ui.md).
+- Meet your own code reference conventions and standards with multiple product reference patterns.
+
+::: interact
+
+Want to know more? Learn how to
+[configure](/develop-empathy-platform/ui-reference/components/identifier-results/) your web
+experience.
+
+:::

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

@@ -0,0 +1,56 @@
+---
+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/x/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/x/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,46 @@
+---
+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/x/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,78 @@
+---
+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/x/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,44 @@
+---
+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/x/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,48 @@
+---
+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/x/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,62 @@
+---
+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 search engine results page (SERP), but Empathy
+Platform Interface X supports displaying them anywhere on the SERP instead.
+
+![Related Tags](~@assets/x/interface/x-related-tags.gif)
+
+::: interact
+
+Can't quite capture the concept? Learn more about
+[Related Tags](../features/related-tags-overview.md).
+
+:::
+
+Related Tags can be **organic**, using information on the terms most used by shoppers to refine a
+query. Otherwise, you can create manually **curated** related tags, based on your business needs, by
+using the Related Tags management tool in the Empathy Platform Playboard.
+
+::: warning
+
+Related Tags are generated organically 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
+
+Wondering how to create curated related tags in the Empathy Platform Playboard? Check out
+[Manage Related Tags](/explore-empathy-platform/fine-tune-search-and-discovery/manage-related-tags.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.
+- Display curated related tags differently to organic related tags for shoppers to clearly identify
+  which of them have been willfully created as a sign of transparency.
+
+<!-- - 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
+using the X Components available for Related Tags.
+
+:::