@empathyco/x-components 3.0.0-alpha.71 → 3.0.0-alpha.72
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/design-system/full-theme.css +12 -13
- package/docs/build-search-ui/README.md +23 -12
- package/docs/build-search-ui/web-archetype-development-guide.md +6 -8
- package/docs/build-search-ui/web-archetype-integration-guide.md +70 -17
- package/docs/build-search-ui/{web-use-x-components-guide.md → web-how-to-use-x-components-guide.md} +1 -1
- package/docs/build-search-ui/web-x-components-integration-guide.md +4 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,19 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file. See
|
|
4
4
|
[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
## [3.0.0-alpha.72](https://github.com/empathyco/x/compare/@empathyco/x-components@3.0.0-alpha.71...@empathyco/x-components@3.0.0-alpha.72) (2022-03-23)
|
|
7
|
+
|
|
8
|
+
### Documentation
|
|
9
|
+
|
|
10
|
+
- Update documentation to differentiate integration from development
|
|
11
|
+
([fc8d9fa](https://github.com/empathyco/x/commit/fc8d9faa57faafee90c0f4da159b6040294c099c)),
|
|
12
|
+
closes [EX-5608](https://searchbroker.atlassian.net/browse/EX-5608)
|
|
13
|
+
|
|
14
|
+
# Change Log
|
|
15
|
+
|
|
16
|
+
All notable changes to this project will be documented in this file. See
|
|
17
|
+
[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
18
|
+
|
|
6
19
|
## [3.0.0-alpha.71](https://github.com/empathyco/x/compare/@empathyco/x-components@3.0.0-alpha.70...@empathyco/x-components@3.0.0-alpha.71) (2022-03-23)
|
|
7
20
|
|
|
8
21
|
### Testing
|
|
@@ -1422,6 +1422,18 @@
|
|
|
1422
1422
|
--x-size-border-radius-bottom-right-input-group-pill: var(--x-size-border-radius-input-group-pill);
|
|
1423
1423
|
--x-size-border-radius-bottom-left-input-group-pill: var(--x-size-border-radius-input-group-pill);
|
|
1424
1424
|
}
|
|
1425
|
+
.x-input--card.x-input,
|
|
1426
|
+
.x-input--card .x-input {
|
|
1427
|
+
--x-size-border-radius-input-default: var(--x-size-border-radius-input-card);
|
|
1428
|
+
--x-size-border-radius-top-left-input-default: var(--x-size-border-radius-top-left-input-card);
|
|
1429
|
+
--x-size-border-radius-top-right-input-default: var(--x-size-border-radius-top-right-input-card);
|
|
1430
|
+
--x-size-border-radius-bottom-right-input-default: var(
|
|
1431
|
+
--x-size-border-radius-bottom-right-input-card
|
|
1432
|
+
);
|
|
1433
|
+
--x-size-border-radius-bottom-left-input-default: var(
|
|
1434
|
+
--x-size-border-radius-bottom-left-input-card
|
|
1435
|
+
);
|
|
1436
|
+
}
|
|
1425
1437
|
:root {
|
|
1426
1438
|
--x-size-border-radius-input-card: var(--x-size-border-radius-base-s);
|
|
1427
1439
|
--x-size-border-radius-top-left-input-card: var(--x-size-border-radius-input-card);
|
|
@@ -7554,16 +7566,3 @@
|
|
|
7554
7566
|
.x-normal-case {
|
|
7555
7567
|
text-transform: none;
|
|
7556
7568
|
}
|
|
7557
|
-
|
|
7558
|
-
.x-input--card.x-input,
|
|
7559
|
-
.x-input--card .x-input {
|
|
7560
|
-
--x-size-border-radius-input-default: var(--x-size-border-radius-input-card);
|
|
7561
|
-
--x-size-border-radius-top-left-input-default: var(--x-size-border-radius-top-left-input-card);
|
|
7562
|
-
--x-size-border-radius-top-right-input-default: var(--x-size-border-radius-top-right-input-card);
|
|
7563
|
-
--x-size-border-radius-bottom-right-input-default: var(
|
|
7564
|
-
--x-size-border-radius-bottom-right-input-card
|
|
7565
|
-
);
|
|
7566
|
-
--x-size-border-radius-bottom-left-input-default: var(
|
|
7567
|
-
--x-size-border-radius-bottom-left-input-card
|
|
7568
|
-
);
|
|
7569
|
-
}
|
|
@@ -24,9 +24,10 @@ Start building your search and discovery experience in a few simple steps:
|
|
|
24
24
|
|
|
25
25
|
- **Discover more about the [Interface X ecosystem](#the-interface-x-ecosystem)** and how
|
|
26
26
|
Interface X works.
|
|
27
|
-
- **[Integrate the Interface X
|
|
27
|
+
- **[Integrate the Interface X Archetype](#integrate-interface-x-archetype)** in your store web
|
|
28
28
|
application.
|
|
29
|
-
- **[
|
|
29
|
+
- **[Develop using the Interface X](#develop-with-interface-x)** inside your current project.
|
|
30
|
+
- **[How to use and configure the Interface X Components](#how-to-use-and-configure-the-interface-x-components)**
|
|
30
31
|
in your project.
|
|
31
32
|
|
|
32
33
|
<!-- 3. Style your UI. 4. Translate your search experience-->
|
|
@@ -42,11 +43,21 @@ numerous components to choose from, and the catalog evolves quickly with new exp
|
|
|
42
43
|
Check out the **[open source project in GitHub](https://github.com/empathyco/x)**.
|
|
43
44
|
|
|
44
45
|
Interested in learning more about how Interface X works? Discover more about its
|
|
45
|
-
**[architecture](
|
|
46
|
+
**[architecture](x-architecture/README.md)**.
|
|
46
47
|
|
|
47
|
-
## Integrate Interface X
|
|
48
|
+
## Integrate Interface X Archetype
|
|
48
49
|
|
|
49
|
-
|
|
50
|
+
Once you have finished developing or extending your search interface using the
|
|
51
|
+
Interface X Archetype project you will probably want to integrate it into your current
|
|
52
|
+
store. The integration of an existing Archetype into your project is pretty straightforward. You
|
|
53
|
+
will need to load the generated Javascript into your website and initialise it.
|
|
54
|
+
|
|
55
|
+
To start integrating an existent Archetype into your project please visit
|
|
56
|
+
[extended guide about Archetype integration](web-archetype-integration-guide.md).
|
|
57
|
+
|
|
58
|
+
## Develop with Interface X
|
|
59
|
+
|
|
60
|
+
You can use the Interface X in a project in two ways:
|
|
50
61
|
|
|
51
62
|
- using the separate **Interface X Archetype** project, an out-of-the-box project with all
|
|
52
63
|
you need to get up and running fast, or
|
|
@@ -59,7 +70,7 @@ You can use Empathy Search API, Elasticsearch, or Solr endpoints with both appro
|
|
|
59
70
|
|
|
60
71
|
:::
|
|
61
72
|
|
|
62
|
-
#####
|
|
73
|
+
##### Develop via Interface X Archetype
|
|
63
74
|
|
|
64
75
|
The **[Interface X Archetype](https://github.com/empathyco/x-archetype)** project is the
|
|
65
76
|
perfect combination of all the existing X Components. Instead of starting from a completely
|
|
@@ -74,10 +85,10 @@ perfect solution for most cases. But don’t worry! It’s still super flexible!
|
|
|
74
85
|
- Use the individual X Component internationalization tool or use your own tool.
|
|
75
86
|
- Create new components or modify the existing ones.
|
|
76
87
|
|
|
77
|
-
To start
|
|
78
|
-
**[
|
|
88
|
+
To start developing the X Archetype project, see
|
|
89
|
+
**[Develop via Interface X Archetype](web-archetype-development-guide.md)**.
|
|
79
90
|
|
|
80
|
-
#####
|
|
91
|
+
##### Develop via Interface X Components library
|
|
81
92
|
|
|
82
93
|
This is the more deep and flexible use of the
|
|
83
94
|
**[Interface X Components library](https://github.com/empathyco/x/tree/main/packages/x-components)**,
|
|
@@ -91,9 +102,9 @@ go if you like to look under the hood!
|
|
|
91
102
|
- Determine styles using design tokens or custom CSS.
|
|
92
103
|
|
|
93
104
|
To get started with the X Components library, check out
|
|
94
|
-
**[
|
|
105
|
+
**[Develop using Interface X Components library](web-x-components-integration-guide.md)**.
|
|
95
106
|
|
|
96
|
-
##
|
|
107
|
+
## How to use and configure the Interface X Components
|
|
97
108
|
|
|
98
109
|
Using the Interface X Components is a piece of cake! Just import and register the
|
|
99
110
|
component, include it in your template, and you’re ready to go! What’s more, each component offers
|
|
@@ -101,7 +112,7 @@ multiple configuration parameters to play around with, allowing you greater flex
|
|
|
101
112
|
experience.
|
|
102
113
|
|
|
103
114
|
Unsure how to start? Check out
|
|
104
|
-
**[
|
|
115
|
+
**[How to use & configure Interface X Components in your project](web-how-to-use-x-components-guide.md)**.
|
|
105
116
|
|
|
106
117
|
<!--
|
|
107
118
|
## Style your UI
|
|
@@ -77,13 +77,10 @@ Then, replace the current repository name (`@empathyco/x-archetype`) with the na
|
|
|
77
77
|
repository in the `package.json` file.
|
|
78
78
|
|
|
79
79
|
```json
|
|
80
|
-
// Define your repository
|
|
81
80
|
{
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
}
|
|
86
|
-
|
|
81
|
+
"name": "<your-repo>",
|
|
82
|
+
"author": "Empathy Systems Corporation S.L."
|
|
83
|
+
}
|
|
87
84
|
```
|
|
88
85
|
|
|
89
86
|
## 2. Install the dependencies and execute the project
|
|
@@ -116,7 +113,7 @@ configurations, or mappers that points to a demo environment. You need to make s
|
|
|
116
113
|
the configuration according to the search features you use in your project.
|
|
117
114
|
|
|
118
115
|
Export the required search adapter with your configuration as you will need it for the search
|
|
119
|
-
[xPlugin configuration](
|
|
116
|
+
[xPlugin configuration](#4-configure-the-plugin).
|
|
120
117
|
|
|
121
118
|
::: interact
|
|
122
119
|
|
|
@@ -178,7 +175,8 @@ Once you have your Interface X Archetype project, you're ready to inte
|
|
|
178
175
|
store, or extend the search and discovery experience to meet your business needs:
|
|
179
176
|
|
|
180
177
|
- [Integrate an Interface X Archetype project into an existing website](web-archetype-integration-guide.md).
|
|
181
|
-
- Change the configuration of [X Components](web-use-x-components-guide.md) or create new
|
|
178
|
+
- Change the configuration of [X Components](web-how-to-use-x-components-guide.md) or create new
|
|
179
|
+
ones.
|
|
182
180
|
- Adapt the
|
|
183
181
|
[design system](https://github.com/empathyco/x/blob/main/packages/x-components/contributing/design-system.md)
|
|
184
182
|
to your branding.
|
|
@@ -24,6 +24,14 @@ The integration is a 2-steps process:
|
|
|
24
24
|
Depending on your business needs, there are 2 different ways of making this integration process:
|
|
25
25
|
auto initialising, or initialising on demand.
|
|
26
26
|
|
|
27
|
+
::: note Frameworks & Libraries Integration
|
|
28
|
+
|
|
29
|
+
As the Archetype is bundled including all the needed dependencies, then it is possible to integrate
|
|
30
|
+
on top of any existing website, regardless of the technologies that it has been built with:
|
|
31
|
+
**React**, **Vue**, **Svelte**...
|
|
32
|
+
|
|
33
|
+
:::
|
|
34
|
+
|
|
27
35
|
## Auto initialisation
|
|
28
36
|
|
|
29
37
|
This is the easiest way to integrate the Interface X project in a website. The way to do so is
|
|
@@ -161,26 +169,71 @@ invoked at any time. Note that you should only call this function **once**.
|
|
|
161
169
|
The snippet configuration allows you to configure certain parts of the Interface X project like
|
|
162
170
|
language, the currency, inform whether the user has given us his consent to process personal data.
|
|
163
171
|
|
|
164
|
-
| Name
|
|
165
|
-
|
|
|
166
|
-
| instance
|
|
167
|
-
| env
|
|
168
|
-
| scope
|
|
169
|
-
| lang
|
|
170
|
-
| searchLang
|
|
171
|
-
| consent
|
|
172
|
-
| documentDirection
|
|
173
|
-
| currency
|
|
174
|
-
| callbacks
|
|
175
|
-
| isSpa
|
|
176
|
-
| <extra parameters>
|
|
172
|
+
| Name | Type | Required | Description |
|
|
173
|
+
| ----------------------- | ------------------------------------------------------------------------------------ | :------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
174
|
+
| instance | `string` | ✅ | The identifier of the API client instance. Should be provided by Empathy |
|
|
175
|
+
| env | `'live'` | `'staging'` | | The API environment to use. Note that you can use the production version of your Interface X with the staging API, or viceversa. |
|
|
176
|
+
| scope | `string` | | The context name where the search interface is being executed. I.e. `mobile`, `mobile-app`, `tablet`, `desktop` |
|
|
177
|
+
| lang | `string` | ✅ | The language to use. By default this lang is used for both the front-end and the API requests |
|
|
178
|
+
| searchLang | `string` | | A language to use only for the API requests |
|
|
179
|
+
| consent | `boolean` | ✅ | Used to let X know whether the user has accepted the usage of cookies and therefore the sessionId can be used and sent to the Search and Tagging API. If this parameter is configured with false value, then the sessionId in not generated nor sent to the Tagging API. No consent means the wisdom of the crowd signals (Related Tags, Next Queries, etc.) will not be inferred from that session. This parameter should be set to true as soon as the user accepts the usage of Customer cookies but note that Empathy not uses any cookie in its libraries, although we tie the cookie acceptance to the sessionID generation in Local Storage. If accepting the cookies does not trigger a page reload, please consider using `window.initX.consent = true` to update the consent parameter so that the current session is tracked already. |
|
|
180
|
+
| documentDirection | `'ltr'` | `'rtl'` | | The writing direction that the X Components should use |
|
|
181
|
+
| currency | `string` | ✅ | The currency identifier. Used to configure how prices are shown |
|
|
182
|
+
| [callbacks](#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); }` |
|
|
183
|
+
| isSpa | `boolean` | | True when the X Components archetype is being run on top of an SPA. |
|
|
184
|
+
| <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. |
|
|
185
|
+
|
|
186
|
+
### Callbacks
|
|
187
|
+
|
|
188
|
+
As the callbacks are a powerful tool in the initialisation options, we provide this section to get
|
|
189
|
+
deep in their use. This is an example of initialisation providing callbacks to subscribe to certain
|
|
190
|
+
events.
|
|
191
|
+
|
|
192
|
+
```html
|
|
193
|
+
<script src="https://x.empathy.co/my-store/app.js"></script>
|
|
194
|
+
<script>
|
|
195
|
+
window.X.init({
|
|
196
|
+
instance: 'my-store',
|
|
197
|
+
env: 'live',
|
|
198
|
+
scope: 'desktop',
|
|
199
|
+
lang: 'en',
|
|
200
|
+
currency: 'EUR',
|
|
201
|
+
consent: false,
|
|
202
|
+
callbacks: {
|
|
203
|
+
UserAcceptedAQuery: query => {
|
|
204
|
+
doSomethingInWebApp(query);
|
|
205
|
+
},
|
|
206
|
+
UserClickedResultAddToCart: result => {
|
|
207
|
+
addToCartInWebApp(result);
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
});
|
|
211
|
+
</script>
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
In this example we are subscribing to `UserAcceptedAQuery` and `UserClickedResultAddToCart` so in
|
|
215
|
+
this way we can perform an action inside our application when these events are triggered. Even
|
|
216
|
+
though we have subscribed to two events, as Interface X Components is an event based architecture
|
|
217
|
+
there are more than one hundred of events available to be subscribed to. The complete list is not
|
|
218
|
+
yet part of this documentation, but you may access to the
|
|
219
|
+
[XEventsTypes](https://github.com/empathyco/x/blob/main/packages/x-components/src/wiring/events.types.ts)
|
|
220
|
+
where all of them are defined.
|
|
221
|
+
|
|
222
|
+
::: note
|
|
223
|
+
|
|
224
|
+
The XEventsTypes are those that can be triggered from different modules inside the X Components, but
|
|
225
|
+
have in mind that every module has its own sort of components. So have a look to DeviceXEvents,
|
|
226
|
+
EmpathizeXEvents, SearchBoxXEvents, etc.
|
|
227
|
+
|
|
228
|
+
:::
|
|
177
229
|
|
|
178
230
|
## X API
|
|
179
231
|
|
|
180
232
|
The X API allows your website to communicate with Interface X. It is a set of utilities that helps
|
|
181
233
|
to integrate Interface X into your website.
|
|
182
234
|
|
|
183
|
-
| Function
|
|
184
|
-
|
|
|
185
|
-
| init
|
|
186
|
-
| search
|
|
235
|
+
| Function | Parameters | Description |
|
|
236
|
+
| ---------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
237
|
+
| init | - [Snippet Configuration](#snippet-configuration) - The initialisation options | [Initialises Interface X on demand](#initialise-on-demand). |
|
|
238
|
+
| search | - query (Optional) - The query to open Interface X with | Opens Interface X and triggers a search with the given query. |
|
|
239
|
+
| setSnippetConfig | - [Snippet Configuration](#snippet-configuration) - The Initialisation options | Changes the options and all components react to the changes. Useful, for example, to change both search engine and displayed language without reloading the page. |
|
package/docs/build-search-ui/{web-use-x-components-guide.md → web-how-to-use-x-components-guide.md}
RENAMED
|
@@ -13,7 +13,7 @@ search UI experiences. The goal of using components is to include only the compo
|
|
|
13
13
|
wherever you want. So, **just import the components, register, and go!**
|
|
14
14
|
|
|
15
15
|
Once you’ve installed the
|
|
16
|
-
[dependencies and the xPlugin](web-x-components-integration-guide.md#
|
|
16
|
+
[dependencies and the xPlugin](web-x-components-integration-guide.md#1-install-the-dependencies),
|
|
17
17
|
you’re ready to use X Components in your project.
|
|
18
18
|
|
|
19
19
|
## 1. Import and register the X Components
|
|
@@ -35,6 +35,8 @@ To integrate the X Components in a frontend UI, you need:
|
|
|
35
35
|
- **Empathy Search API** to retrieve search data (or any other search API)
|
|
36
36
|
- A **search adapter** to communicate with the search API. You can use the Empathy Adapter and
|
|
37
37
|
configure it with the `EmpathyAdapterBuilder`
|
|
38
|
+
- You must be working on a **Vue** project, or on a **React** project using the
|
|
39
|
+
[React Wrapper](https://github.com/empathyco/x/tree/main/packages/react-wrapper).
|
|
38
40
|
|
|
39
41
|
:::
|
|
40
42
|
|
|
@@ -193,7 +195,8 @@ poster="/assets/media/videos/How-to-use-X-components-in-a-real-project.jpeg"
|
|
|
193
195
|
Once you have integrated the Interface X Components in your project, you're ready to start
|
|
194
196
|
building your search and discovery UI:
|
|
195
197
|
|
|
196
|
-
- Change the configuration of the [X Components](web-use-x-components-guide.md) or create new
|
|
198
|
+
- Change the configuration of the [X Components](web-how-to-use-x-components-guide.md) or create new
|
|
199
|
+
ones.
|
|
197
200
|
- Adapt the
|
|
198
201
|
[design system](https://github.com/empathyco/x/blob/main/packages/x-components/contributing/design-system.md)
|
|
199
202
|
to your branding.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@empathyco/x-components",
|
|
3
|
-
"version": "3.0.0-alpha.
|
|
3
|
+
"version": "3.0.0-alpha.72",
|
|
4
4
|
"description": "Empathy X Components",
|
|
5
5
|
"author": "Empathy Systems Corporation S.L.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -127,5 +127,5 @@
|
|
|
127
127
|
"access": "public",
|
|
128
128
|
"directory": "dist"
|
|
129
129
|
},
|
|
130
|
-
"gitHead": "
|
|
130
|
+
"gitHead": "7e53bc3ca696b6129614ed2618a8e6036713a90d"
|
|
131
131
|
}
|