@empathyco/x-components 3.0.0-alpha.29 → 3.0.0-alpha.32

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

@@ -0,0 +1,175 @@
+---
+id: x-components.x-components.main-scroll
+title: Main Scroll
+sidebar_label: Main Scroll
+---
+# main-scroll
+
+> Extends the scroll making it able to sync the first visible element, and allowing
+> the children position to be restored.
+
+Each child element that wants to have this support must be wrapped in a {@link MainScrollItem}
+component.
+
+## Props
+
+| Name                                | Description                                                                                                                                                                                                                                                | Type                 | Default            |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------------------ |
+| <code>useWindow</code>              | If `true`, sets this scroll instance to the main of the application. Being the main<br />scroll implies that features like restoring the scroll when the query changes, or storing<br />the scroll position in the URL will be enabled for this container. | <code>boolean</code> | <code>false</code> |
+| <code>restoreScrollTimeoutMs</code> | Timeout in milliseconds to abort trying to restore the scroll position to the target<br />element.                                                                                                                                                         | <code>number</code>  | <code>5000</code>  |
+| <code>threshold</code>              | Intersection percentage to consider an element visible.                                                                                                                                                                                                    | <code>number</code>  | <code>0.3</code>   |
+| <code>margin</code>                 | Adjusts the size of the scroll container bounds.                                                                                                                                                                                                           | <code>string</code>  | <code>''</code>    |
+
+## Slots
+
+| Name                 | Description | Bindings<br />(name - type - description) |
+| -------------------- | ----------- | ----------------------------------------- |
+| <code>default</code> |             | None                                      |
+
+---
+
+## Events
+
+This component emits the following events:
+
+[`UserScrolledToElement`](./../../api/x-components.scrollxevents.md)
+[`ScrollRestoreFailed`](./../../api/x-components.scrollxevents.md)
+
+## See it in action
+
+The `MainScroll` component must be an ancestor of the `MainScrollItem` components. This is because
+it injects the needed utilities to determine the first visible item.
+
+```vue
+<template>
+  <MainScroll>
+    <ul>
+      <MainScrollItem v-for="item in 24" tag="li"
+        >Item {{ item }}</MainScrollItem
+      >
+    </ul>
+  </MainScroll>
+</template>
+
+<script>
+import { MainScroll, MainScrollItem } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "MainScrollDemo",
+  components: {
+    MainScroll,
+    MainScrollItem
+  }
+};
+</script>
+
+<style scoped>
+ul {
+  overflow: auto;
+  max-height: 200px;
+}
+
+li {
+  height: 50px;
+  line-height: 50px;
+}
+</style>
+```
+
+### Play with props
+
+#### Window scroll
+
+In case you aren't using a custom scrolling element like the `Scroll` panel, and want to use the
+default browser scroll, you can do so by using the `useWindow` prop:
+
+```vue
+<template>
+  <MainScroll useWindow>
+    <ul>
+      <MainScrollItem v-for="item in 24" tag="li"
+        >Item {{ item }}</MainScrollItem
+      >
+    </ul>
+  </MainScroll>
+</template>
+
+<script>
+import { MainScroll, MainScrollItem } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "MainScrollDemo",
+  components: {
+    MainScroll,
+    MainScrollItem
+  }
+};
+</script>
+```
+
+#### Timeout for restoring scroll
+
+When your application is loaded, this component, together with the `MainScrollItem` will try to
+restore the scroll to the provided position (if available). Because of the dynamic nature of
+JavaScript applications, the element that it tries to restore the scroll to might not be available
+anymore. For this reason after a defined time, the scroll restoration will be considered failed.
+
+This time can be configured through the `restore-scroll-timeout-ms` prop. This is specially useful
+when combined with the URL X Module.
+
+```vue
+<template>
+  <MainScroll :restoreScrollTimeoutMs="1000">
+    <ul>
+      <MainScrollItem v-for="item in 24" tag="li"
+        >Item {{ item }}</MainScrollItem
+      >
+    </ul>
+  </MainScroll>
+</template>
+
+<script>
+import { MainScroll, MainScrollItem } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "MainScrollDemo",
+  components: {
+    MainScroll,
+    MainScrollItem
+  }
+};
+</script>
+```
+
+#### Adjust first visible item
+
+By default this component will consider the first visible item, the first element that is at least
+intersecting a 50% with its container. However this arbitrary number might not always be the best.
+
+To configure this, you can use the `margin` and `threshold` props, which work exactly like in the
+`IntersectionObserver` API. In this example we are reducing the bounds of the intersection by 50px,
+and adjusting the element to be at least 75% intersecting.
+
+```vue
+<template>
+  <MainScroll :threshold="0.75" margin="-50px">
+    <ul>
+      <MainScrollItem v-for="item in 24" tag="li"
+        >Item {{ item }}</MainScrollItem
+      >
+    </ul>
+  </MainScroll>
+</template>
+
+<script>
+import { MainScroll, MainScrollItem } from "@empathyco/x-components/scroll";
+
+export default {
+  name: "MainScrollDemo",
+  components: {
+    MainScroll,
+    MainScrollItem
+  }
+};
+</script>
+```

package/docs/API-reference/components/{common/scroll/x-components.base-scroll-to-top.md → scroll/x-components.scroll-to-top.md}

@@ -1,15 +1,12 @@
 ---
-id: x-components.x-components.base-scroll-to-top
-title: Base Scroll To Top
-sidebar_label: Base Scroll To Top
+id: x-components.x-components.scroll-to-top
+title: Scroll To Top
+sidebar_label: Scroll To Top
 ---
-# base-scroll-to-top
+# scroll-to-top
 
-> Renders a button with a default slot.
-> This button will emit a UserClickedScrollToTop when clicked.
-> The button will be shown either if it reaches a threshold and then the user scrolls up or
-> just on the UserAlmostReachedScrollEnd event depending on whether the threshold config has been
-> provided or not.
+> The `ScrollToTop` component is a button that the user can click to make a container scroll
+> up to its initial position.
 
 ## Props
 
@@ -17,7 +14,7 @@ sidebar_label: Base Scroll To Top
 | ------------------------ | ---------------------------------------------------- | ------------------- | ---------------------------- |
 | <code>animation</code>   | Animation to use for showing/hiding the button.      | <code>union</code>  | <code>() => NoElement</code> |
 | <code>thresholdPx</code> | Threshold in pixels from the top to show the button. | <code>number</code> | <code></code>                |
-| <code>scrollId</code>    | Id of the target scroll component.                   | <code>string</code> | <code></code>                |
+| <code>scrollId</code>    | Id of the target scroll component.                   | <code>string</code> | <code>MainScrollId</code>    |
 
 ## Slots
 
@@ -43,19 +40,19 @@ the scroll.
 ```vue
 <template>
   <div>
-    <BaseScrollToTop scroll-id="scrollId" :threshold-px="1000">
+    <ScrollToTop scroll-id="scrollId" :threshold-px="1000">
       <span>Scroll to top</span>
-    </BaseScrollToTop>
+    </ScrollToTop>
   </div>
 </template>
 
 <script>
-import { BaseScrollToTop } from "@empathyco/x-components";
+import { ScrollToTop } from "@empathyco/x-components/scroll";
 
 export default {
   name: "ScrollToTopTest",
   components: {
-    BaseScrollToTop
+    ScrollToTop
   }
 };
 </script>

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/tagging/x-components.tagging.md

@@ -0,0 +1,88 @@
+---
+id: x-components.x-components.tagging
+title: Tagging
+sidebar_label: 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
+
+| 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.