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

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

@@ -0,0 +1,168 @@
+---
+id: x-components.x-components.scroll
+title: Scroll
+sidebar_label: Scroll
+---
+# scroll
+
+> Base scroll component that depending on base scroll component and the user interaction emits
+> different x events for knowing when the user scrolls, the direction of scroll and if user
+> reaches the start or end.
+
+## Props
+
+| Name                          | Description                                                                                                                                                   | Type                | Default                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ------------------------- |
+| <code>throttleMs</code>       | Time duration to ignore the subsequent scroll events after an emission.<br />Higher values will decrease events precision but can prevent performance issues. | <code>number</code> | <code></code>             |
+| <code>distanceToBottom</code> | Distance to the end of the scroll that when reached will emit the<br />`scroll:about-to-end` event.                                                           | <code>number</code> | <code></code>             |
+| <code>id</code>               | Id to identify the component.                                                                                                                                 | <code>string</code> | <code>MainScrollId</code> |
+
+## Slots
+
+| Name                 | Description | Bindings<br />(name - type - description) |
+| -------------------- | ----------- | ----------------------------------------- |
+| <code>default</code> |             | None                                      |
+
+---
+
+# Example
+
+The Scroll is a component that wraps the BaseScroll and provides it for a unique id.
+
+## Events
+
+A list of events that the component will emit:
+
+- `UserScrolled`: emitted after the user scrolls in this container. The payload is the scroll top
+  distance in pixels.
+- `UserChangedScrollDirection`: emitted when the user changes the scroll direction. The payload is
+  the new scrolling direction.
+- `UserReachedScrollStart`: emitted when the user scrolls up to the initial position of the scroll.
+- `UserAlmostReachedScrollEnd`: emitted when the user is about to reach the bottom part of the
+  scroll.
+- `UserReachedScrollEnd`: emitted when the user has reached the bottom part of the scroll.
+
+## Customized usage
+
+### Overriding the properties
+
+It renders an element with scroll, with the content passed in the `default slot`.
+
+```vue
+<template>
+  <Scroll id="exampleScrollId" throttleMs="50" distanceToBottom="300">
+    <div class="content-scroll">
+      <span>content1</span>
+      <span>content1</span>
+    </div>
+  </Scroll>
+</template>
+
+<script>
+import { Scroll } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "ScrollIdTest",
+  components: {
+    Scroll
+  }
+};
+</script>
+```
+
+## Customized usage
+
+### Using scroll events.
+
+```vue
+<template>
+  <Scroll
+    @scroll="scroll"
+    @scroll:direction-change="scrollDirectionChange"
+    @scroll:at-start="scrollAtStart"
+    @scroll:almost-at-end="scrollAlmostAtEnd"
+    @scroll:at-end="scrollAtEnd"
+    id="exampleScrollId"
+    throttleMs="50"
+    distanceToBottom="300"
+  >
+    <div class="content-scroll">
+      <span>content1</span>
+      <span>content1</span>
+    </div>
+  </Scroll>
+</template>
+
+<script>
+import { Scroll } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "ScrollIdTest",
+  components: {
+    Scroll
+  },
+  methods: {
+    scroll(position) {
+      console.log("scroll", position);
+    },
+    scrollDirectionChange(direction) {
+      console.log("scroll:direction-change", direction);
+    },
+    scrollAtStart(isAtStart) {
+      console.log("scroll:at-start", isAtStart);
+    },
+    scrollAlmostAtEnd(isAlmostAtEnd) {
+      console.log("scroll:almost-at-end", isAlmostAtEnd);
+    },
+    scrollAtEnd(isAtEnd) {
+      console.log("scroll:at-end", isAtEnd);
+    }
+  }
+};
+</script>
+```
+
+## Customized usage
+
+### Using XEvents.
+
+You can use the XEvents subscribing to them.
+
+```vue
+<template>
+  <Scroll throttleMs="50" distanceToBottom="300">
+    <div class="content-scroll">
+      <span>content1</span>
+      <span>content1</span>
+    </div>
+  </Scroll>
+</template>
+
+<script>
+import { Scroll } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "ScrollIdTest",
+  components: {
+    Scroll
+  },
+  mounted() {
+    this.$x.on("UserScrolled").subscribe(distance => {
+      console.log(distance);
+    });
+    this.$x.on("UserChangedScrollDirection").subscribe(direction => {
+      console.log(direction);
+    });
+    this.$x.on("UserReachedScrollStart").subscribe(isAtStart => {
+      console.log(isAtStart);
+    });
+    this.$x.on("UserAlmostReachedScrollEnd").subscribe(isAlmostAtEnd => {
+      console.log(isAlmostAtEnd);
+    });
+    this.$x.on("UserReachedScrollEnd").subscribe(isAtEnd => {
+      console.log(isAtEnd);
+    });
+  }
+};
+</script>
+```

package/docs/API-reference/components/scroll/x-components.window-scroll.md

@@ -0,0 +1,158 @@
+---
+id: x-components.x-components.window-scroll
+title: Window Scroll
+sidebar_label: Window Scroll
+---
+# window-scroll
+
+> The `WindowScroll` component listens to either the `html` or `body` DOM scroll events, and
+> re-emits them as X Events. Additionally it also emits events related to the direction or
+> current position of these elements scroll.
+
+## Props
+
+| Name                           | Description                                  | Type                           | Default                   |
+| ------------------------------ | -------------------------------------------- | ------------------------------ | ------------------------- |
+| <code>scrollableElement</code> | Tag to identify the main scrollable element. | <code>ScrollableElement</code> | <code>'html'</code>       |
+| <code>id</code>                | Id to identify the component.                | <code>string</code>            | <code>MainScrollId</code> |
+
+---
+
+# Example
+
+The `WindowScroll` component manages the scroll state of the `body` or `html` elements. It does the
+necessary calculations for knowing the direction of scroll, if the scroll has reached its starting
+position, if it is about to reach its ending position or if it has already reached it end. Whenever
+this state changes, it emits the appropiate X Event to the rest of the application
+
+## Custom usage
+
+### Overriding the properties and using document scroll events.
+
+```vue
+<template>
+  <WindowScroll
+    @scroll="scroll"
+    @scroll:direction-change="scrollDirectionChange"
+    @scroll:at-start="scrollAtStart"
+    @scroll:almost-at-end="scrollAlmostAtEnd"
+    @scroll:at-end="scrollAtEnd"
+    id="example-main-scroll"
+    throttleMs="100"
+    distanceToBottom="300"
+    scrollableElement="body"
+  />
+</template>
+
+<script>
+import { WindowScroll } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "ScrollIdTest",
+  components: {
+    WindowScroll
+  },
+  methods: {
+    scroll(position) {
+      console.log("scroll", position);
+    },
+    scrollDirectionChange(direction) {
+      console.log("scroll:direction-change", direction);
+    },
+    scrollAtStart() {
+      console.log("scroll:at-start", isAtStart);
+    },
+    scrollAlmostAtEnd(isAlmostAtEnd) {
+      console.log("scroll:almost-at-end", isAlmostAtEnd);
+    },
+    scrollAtEnd(isAtEnd) {
+      console.log("scroll:at-end", isAtEnd);
+    }
+  }
+};
+</script>
+```
+
+## Customized usage
+
+### Using body and XEvents.
+
+If we want to listen scroll body we should do some changes in css for body. This is an example, so
+therefore the height of body can be get any value that you want. The template style should have a
+similar styles the corresponding style for tag body like in the next example.
+
+```vue
+<template>
+  <WindowScroll
+    id="example-main-scroll"
+    throttleMs="100"
+    distanceToBottom="300"
+    scrollableElement="body"
+  />
+</template>
+
+<script>
+import { WindowScroll } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "MainComponent",
+  components: {
+    WindowScroll
+  },
+  mounted() {
+    this.$x.on("UserScrolled").subscribe(distance => {
+      console.log(distance);
+    });
+    this.$x.on("UserChangedScrollDirection").subscribe(direction => {
+      console.log(direction);
+    });
+    this.$x.on("UserReachedScrollStart").subscribe(isAtStart => {
+      console.log(isAtStart);
+    });
+    this.$x.on("UserAlmostReachedScrollEnd").subscribe(isAlmostAtEnd => {
+      console.log(isAlmostAtEnd);
+    });
+    this.$x.on("UserReachedScrollEnd").subscribe(isAtEnd => {
+      console.log(isAtEnd);
+    });
+  }
+};
+</script>
+<style lang="scss">
+html {
+  overflow: hidden;
+}
+
+body {
+  overflow-y: auto;
+  height: 100vh;
+}
+</style>
+```
+
+## Vue Events:
+
+- `scroll`: the event is emitted after the user scrolls in this container. The payload is the scroll
+  top distance in pixels.
+- `scroll:direction-change`: the event is emitted when the user changes the scroll direction. The
+  payload is the new scrolling direction.
+- `scroll:at-start`: the event is emitted when the user scrolls up to the initial position of the
+  scroll.
+- `scroll:almost-at-end`: the event is emitted when the user is about to reach the bottom part of
+  the scroll.
+- `scroll:at-end`: the event is emitted when the user has reached the bottom part of the scroll.
+
+## Events
+
+A list of events that the component will emit:
+
+- `UserScrolled`: the event is emitted after the user scrolls in this container. The payload is the
+  scroll top distance in pixels.
+- `UserChangedScrollDirection`: the event is emitted when the user changes the scroll direction. The
+  payload is the new scrolling direction.
+- `UserReachedScrollStart`: the event is emitted when the user scrolls up to the initial position of
+  the scroll.
+- `UserAlmostReachedScrollEnd`: the event is emitted when the user is about to reach the bottom part
+  of the scroll.
+- `UserReachedScrollEnd`: the event is emitted when the user has reached the bottom part of the
+  scroll.

package/docs/API-reference/components/search/x-components.redirection.md

@@ -0,0 +1,99 @@
+---
+id: x-components.x-components.redirection
+title: Redirection
+sidebar_label: Redirection
+---
+# redirection
+
+> A redirection is a component that sends the user to a link in the website. It is helpful when
+> there are queries like `help`, `shipping costs`, `my account`, where a link to a section in the
+> website will be more helpful than the set of results returned.
+
+## Props
+
+| Name                        | Description                                                                         | Type                | Default             |
+| --------------------------- | ----------------------------------------------------------------------------------- | ------------------- | ------------------- |
+| <code>mode</code>           | The redirection mode. Auto for auto redirection and manual for an user interaction. | <code>string</code> | <code>'auto'</code> |
+| <code>delayInSeconds</code> | The waiting time in seconds until the redirection is made.                          | <code>number</code> | <code>0</code>      |
+
+## Slots
+
+| Name                 | Description | Bindings<br />(name - type - description) |
+| -------------------- | ----------- | ----------------------------------------- |
+| <code>default</code> |             | <br /><br /><br /><br />                  |
+
+---
+
+### Play with the component
+
+In this example, a query has been searched in the search input resulting in a case where the
+response has a redirection.
+
+A text box appears bellow the search box indicating that you're going to be redirected to another
+web page.
+
+This component has two modes:
+
+- Auto mode means that the redirection will occur after a certain number of seconds passed as a
+  property.
+- If the value is 0 the redirection will be instantly.
+- Manual mode means that the user have to click the redirect button or nothing will happen.
+
+_Type any term in the input field to try it out!_
+
+```vue
+<template>
+  <Redirection #default="{ redirection, redirect, abortRedirect }">
+    <span>In a few seconds you're going to be redirected!</span>
+    <span>{{ redirection.url }}</span>
+    <button @click="redirection">Redirect now!</button>
+    <button @click="abortRedirect">Abort redirection!</button>
+  </Redirection>
+</template>
+
+<script>
+import { Redirection } from "@empathyco/x-components/search";
+export default {
+  name: "RedirectionDemo",
+  components: {
+    Redirection
+  }
+};
+</script>
+```
+
+## Extending the component
+
+Components behaviour can be changed, in this example the mode of the component will be manual
+forcing the user to accept the redirection
+
+```vue
+<template>
+  <Redirection #default="{ redirection, redirect }">
+    <span>{{ redirection.url }}</span>
+    <button @click="redirect">Redirect now!</button>
+  </Redirection>
+</template>
+
+<script>
+import { Redirection } from "@empathyco/x-components/search";
+export default {
+  name: "RedirectionDemo",
+  components: {
+    Redirection
+  },
+  data() {
+    return {
+      mode: "manual"
+    };
+  }
+};
+</script>
+```
+
+## Events
+
+This component emits the following events:
+
+- `UserClickedARedirection` after the user clicks the redirection button.
+- `UserClickedAbortARedirection` after the user clicks the abort redirection button.

package/docs/API-reference/components/search/x-components.sort-dropdown.md

@@ -10,11 +10,10 @@ sidebar_label: Sort Dropdown
 
 ## Props
 
-| Name                   | Description                                                                                                                                                                                                       | Type               | Default       |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------- |
-| <code>items</code>     | The list of possible sort values. If the {@link SortMixin.value} option<br />is not provided, the first item of this list will be selected.                                                                       | <code>Array</code> | <code></code> |
-| <code>value</code>     | The selected sort value. This is an optional prop that allows to change programmatically<br />the selected sort. If it is not provided, the first item of the {@link SortMixin.items}<br />list will be selected. | <code>Sort</code>  | <code></code> |
-| <code>animation</code> | The transition to use for opening and closing the dropdown.                                                                                                                                                       | <code>union</code> | <code></code> |
+| Name                   | Description                                                                                                           | Type               | Default       |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------- |
+| <code>items</code>     | The list of possible sort values. If there are no values selected, the first item of<br />this list will be selected. | <code>Array</code> | <code></code> |
+| <code>animation</code> | The transition to use for opening and closing the dropdown.                                                           | <code>union</code> | <code></code> |
 
 ## Events
 

package/docs/API-reference/components/search/x-components.sort-list.md

@@ -10,11 +10,10 @@ sidebar_label: Sort List
 
 ## Props
 
-| Name                   | Description                                                                                                                                                                                                       | Type               | Default           |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------- |
-| <code>items</code>     | The list of possible sort values. If the {@link SortMixin.value} option<br />is not provided, the first item of this list will be selected.                                                                       | <code>Array</code> | <code></code>     |
-| <code>value</code>     | The selected sort value. This is an optional prop that allows to change programmatically<br />the selected sort. If it is not provided, the first item of the {@link SortMixin.items}<br />list will be selected. | <code>Sort</code>  | <code></code>     |
-| <code>animation</code> | The transition to use for rendering the list.                                                                                                                                                                     | <code>union</code> | <code>'ul'</code> |
+| Name                   | Description                                                                                                           | Type               | Default           |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------- |
+| <code>items</code>     | The list of possible sort values. If there are no values selected, the first item of<br />this list will be selected. | <code>Array</code> | <code></code>     |
+| <code>animation</code> | The transition to use for rendering the list.                                                                         | <code>union</code> | <code>'ul'</code> |
 
 ## Slots
 

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

@@ -0,0 +1,84 @@
+---
+id: x-components.x-components.tagging
+title: Tagging
+sidebar_label: Tagging
+---
+# tagging
+
+## Props
+
+| Name                                | Description                                           | Type                 | Default       |
+| ----------------------------------- | ----------------------------------------------------- | -------------------- | ------------- |
+| <code>sessionTTLMs</code>           | The session TTL in milliseconds.                      | <code>union</code>   | <code></code> |
+| <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:
+
+- [`ConsentProvided`](./../../api/x-components.taggingxevents.consentprovided.md)
+- [`SessionDurationProvided`](./../../api/x-components.taggingxevents.sessiondurationprovided.md)
+- `QueryTaggingDebounceProvided`[1][1](./../../api/x-components.taggingxevents.querytaggingdebounceprovided.md)
+
+## See it in action
+
+This component manages the tagging of the API to track the different features. This component
+doesn't render elements to the DOM.
+
+```vue
+<template>
+  <Tagging />
+</template>
+
+<script>
+import { Tagging } from "@empathyco/x-components/tagging";
+
+export default {
+  name: "TaggingDemo",
+  components: {
+    Tagging
+  }
+};
+</script>
+```
+
+### Play with props
+
+In this example, the `Tagging` component will emit `ConsentProvided` with payload false by default
+if the consent is not provided, the `SessionDurationProvided` and `QueryTaggingDebounceProvided`
+events will be emitted only if the props are defined.
+
+```vue
+<template>
+  <Tagging
+    :consent="true"
+    :queryTaggingDebounceMs="300"
+    :sessionDurationMs="30000"
+  />
+</template>
+
+<script>
+import { Tagging } from "@empathyco/x-components/tagging";
+
+export default {
+  name: "TaggingDemo",
+  components: {
+    Tagging
+  }
+};
+</script>
+```
+
+### Play with events
+
+The `Tagging` will emit the `ConsentProvided` when the component is loaded and the consent is set by
+the prop or getting the value from the snippet config.
+
+The `Tagging` will emit the `SessionDurationProvided` when the component is loaded with a session
+duration using the prop.
+
+The `Tagging` will emit the `QueryTaggingDebounceProvided` when the component is loaded with query
+debounce using the prop.

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

@@ -5,6 +5,10 @@ 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.
+
 ---
 
 ## Events
@@ -12,12 +16,14 @@ sidebar_label: Url Handler
 This component emits the following events:
 
 - [`ParamsLoadedFromUrl`](./../../api/x-components.urlxevents.paramsloadedfromurl.md)
+- [`ExtraParamsLoadedFromUrl`](./../../api/x-components.urlxevents.extraparamsloadedfromurl.md)
 - [`UserOpenXProgrammatically`](./../../api/x-components.xeventstypes.useropenxprogrammatically.md)
 
 ## See it in action
 
-This component doesn't render elements to the DOM, but serves as a way to easily change the default
-url parameter names.
+This component manages the browser URL parameters to preserve 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.
 
 _Try to make some requests and take a look to the url!_
 
@@ -69,3 +75,9 @@ export default {
 ### Play with events
 
 The `UrlHandler` will emit the `ParamsLoadedFromUrl` when the page is loaded.
+
+The `UrlHandler` will emit the `ExtraParamsLoadedFromUrl` when the page is loaded with an extra
+param configured and with a value in URL.
+
+The `UrlHandler` will emit the `UserOpenXProgrammatically` when the page is loaded with a query in
+the URL.