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

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

@@ -0,0 +1,183 @@
+---
+id: x-components.web-archetype-integration-guide
+title: Web Archetype Integration Guide
+sidebar_label: Web Archetype Integration Guide
+---
+---
+title: Integrate Interface X Archetype
+tags:
+  - integration
+  - archetype
+  - X Components archetype integration
+  - x integration
+  - interface x
+  - x components
+  - 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.
+
+::: 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 integrate 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 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:
+
+- 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-use-x-components-guide.md

@@ -0,0 +1,170 @@
+---
+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
+  - x configuration
+  - x component configuration
+---
+
+# Use and configure Interface X Components in your project
+
+Interface X Components are like building blocks that you pick up and mix to craft your
+search UI experiences. The goal of using components is to include only the components you want,
+wherever you want. So, **just import the components, register, and go!**
+
+Once you’ve installed the
+[dependencies and the xPlugin](web-x-components-integration-guide.md#_1-install-the-dependencies),
+you’re ready to use X Components in your project.
+
+## 1. Import and register the X Components
+
+Many of the X Components are distributed into modules to make them easier to manage. So you
+need to indicate from which module you’re importing each component as appropriate.
+
+For example, the `search-box` module contains the `SearchInput`, `SearchButton`, and
+`ClearSearchInput` components.
+
+### Import and register components from a module
+
+When importing the components, you can register each component **locally for each Vue instance** as
+you go.
+
+```typescript
+//Import each component you'd like to use, before you register it.
+import { ComponentA } from './Module1';
+import { ComponentB } from './Module1';
+import { ComponentC } from './Module1';
+
+//Locally register each component.
+export default {
+  components: {
+    ComponentA,
+    ComponentB,
+    ComponentC
+  }
+  // ...
+};
+
+//The components are now ready to be used inside your template.
+```
+
+### Import and register components globally
+
+Alternatively, you can **globally** register components in Vue directly in the `main.js` file if you
+plan on using a component more than once in your app. By registering the components globally, you
+can use them in the template of any root Vue instance you create afterwards.
+
+::: develop Although you can register components globally, it should be done with caution as **it
+may impact future performance**. Remember if you register the components globally, the entire
+X Component module is loaded and registered each time this code line is run. :::
+
+```typescript
+import { ComponentA, ComponentB, ComponentC } from './ModuleA';
+
+Vue.component('ComponentAName', ComponentA);
+Vue.component('ComponentBName', ComponentB);
+Vue.component('ComponentCName', ComponentC);
+```
+
+## 2. Configure the X Components
+
+You can configure some behaviors for each component to customize the search experience.
+
+To provide different project-specific behaviors, you can use:
+
+- **Props**: custom attributes to pass data into a component. It modifies the behavior or the
+  properties in a component.
+
+```vue
+//Configure a component with props.
+<SearchInput :maxLength="5" :autofocus="false" :instant="true" :instantDebounceInMs="1000" />
+```
+
+- **Scoped slots**: a slot exposes data from a child component to create your own custom
+  implementation.
+
+```vue
+//Configure a component with slots.
+<ClearSearchInput>Clear</ClearSearchInput>
+```
+
+You can pass the configuration attributes documented in the
+[UI Reference](/develop-empathy-platform/ui-reference/) for the Interface&nbsp;X&nbsp;Components.
+
+You can combine components at your ease and use resource modules such as modals, panels, and
+animations. You can also use base components, i.e. standard Vue components that don’t have any
+dependencies with the X&nbsp;Components. Use them as a foundation to build other components.
+
+Your components are ready to go, but you can provide your search UI with a friendly and fancy style
+and layout. For more information, see
+[Design tokens](https://github.com/empathyco/x/blob/main/packages/x-components/contributing/design-system.md).
+
+<!--If you want to support multiple languages, you can use the [x-translation](https://github.com/empathyco/x/tree/main/packages/x-translations) library to manage localization options.-->
+
+## Example: Using the search box components
+
+To build your search UI, you need to provide at least a search field that allows users to input a
+query. Additionally, you can include a button to trigger the search and a button to delete the input
+query.
+
+The search-box module contains these components:
+
+- `SearchInput`
+- `SearchButton`
+- `ClearSearchInput`
+
+::: interact Learn more about the
+[Search Box UI](/explore-empathy-platform/experience-search-&-discovery/search-box.md) :::
+
+### Importing the components from the search-box module
+
+For this purpose, you need to import the `SearchInput`, `SearchButton`, and `ClearSearchInput`
+components from the `search-box` module to the desired app component. Then, register them and
+include them in the template.
+
+First, import and locally register the components.
+
+```vue
+//Import the components from the corresponding module.
+<script>
+  import { SearchInput, SearchButton, ClearSearchInput } from '@empathyco/x-components/search-box';
+
+  //Locally register each component.
+  export default {
+    components: { SearchInput, SearchButton, ClearSearchInput }
+  };
+</script>
+```
+
+Now, you’re ready to start using the component wherever you want in your template.
+
+```vue
+<template>
+  <div>
+    <SearchInput />
+    <SearchButton />
+    <ClearSearchInput />
+  </div>
+</template>
+```
+
+### Configuring the SearchInput component
+
+Next, you want to configure the behavior of the `SearchInput` component. Here you use the
+`maxLength` prop to limit the maximum length to 20 characters.
+
+```vue
+<SearchInput
+  :maxLength="20"
+  :autofocus="false"
+  :instant="true"
+  :instantDebounceInMs="1000"
+  :autocompleteKeyboardKeys="['ArrowDown']"
+  :autocompleteSuggestionsEvent="'NextQueriesChanged'"
+/>
+```

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

@@ -0,0 +1,197 @@
+---
+id: x-components.web-x-components-integration-guide
+title: Web X Components Integration Guide
+sidebar_label: Web X Components Integration Guide
+---
+---
+title: Integrate Interface X Components in your Vue application
+tags:
+  - integration
+  - interface x components integration
+  - web integration
+  - x integration
+  - interface x
+---
+
+# Integrate Interface X Components in your Vue application
+
+In this tutorial, you’ll learn the basics to integrate the Interface X Components library
+in your own project to craft enticing Vue search experiences for your shop in a matter of minutes.
+
+::: interact If you are looking to use the ready-to-go project Interface X Archetype as
+your starting point, see
+**[Integrate Interface X Archetype project](/develop-empathy-platform/build-search-ui/web-archetype-integration-guide.md)**.
+:::
+
+For this tutorial, the Empathy Search API is used, but you can use any search API. This step-by-step
+guide requires a knowledge of **JavaScript** and **Vue.js**.
+
+You can find the X Components library in the
+[Interface X open source project in GitHub](https://github.com/empathyco/x).
+
+::: note Before you begin
+
+To integrate the X Components in a frontend UI, you need:
+
+- **Empathy Search API** to retrieve search data (or any other search API)
+- A **search adapter** to communicate with the search API. You can use the Empathy Adapter and
+  configure it with the `EmpathyAdapterBuilder`
+
+:::
+
+##### Steps to integrate the X Components in your project:
+
+1. Install **project dependencies**.
+2. Configure the **search adapter**.
+3. Configure the **xPlugin**.
+4. Install and **initialize the xPlugin**.
+
+## 1. Install the dependencies
+
+To build your search and discovery UI, the following project dependencies are required:
+
+- **x-components** library
+  ([`@empathyco/x-components`](https://github.com/empathyco/x/tree/main/packages/x-components)):
+  Interface X Components Vue.js library to implement out-of-the-box search UI components
+  in a couple of minutes.
+
+- **x-adapter**
+  ([`@empathyco/x-adapter`](https://github.com/empathyco/x/tree/main/packages/search-adapter)): A
+  search adapter connector that tells the app how to communicate with the Empathy Search API you’re
+  using, translating the response into understandable information for X Components. If you are
+  not using the Empathy Search API, you need to build your own search adapter.
+
+- **x-types**
+  ([`@empathyco/x-types`](https://github.com/empathyco/x/tree/main/packages/search-types)): The data
+  model used in the X Components to define types.
+
+- **reflect-metadata**: Polyfill that allows the internal decorators of X Components to be
+  used. This is only required if you use the Empathy search adapter (`x-adapter`).
+
+Install the project dependencies via `npm` as follows:
+
+```batch
+//Install the dependencies via npm.
+npm install --save @empathyco/x-components @empathyco/x-types @empathyco/x-adapter reflect-metadata
+```
+
+## 2. Configure the search adapter
+
+::: warning If you are using the Empathy search API and the Empathy Search Adapter (`x-adapter`),
+make sure you have imported the `reflect-metadata` polyfill before executing any code of the search
+adapter. :::
+
+Next, construct the search adapter. You will need the search adapter in the
+[xPlugin configuration](#_3-configure-the-xplugin).
+
+Empathy Search Adapter is a library for making it easier to consume search APIs. The project
+contains two main parts: an **implementation** to consume the Empathy Search API, and an
+**interface** that you can use to build your own adapter for other APIs.
+
+It contains a specific builder that helps you to configure the Empathy Search Adapter. If you are
+using Empathy Search API, you need to only configure the values for `instance`, `language`, `scope`,
+and `endpoint` properties in the `empathy-adapter.config.ts` file.
+
+```typescript
+// Import the search adapter and metadata
+import 'reflect-metadata';
+import { EmpathyAdapterBuilder } from '@empathyco/x-adapter';
+
+// Construct the EmpathyAdapterBuilder
+export const adapter = new EmpathyAdapterBuilder()
+  .withConfiguration({ instance: 'my-instance-id' })
+  .setLang('es')
+  .setScope('demo')
+  .setFeatureConfig('search', { endpoint: 'http://my-search-API-url' })
+  .build();
+```
+
+::: warning If you do not use the Empathy Search API, you need to build your own adapter. :::
+
+For more information, see
+[Using the Empathy Search Adapter](https://github.com/empathyco/x/tree/main/packages/search-adapter).
+
+## 3. Configure the plugin
+
+Plugins are self-contained code that usually add global-level functionality to Vue projects. They’re
+specifically objects that expose an `install` method, allowing you to keep your components clear and
+small.
+
+The xPlugin is designed to connect the X Components to the Vue components in your project.
+
+**Import** the xPlugin in your Vue instance.
+
+```typescript
+import Vue from 'vue';
+import { xPlugin } from '@empathyco/x-components';
+import { adapter } from './my-adapter';
+import { store } from './my-store';
+```
+
+Then, **configure** the xPlugin. It has two key options you need to configure:
+
+1. **Adapter**: A search adapter is required to connect and communicate with the search API. Here
+   you’re using the `EmpathyAdapterBuilder` to communicate specifically with the Empathy Search API.
+   If you are not using the Empathy Search API, you need to build your own adapter. See
+   [Configure the search adapter](#_2-configure-the-search-adapter).
+
+::: develop
+
+When using your own adapter, remember to configure the `instance`, `language`, `scope`, and
+`endpoint` methods.
+
+:::
+
+2. **Store**: The Vuex store. If you use a store for Vuex, you need to provide the store you’re
+   currently using for your project to the Vue instance.
+
+::: warning
+
+If you don’t provide any parameters for the `store`, a default store is created automatically. Leave
+the `store` blank **only if you’re not using any store** for Vuex.
+
+:::
+
+## 4. Install and initialize the plugin
+
+Finally, the last step is to install and initialize the xPlugin. You need to do this in the
+`main.ts` or `main.js file` of the project.
+
+```typescript
+//Initialize the plugin. Pass the search adapter and the store you use as parameters.
+Vue.use(xPlugin, { adapter, store });
+```
+
+---
+
+### Next steps
+
+Watch how our frontend Team Lead, [Iván Tajes](https://github.com/tajespasarela), integrates the
+Interface X Components in a project from scratch.
+
+<VideoContent 
+title="Want to learn more?"
+source="/assets/media/videos/How-to-use-X-components-in-a-real-project.mp4" 
+poster="/assets/media/videos/How-to-use-X-components-in-a-real-project.jpeg"
+:links="[
+  {
+    title:'Architecture',
+    path:'/develop-empathy-platform/build-search-ui/x-architecture/'
+  },
+  {
+    title:'UI reference',
+    path:'/develop-empathy-platform/ui-reference/'
+  }
+]">
+
+Once you have integrated the Interface&nbsp;X&nbsp;Components in your project, you're ready to start
+building your search and discovery UI:
+
+- Change the configuration of the [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.
+
+</VideoContent>
+
+<!-- Manage [internationalization options](https://github.com/empathyco/x/tree/main/packages/x-translations) to support different languages.-->

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

@@ -0,0 +1,133 @@
+---
+id: x-components.README
+title: README
+sidebar_label: README
+---
+---
+title: How Interface X works
+tags:
+  - x components
+  - interface x
+  - x architecture
+  - architecture
+---
+
+# How Interface X works
+
+<img :src="$withBase('/assets/media/interfacex-architecture.svg')" alt="Interface X architecture">
+
+<FootNote>
+
+Data journey: The frontend components collect user interactions or events. The wiring orchestrates
+the UI events by emitting actions for the client API through the adapter. The API returns the
+required data, travelling to the Vuex store through actions that can modify the app data state in
+the Vuex store with mutation objects. The UI components are bound to the data state, so that they
+render the new state to the user.
+
+</FootNote>
+
+## Understand how the pieces work together
+
+The Interface&nbsp;X architecture is designed into separate tiers and elements:
+
+1.  **Presentation tier**. Mainly represented by the UI **components**, responsible for determining
+    how to display the data. It not only presents data in an understandable manner to users, but
+    also monitors user interactions, emitting events to the Interface&nbsp;X application.
+
+    Components can be customised according to client requirements, even allowing custom CSS styles.
+
+2.  **Orchestration tier**. The x-factor in charge of orchestrating all the event wiring. When an
+    event is emitted, other components are listening to it to react. This behavioural connection
+    between components through events is the **wiring**. Then, the wiring decides what happens when
+    an event is emitted in the Presentation layer.
+
+    The wiring is customisable and flexible to meet client requirements. The behaviour can change
+    without modifying the entire application. The event-driven operators in charge of the wiring
+    routing logic enable different wiring configurations per event.
+
+3.  **Business logic tier**. The heart of the app in charge of keeping all the data processing,
+    where:
+    - UI events emit **actions** for the client API. These actions can modify the state of the
+      store.
+    - The **store** holds all the app data that should be presented to the user at any given time.
+      It acts as a single source of truth, providing great performance and reactivity.
+
+The Interface&nbsp;X app needs an **adapter** to handle all client API communications. The API
+adapter mainly translates the related app data and use models to the client API and vice versa,
+solving any incompatibility issues. It is the entry point for all external data into the
+application.
+
+The API adapter can be customised and extended to meet the client requirements. It’s a plug-in
+element that can be changed and adjusted to the specific client API, even when using other search
+services not based on the Empathy search API.
+
+::: note Architecture patterns  
+If you’re already experienced in the Vue universe, you’ll find the Interface&nbsp;X architecture
+somewhat familiar. Although the [ViewModel layer](https://012.vuejs.org/guide/#Introduction) of the
+**MVVM pattern** sprinkles traces all over the presentation tier, the Interface X architecture is
+basically inspired by the
+[**Flux pattern**](https://vuex.vuejs.org/#what-is-a-state-management-pattern) behind the state. As
+the X&nbsp;Components emit events that dispatch actions in the business logic tier, these actions
+can commit mutations to modify the state of the store.  
+To sum up, the design of Interface&nbsp;X takes advantage of the MVVM and Flux patterns to design,
+develop, and configure each tier separately and independently. :::
+
+## Technical stack
+
+- [Vue.js](https://vuejs.org/) framework
+- JavaScript + [TypeScript](https://www.typescriptlang.org/) languages
+- [RxJS](https://rxjs.dev/) for the wiring configuration logic
+
+**The story so far**  
+Not long ago, exploring alternative options for the architecture design and technical stack became a
+must. There were several design challenges that needed to be overcome to make the frontend service
+easier to configure:
+
+- Improve reusability and performance that were hindered by the logic in components and the bundle
+  size
+- Facilitate setup by solving synchronicity and extendability problems
+- Provide easier maintenance over time, reducing regression issues
+
+After studying different approaches to build fast and reusable components, **Vue.js** (also Vue)
+seemed to be the best fit for the technical requirements and the level of abstraction required.
+
+Revamping the architecture and technical stack has helped the former frontend services to evolve
+into the latest Interface&nbsp;X application. Now, all the required **attributes and design
+principles** are combined to make the solution easy to implement, change, test, and reuse:
+
+- **Flexible**. Make changes to any element without impacting the rest of the app. For example, you
+  can modify a visual component without impacting the business logic.
+- **Customizable & extensible**. Add new custom components andor features.
+- **Lightweight**. The bundle includes only the modules you want. You’ll get only the code you
+  really need.
+- **Incremental**. The modules interact and communicate automatically with each other. The more
+  modules you use, the more features you get.
+- **Easy-to-integrate**. Install the library as an NPM dependency in Vue and React projects.
+  Interface X can be used in any webpage, as long as it is integrated as an isolated search layer.
+
+**Why Vue?**  
+Due to the flexibility required, using a library for the presentation layer instead of a
+full-fledged framework is the best choice. Among the state-of-the-art technologies available for
+building component-based UIs, Vue meets all the requirements:
+
+- Lightweight, flexible, and stand-alone library
+- Easy to learn and use with a user-friendly template syntax
+- Smooth dynamic components and composition creation
+- Outperformance with reactive approach, proxies, and interceptors
+- Out-of-the-box solution, allowing you to focus just on developing features
+- Small bundle size with no dependencies
+
+**How does Vue meet the design challenges?**
+
+- Stateless components. Centralised management through the Vuex library reduces the logic in
+  components.
+- Smooth setups. Dynamic component creation helps to track the modified data and re-render only the
+  required components.
+- Improved performance out of the box
+- Seamless maintenance. Framework or library-agnostic
+
+::: note  
+Interface&nbsp;X can potentially be integrated in commerce shops built with React. In any case,
+Interface&nbsp;X can be used in any webpage, as long as it is integrated as an isolated search
+layer.  
+:::