@empathyco/x-components 3.0.0-alpha.31 → 3.0.0-alpha.35

package/docs/API-reference/components/search-box/x-components.search-button.md

@@ -1,11 +1,12 @@
 ---
-id: x-components.x-components.search-button
-title: Search Button
-sidebar_label: Search Button
+
+title: SearchButton
+
 ---
-# search-button
 
-> This component renders a button to submit the query.
+# SearchButton
+
+This component renders a button to submit the query.
 
 If query is not empty, it emits {@link XEventsTypes.UserAcceptedAQuery} and
 {@link SearchBoxXEvents.UserPressedSearchButton} events with the query as payload.
@@ -17,8 +18,6 @@ It also adds `x-search-button--has-empty-query` as class when there is no query.
 | -------------------- | ------------------------------------------------ | ----------------------------------------- |
 | <code>default</code> | _Required_. Button content (text, icon, or both) | None                                      |
 
----
-
 ## Events
 
 This component emits the following events:

package/docs/API-reference/components/search-box/x-components.search-input.md

@@ -1,12 +1,13 @@
 ---
-id: x-components.x-components.search-input
-title: Search Input
-sidebar_label: Search Input
+
+title: SearchInput
+
 ---
-# search-input
 
-> This component renders an input field that allows the user to type a query. It also reacts to
-> query changes through event listening.
+# SearchInput
+
+This component renders an input field that allows the user to type a query. It also reacts to
+query changes through event listening.
 
 ## Props
 
@@ -19,8 +20,6 @@ sidebar_label: Search Input
 | <code>autocompleteKeyboardKeys</code>     | Keyboard keys to accept the autocomplete suggestion.      | <code>Array</code>         | <code>() => ['ArrowRight']</code>      |
 | <code>autocompleteSuggestionsEvent</code> | Event that retrieves the autocomplete suggestion.         | <code>PropsWithType</code> | <code>'QuerySuggestionsChanged'</code> |
 
----
-
 ## Events
 
 This component emits the following events:

package/docs/API-reference/components/tagging/x-components.tagging.md

@@ -1,9 +1,14 @@
 ---
-id: x-components.x-components.tagging
+
 title: Tagging
-sidebar_label: Tagging
+
 ---
-# tagging
+
+# Tagging
+
+This component enables and manages the sending of information to the
+{@link https://empathy.co/docs/tagging-api/ | Empathy Tagging API}. It allows to enable or
+disable the session id management through the `consent` prop.
 
 ## Props
 
@@ -13,8 +18,6 @@ sidebar_label: Tagging
 | <code>queryTaggingDebounceMs</code> | The debounce time in milliseconds to track the query. | <code>union</code>   | <code></code> |
 | <code>consent</code>                | The consent to be emitted.                            | <code>boolean</code> | <code></code> |
 
----
-
 ## Events
 
 This component emits the following events:

package/docs/API-reference/components/url/x-components.url-handler.md

@@ -1,16 +1,15 @@
 ---
-id: x-components.x-components.url-handler
-title: Url Handler
-sidebar_label: Url Handler
----
-# url-handler
 
-> This component manage the browser URL parameters to perserve them through reloads and browser
-> history navigation. It allow to configure the default url parameter names using its attributes.
-> This component doesn't render elements to the DOM.
+title: UrlHandler
 
 ---
 
+# UrlHandler
+
+This component manage the browser URL parameters to perserve them through reloads and browser
+history navigation. It allow to configure the default url parameter names using its attributes.
+This component doesn't render elements to the DOM.
+
 ## Events
 
 This component emits the following events:

package/docs/build-search-ui/README.md

@@ -1,9 +1,4 @@
 ---
-id: x-components.README
-title: README
-sidebar_label: README
----
----
 title: Build your search UI for web
 tags:
   - getting started

package/docs/build-search-ui/web-archetype-development-guide.md

@@ -0,0 +1,178 @@
+---
+title: Interface X Archetype Development
+tags:
+  - development
+  - archetype
+  - X Components archetype development
+  - x development
+  - interface x
+  - x components
+  - archetype development
+  - archetype integration
+---
+
+# Interface X Archetype Development
+
+In this tutorial, you’ll learn how to start developing with the Interface X Archetype
+project in your store in a matter of minutes, so you can create a search interface layer based on
+predefined features and components.
+
+For this tutorial, the Empathy Search API is used, but you can use any search API. This guide
+requires knowledge of JavaScript and Vue.js.
+
+::: note Before you begin
+
+To integrate Interface X Archetype as a search UI layer, you need:
+
+- **Empathy Search API** (or any search API that you use to retrieve search data).
+- **Empathy Search Adapter** to communicate with the Empathy Search API (or any search adapter to
+  connect with the search API you are using).
+
+:::
+
+##### Steps to start developing in a X Archetype project:
+
+1. **Clone** the X Archetype project and **initialize** your repository.
+2. Install the **project dependencies** and execute the project.
+3. Configure the **search adapter**.
+4. Configure the **xPlugin**.
+
+## 1. Clone the project and initialize your repository
+
+Clone the [X Archetype project](https://github.com/empathyco/x-archetype.git) from the GitHub
+repository to your target folder. You need a non-initialized repository, so make sure you remove the
+git folder from the cloned project.
+
+```batch
+// Clone the X Archetype project from GitHub
+git clone --depth 1 https://github.com/empathyco/x-archetype.git <your-target-folder>
+
+// Remove the git folder
+rm -rf .git
+```
+
+::: develop
+
+You can use [Degit](https://github.com/Rich-Harris/degit) to clone the git repository without
+downloading the entire git history:
+`npx degit https://github.com/empathyco/x-archetype.git <your-target-folder>`.
+
+:::
+
+Once you have cloned the project and removed the git history from the project, initialize the
+repository from the root directory.
+
+```batch
+// Initialize the repository
+git init
+git remote add origin <your-repository-url>
+git add .
+git commit -m "Initial X-Components Setup"
+git push -u origin main
+```
+
+Then, replace the current repository name (`@empathyco/x-archetype`) with the name of your
+repository in the `package.json` file.
+
+```json
+// Define your repository
+{
+   "name": "<your-repo>",
+   "author": "Empathy Systems Corporation S.L.",
+   …
+ }
+
+```
+
+## 2. Install the dependencies and execute the project
+
+Install the project dependencies via `npm` in the root folder of your cloned repository. Then, you
+can run the project.
+
+```batch
+// Install the dependencies via npm
+npm install
+
+// Execute the project
+npm run serve
+```
+
+::: interact For a full list of the project dependencies, check the
+[`package.json`](https://github.com/empathyco/x-archetype/blob/main/package.json) file in the
+Interface&nbsp;X&nbsp;Archetype repository. :::
+
+## 3. Configure the search adapter
+
+Before using your project, configure the Empathy Search Adapter in the
+`x-archetype/src/adapter/adapter.ts` file, using the Empathy Adapter Builder to make it work with
+the Empathy Search API. The Empathy Search Adapter contains a sample configuration for setup, global
+configurations, or mappers that points to a demo environment. You need to make some adjustments in
+the configuration according to the search features you use in your project.
+
+Export the required search adapter with your configuration as you will need it for the search
+[xPlugin configuration](web-archetype-integration-guide.md#_4-configure-the-plugin).
+
+::: interact For detailed information about other configuration options in the Empathy Search
+Adapter, go to the
+[x-adapter repository](https://github.com/empathyco/x/tree/main/packages/search-adapter). :::
+
+::: note Although you configure the values for the `instance`, `language`, `scope`, and `endpoint`
+options when integrating the project, you can still change these values when the project is
+deployed. Use the `/x-archetype/public/snippet-script.js` file to perform hot changes for `lang`,
+`store`, `device`, and `catalog` parameters.
+
+For example, you may configure the adapter to use EN as `lang` so that when you search, the results
+are displayed in English. However, if you want to deploy the application in Spain, you want the
+`lang` to be ES. You change these values in the `snippet-script.js` file.
+
+:::
+
+## 4. Configure the plugin
+
+The `xPlugin` initializes the properties needed by the X&nbsp;Components. It has key options that
+you can configure in the `/x-archetype/src/x-components/plugin.options.ts` file.
+
+Since the X&nbsp;Archetype project operates as a layer and is designed to be integrated on top of
+any kind of website regardless the chosen technology, the `XInstaller` utility and its
+`installXOptions` object are designed to install the xPlugin, adding the connection between the
+X&nbsp;Components and the search API and bootstrapping the entire application with powerful APIs
+that are available in the `window.X` object.
+
+To configure the xPlugin, run this code:
+
+```typescript
+import { InstallXOptions, XInstaller } from '@empathyco/x-components';
+import App from './App.vue';
+import store from './store';
+import { adapter } from '../adapter';
+
+export const installXOptions: InstallXOptions = {
+  adapter,
+  store,
+  app: App
+};
+
+new XInstaller(installXOptions).init({
+  instance: '<your-search-api-instance>',
+  lang: '<your-application-language>',
+  scope: '<your-application-scope>'
+});
+```
+
+---
+
+### Next steps
+
+Once you have your Interface&nbsp;X&nbsp;Archetype project, you're ready to integrate it in your
+store, or extend the search and discovery experience to meet your business needs:
+
+- [Integrate an Interface&nbsp;X&nbsp;Archetype project into an existing website](web-archetype-integration-guide.md).
+- Change the configuration of [X Components](web-use-x-components-guide.md) or create new ones.
+- Adapt the
+  [design system](https://github.com/empathyco/x/blob/main/packages/x-components/contributing/design-system.md)
+  to your branding.
+- Manage
+  [internationalization options](https://github.com/empathyco/x-archetype/blob/main/docs/i18n.md) to
+  support different languages.
+
+<!-- add links to design system and internationalization content pages when ready-->

package/docs/build-search-ui/web-archetype-integration-guide.md

@@ -1,10 +1,5 @@
 ---
-id: x-components.web-archetype-integration-guide
-title: Web Archetype Integration Guide
-sidebar_label: Web Archetype Integration Guide
----
----
-title: Integrate Interface X Archetype
+title: Integrate Interface X Archetype into an existing website
 tags:
   - integration
   - archetype
@@ -15,169 +10,177 @@ tags:
   - archetype integration
 ---
 
-# Integrate Interface X Archetype
-
-In this tutorial, you’ll learn how to integrate the Interface X Archetype project in your
-store in a matter of minutes so you can develop a search interface layer based on predefined
-features and components.
-
-For this tutorial, the Empathy Search API is used, but you can use any search API. This guide
-requires knowledge of JavaScript and Vue.js.
+# Integrate Interface X Archetype into an existing website
 
-::: note Before you begin
+Once you have finished developing or extending your search interface using the
+Interface X Archetype project you will probably want to integrate it into your current
+store.
 
-To integrate Interface X Archetype as a search UI layer, you need:
+The integration is a 2-steps process:
 
-- **Empathy Search API** (or any search API that you use to retrieve search data).
-- **Empathy Search Adapter** to communicate with the Empathy Search API (or any search adapter to
-  connect with the search API you are using).
+- Load Interface X script.
+- Initialise the Interface X.
 
-:::
+Depending on your business needs, there are 2 different ways of making this integration process:
+auto initialising, or initialising on demand.
 
-##### Steps to integrate X Archetype project:
+## Auto initialisation
 
-1. **Clone** the X Archetype project and **initialize** your repository.
-2. Install the **project dependencies** and execute the project.
-3. Configure the **search adapter**.
-4. Configure the **xPlugin**.
+This is the easiest way to integrate the Interface X project in a website. The way to do so is
+by first defining an initialisation object or function, and then loading the Interface X
+script.
 
-## 1. Clone the project and initialize your repository
+### 1. Add a snippet configuration
 
-Clone the [X Archetype project](https://github.com/empathyco/x-archetype.git) from the GitHub
-repository to your target folder. You need a non-initialized repository, so make sure you remove the
-git folder from the cloned project.
+The snippet configuration is needed by Interface X to know the API it must use, the language or
+currency it should display the texts in, or tagging parameters to enrich the data and provide better
+insights on how users search.
 
-```batch
-// Clone the X Archetype project from GitHub
-git clone --depth 1 https://github.com/empathyco/x-archetype.git <your-target-folder>
+If your configuration values are easy to retrieve or static, you can simply use an object.
 
-// Remove the git folder
-rm -rf .git
+```js
+window.initX = {
+  instance: 'my-store',
+  env: 'live',
+  scope: 'desktop',
+  lang: 'en',
+  currency: 'EUR',
+  consent: false
+};
 ```
 
-::: develop
-
-You can use [Degit](https://github.com/Rich-Harris/degit) to clone the git repository without
-downloading the entire git history:
-`npx degit https://github.com/empathyco/x-archetype.git <your-target-folder>`.
-
-:::
-
-Once you have cloned the project and removed the git history from the project, initialize the
-repository from the root directory.
-
-```batch
-// Initialize the repository
-git init
-git remote add origin <your-repository-url>
-git add .
-git commit -m "Initial X-Components Setup"
-git push -u origin main
+Otherwise, if you need to retrieve values dynamically, or execute any kind of logic before the
+initialisation you can also use a function:
+
+```js
+window.initX = function () {
+  return {
+    instance: 'my-store',
+    env: location.href.includes('.pre.') ? 'staging' : 'live',
+    scope: 'web',
+    lang: localStorage.get('lang'),
+    currency: localStorage.get('currency'),
+    consent: localStorage.get('consent')
+  };
+};
 ```
 
-Then, replace the current repository name (`@empathyco/x-archetype`) with the name of your
-repository in the `package.json` file.
-
-```json
-// Define your repository
-{
-   "name": "<your-repo>",
-   "author": "Empathy Systems Corporation S.L.",
-   …
- }
-
+You can read more about the [Snippet Configuration](#snippet-configuration) below.
+
+### 2. Load the Interface&nbsp;X script
+
+Once you have defined your snippet configuration either as an object or a function, you can insert
+the Interface&nbsp;X script. This script is hosted in a URL of this shape
+`https://x.<environment?>.empathy.co/<instance>/app.js`.
+
+For example, supposing that `my-store` is the instance, and you want to load the production script,
+you can add to your HTML the following scripts.
+
+```html
+<script>
+  window.initX = {
+    instance: 'my-store',
+    env: 'live',
+    scope: 'desktop',
+    lang: 'en',
+    currency: 'EUR',
+    consent: false
+  };
+</script>
+<script src="https://x.empathy.co/my-store/app.js"></script>
 ```
 
-## 2. Install the dependencies and execute the project
-
-Install the project dependencies via `npm` in the root folder of your cloned repository. Then, you
-can run the project.
-
-```batch
-// Install the dependencies via npm
-npm install
-
-// Execute the project
-npm run serve
+Or if you want to load the staging version, you just have to change the script `src` attribute to
+point to the staging environment:
+
+```html
+<script>
+  window.initX = {
+    instance: 'my-store',
+    env: 'live', // Note that here you are using production API with the staging version of Interface X
+    scope: 'desktop',
+    lang: 'en',
+    currency: 'EUR',
+    consent: false
+  };
+</script>
+<script src="https://x.staging.empathy.co/my-store/app.js"></script>
 ```
 
-::: interact  
-For a full list of the project dependencies, check the
-[`package.json`](https://github.com/empathyco/x-archetype/blob/main/package.json) file in the
-Interface&nbsp;X&nbsp;Archetype repository. :::
-
-## 3. Configure the search adapter
-
-Before using your project, configure the Empathy Search Adapter in the
-`x-archetype/src/adapter/adapter.ts` file, using the Empathy Adapter Builder to make it work with
-the Empathy Search API. The Empathy Search Adapter contains a sample configuration for setup, global
-configurations, or mappers that points to a demo environment. You need to make some adjustments in
-the configuration according to the search features you use in your project.
-
-Export the required search adapter with your configuration as you will need it for the search
-[xPlugin configuration](web-archetype-integration-guide.md#_4-configure-the-plugin).
-
-::: interact For detailed information about other configuration options in the Empathy Search
-Adapter, go to the
-[x-adapter repository](https://github.com/empathyco/x/tree/main/packages/search-adapter). :::
-
-::: note Although you configure the values for the `instance`, `language`, `scope`, and `endpoint`
-options when integrating the project, you can still change these values when the project is
-deployed. Use the `/x-archetype/public/snippet-script.js` file to perform hot changes for `lang`,
-`store`, `device`, and `catalog` parameters.
-
-For example, you may configure the adapter to use EN as `lang` so that when you search, the results
-are displayed in English. However, if you want to deploy the application in Spain, you want the
-`lang` to be ES. You change these values in the `snippet-script.js` file.
+This way, when the Interface&nbsp;X JavaScript file is loaded, it will retrieve the configuration
+from the object or function that you defined before. Nothing else is required.
 
-:::
+## Initialise on demand
 
-## 4. Configure the plugin
+If you want to have more manual control on when the Interface&nbsp;X is loaded, you can still do so.
+Instead of defining an initialisation object or function upfront like in
+[Auto initialisation](#auto-initialisation), you can invoke a function with these options that will
+initialise Interface&nbsp;X.
 
-The `xPlugin` initializes the properties needed by the X&nbsp;Components. It has key options that
-you can configure in the `/x-archetype/src/x-components/plugin.options.ts` file.
+### 1. Load the Interface&nbsp;X script
 
-Since the X&nbsp;Archetype project operates as a layer and is designed to be integrated on top of
-any kind of website regardless the chosen technology, the `XInstaller` utility and its
-`installXOptions` object are designed to install the xPlugin, adding the connection between the
-X&nbsp;Components and the search API and bootstrapping the entire application with powerful APIs
-that are available in the `window.X` object.
+First, load the Interface&nbsp;X script. As you may already know, it is hosted in a URL of this
+shape: `https://x.<environment?>.empathy.co/<instance>/app.js`.
 
-To configure the xPlugin, run this code:
+For example, supposing that `my-store` is the instance, and you want to load the production script,
+you can add to your HTML the following scripts:
 
-```typescript
-import { InstallXOptions, XInstaller } from '@empathyco/x-components';
-import App from './App.vue';
-import store from './store';
-import { adapter } from '../adapter';
-
-export const installXOptions: InstallXOptions = {
-  adapter,
-  store,
-  app: App
-};
-
-new XInstaller(installXOptions).init({
-  instance: '<your-search-api-instance>',
-  lang: '<your-application-language>',
-  scope: '<your-application-scope>'
-});
+```html
+<script src="https://x.empathy.co/my-store/app.js"></script>
 ```
 
----
+For loading the staging version simply change the `src` attribute to the staging environment:
 
-### Next steps
-
-Once you have integrated the Interface&nbsp;X&nbsp;Archetype in your store, you're ready to start
-using the X&nbsp;Archetype as is or extend the search and discovery experience to meet your business
-needs:
+```html
+<script src="https://x.staging.empathy.co/my-store/app.js"></script>
+```
 
-- Change the configuration of [X Components](web-use-x-components-guide.md) or create new ones.
-- Adapt the
-  [design system](https://github.com/empathyco/x/blob/main/packages/x-components/contributing/design-system.md)
-  to your branding.
-- Manage
-  [internationalization options](https://github.com/empathyco/x-archetype/blob/main/docs/i18n.md) to
-  support different languages.
+### 2. Initialise Interface&nbsp;X
+
+Loading the Interface&nbsp;X script and not providing a `initX` configuration will make it create an
+initialisation function in the [X API](#x-api) object that you can invoke whenever you want. In this
+example we are calling it immediately after loading the Interface&nbsp;X script, but it can be
+invoked at any time. Note that you should only call this function **once**.
+
+```html
+<script src="https://x.empathy.co/my-store/app.js"></script>
+<script>
+  window.X.init({
+    instance: 'my-store',
+    env: 'live',
+    scope: 'desktop',
+    lang: 'en',
+    currency: 'EUR',
+    consent: false
+  });
+</script>
+```
 
-<!-- add links to design system and internationalization content pages when ready-->
+## Snippet configuration
+
+The snippet configuration allows you to configure certain parts of the Interface&nbsp;X project like
+language, the currency, inform whether the user has given us his consent to process personal data.
+
+| Name                  | Type                                                                                 | Required | Description                                                                                                                                                                                                                                                                                     |
+| --------------------- | ------------------------------------------------------------------------------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| instance              | `string`                                                                             |    ✅    | The identifier of the API client instance. Should be provided by Empathy                                                                                                                                                                                                                        |
+| env                   | `'live'` &#124; `'staging'`                                                          |          | The API environment to use. Note that you can use the production version of your Interface&nbsp;X with the staging API, or viceversa.                                                                                                                                                           |
+| scope                 | `string`                                                                             |          | The context name where the search interface is being executed. I.e. `mobile`, `mobile-app`, `tablet`, `desktop`                                                                                                                                                                                 |
+| lang                  | `string`                                                                             |    ✅    | The language to use. By default this lang is used for both the front-end and the API requests                                                                                                                                                                                                   |
+| searchLang            | `string`                                                                             |          | A language to use only for the API requests                                                                                                                                                                                                                                                     |
+| consent               | `boolean`                                                                            |    ✅    | Whether the user has allowed to process its personal data or not. X-Components do not track or process any personal data. This parameter is used to generate a unique session id                                                                                                                |
+| documentDirection     | `'ltr'` &#124; `'rtl'`                                                               |          | The writing direction that the X Components should use                                                                                                                                                                                                                                          |
+| currency              | `string`                                                                             |    ✅    | The currency identifier. Used to configure how prices are shown                                                                                                                                                                                                                                 |
+| callbacks             | `Record<XEventName, (payload: XEventPayload<Event>, metadata: WireMetadata) => void` |          | A record of callbacks where the key is the event to listen, and the value is the callback to be executed whenever the event is emitted. For example, to listen to the `UserAcceptedAQuery` event: `{ UserAcceptedAQuery({ eventPayload }) { console.log('UserAcceptedAQuery', eventPayload); }` |
+| isSpa                 | `boolean`                                                                            |          | True when the X Components archetype is being run on top of an SPA.                                                                                                                                                                                                                             |
+| &lt;extra parameters> | `any`                                                                                |          | Any other parameter to be sent directly to the API calls. For example, some times is needed to filter the search catalog with a warehouse parameter. In that case you can just add `warehouse: <your-warehouse-identifier>` to the snippet config.                                              |
+
+## X API
+
+The X API allows your website to communicate with Interface&X. It is a set of utilities that helps
+to integrate Interface&X into your website.
+
+| Function | Parameters                                                                     | Description                                                 |
+| -------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| init     | - [Snippet Configuration](#snippet-configuration) - The initialisation options | [Initialises Interface X on demand](#initialise-on-demand). |
+| search   | - query (Optional) - The query to open Interface&nbsp;X with                   | Opens Interface&nbsp;X with the given search query.         |

package/docs/build-search-ui/web-use-x-components-guide.md

@@ -1,9 +1,4 @@
 ---
-id: x-components.web-use-x-components-guide
-title: Web Use X Components Guide
-sidebar_label: Web Use X Components Guide
----
----
 title: Use & configure Interface X Components in your project
 tags:
   - configuration