@maz-ui/mcp 4.0.0-beta.26

package/docs/src/composables/use-swipe.md

@@ -0,0 +1,223 @@
+---
+title: useSwipe
+description: useSwipe is a Vue 3 composable that simplifies the management of "swipe" interactions on HTML elements.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Introduction
+
+`useSwipe` allows you to detect and react to swiping movements on an HTML element. It provides you with various information about the swipe movement, such as the direction, distance, start, and end coordinates.
+You can use this information to implement specific interactions in your application, such as scrolling a carousel, opening a side menu, etc.
+
+## Key Features
+
+- Detects swipes in all 4 directions (left, right, up, down)
+- Provides key information about the swipe movement (start/end coordinates, horizontal/vertical distance)
+- Allows you to configure callbacks for each swipe direction
+- Possibility to customize the swipe detection threshold
+- Automatically handles the addition and removal of event listeners
+- Can be used with any HTML element
+
+## Basic Usage
+
+<div ref="swipeContainer" class="swipe-container">
+  <p>
+    Swipe in any direction<br>
+    <span class="maz-text-xs maz-text-muted">
+      (You should use a real device or a mobile simulator to test the swipe functionality)
+    </span>
+    <br><br>
+    Last swipe direction: {{lastSwipeDirection || 'None'}}
+  </p>
+</div>
+
+Here's an example of using the useSwipe composable:
+
+```vue
+<script lang="ts" setup>
+import { useSwipe } from 'maz-ui/composables'
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const swipeContainer = ref<HTMLDivElement>()
+
+const lastSwipeDirection = ref<string>('None')
+
+const { xDiff, yDiff, start, stop } = useSwipe({
+  element: swipeContainer,
+  onLeft: () => lastSwipeDirection.value = 'Swiped left',
+  onRight: () => lastSwipeDirection.value = 'Swiped right',
+  onUp: () => lastSwipeDirection.value = 'Swiped up',
+  onDown: () => lastSwipeDirection.value = 'Swiped down',
+  threshold: 50,
+})
+
+/**
+ * Start listening for swipe events
+ * You can also call start() directly
+ * But it's better to call it in onMounted specially for SSR
+ */
+onMounted(() => {
+  start()
+})
+
+// Stop listening for swipe events
+onUnmounted(() => {
+  stop()
+})
+</script>
+
+<template>
+  <div ref="swipeContainer" class="swipe-container">
+    <p>
+      Swipe in any direction<br>
+      <span class="maz-text-sm maz-text-muted">
+        (You should use a real device or a mobile simulator to test the swipe functionality)
+      </span>
+      <br><br>
+      Last swipe direction: {{ lastSwipeDirection || 'None' }}
+    </p>
+  </div>
+</template>
+
+<style>
+.swipe-container {
+  border: 1px solid #e2e2e3;
+  border-radius: 10px;
+  height: 200px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  font-size: 1.2rem;
+}
+</style>
+```
+
+<script lang="ts" setup>
+import { useSwipe } from 'maz-ui/src/composables/useSwipe'
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const swipeContainer = ref<HTMLDivElement>()
+
+const lastSwipeDirection = ref<string>('None')
+
+const { xDiff, yDiff, start, stop } = useSwipe({
+  element: swipeContainer,
+  onLeft: () => lastSwipeDirection.value = 'Swiped left',
+  onRight: () => lastSwipeDirection.value = 'Swiped right',
+  onUp: () => lastSwipeDirection.value = 'Swiped up',
+  onDown: () => lastSwipeDirection.value = 'Swiped down',
+  threshold: 50,
+})
+
+onMounted(() => {
+  start()
+})
+
+onUnmounted(() => {
+  stop()
+})
+</script>
+
+<style>
+.swipe-container {
+  border: 1px solid #e2e2e3;
+  border-radius: 10px;
+  height: 200px;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+  font-size: 1.2rem;
+}
+</style>
+
+In this example, the `useSwipe` composable is used to detect swiping movements on an HTML element with the `container` class. When a swipe is detected, the horizontal (`xDiff`) and vertical (`yDiff`) coordinates of the movement are displayed.
+
+Additionally, callbacks are defined for each swipe direction (`onLeft`, `onRight`, `onUp`, `onDown`), which will be called when the corresponding swipe is detected.
+
+The swipe detection threshold is also customized to 50 pixels.
+
+## Options
+
+`useSwipe` accepts an options object with the following properties:
+
+```ts
+interface UseSwipeOptions {
+  /**
+   * The HTML element on which the swipe events will be handled. This can be either a direct reference to the element or a CSS selector.
+   * @required
+   */
+  element: HTMLElement | string | Ref<HTMLElement>
+  /** Callback executed when a left swipe is detected. */
+  onLeft?: (event: TouchEvent) => void
+  /** Callback executed when a right swipe is detected. */
+  onRight?: (event: TouchEvent) => void
+  /** Callback executed when an up swipe is detected. */
+  onUp?: (event: TouchEvent) => void
+  /** Callback executed when a down swipe is detected. */
+  onDown?: (event: TouchEvent) => void
+  /**
+   * The minimum distance the swipe must travel to be considered valid.
+   * @default 50
+   */
+  threshold?: number
+  /**
+   * Whether to prevent the default behavior of the touchmove event.
+   * @default false
+   */
+  preventDefaultOnTouchMove?: boolean
+  /**
+   * Whether to prevent the default behavior of the mousewheel event.
+   * @default false
+   */
+  preventDefaultOnMouseWheel?: boolean
+  /**
+   * Whether to trigger the swipe event immediately on touchstart/mousedown.
+   * @default false
+   */
+  immediate?: boolean
+  /**
+   * Whether to trigger the swipe event only on touchend/mouseup.
+   * @default false
+   */
+  triggerOnEnd?: boolean
+}
+```
+
+## Composable Return
+
+`useSwipe` returns an object with the following properties:
+
+```ts
+interface UseSwipeReturn {
+  /** A function to start listening for swipe events. */
+  start: () => void
+  /** A function to stop listening for swipe events. */
+  stop: () => void
+  /** The horizontal difference between the start and end coordinates of the swipe. */
+  xDiff: Ref<number | undefined>
+  /** The vertical difference between the start and end coordinates of the swipe. */
+  yDiff: Ref<number | undefined>
+  /** The horizontal start coordinate of the swipe. */
+  xStart: Ref<number | undefined>
+  /** The horizontal end coordinate of the swipe. */
+  xEnd: Ref<number | undefined>
+  /** The vertical start coordinate of the swipe. */
+  yStart: Ref<number | undefined>
+  /** The vertical end coordinate of the swipe. */
+  yEnd: Ref<number | undefined>
+}
+```
+
+## Notes
+
+- Make sure to call the `start()` function to start listening for swipe events.
+- You can call the `stop()` function to stop listening for swipe events.
+- If you use the composable in a Vue component, make sure to call it in the `setup()` and clean up the event listeners in the `onUnmounted()`.
+- The composable automatically handles the addition and removal of event listeners based on the provided options.
+- You can customize the swipe detection threshold by modifying the `threshold` option.
+- If you want to prevent the default behavior of touchmove or mousewheel events, you can set the `preventDefaultOnTouchMove` and `preventDefaultOnMouseWheel` options, respectively.

package/docs/src/composables/use-timer.md

@@ -0,0 +1,130 @@
+---
+title: useTimer
+description: The useTimer composable manages timeouts. It allows you to start, pause, resume, and stop a timer with reactive updates on the remaining time. Ideal for handling asynchronous operations or user interactions with a specified timeout.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+---
+
+The composable provides the following functionality:
+
+- **start**: Initiates a timer that decrements the remaining time every second until the timeout is reached. When the timeout is reached, it executes the provided callback function.
+- **pause**: Pauses the active timer, allowing it to be resumed later from the point it was paused.
+- **resume**: Resumes the timer from the point it was paused, considering the remaining time.
+- **stop**: Stops the timer completely, resetting the remaining time to the initial timeout value.
+- **remainingTime**: A reactive variable that holds the current remaining time in milliseconds. It updates reactively as the timer progresses.
+
+The composable also includes cleanup logic using onBeforeUnmount to ensure that the timer is stopped when the component is unmounted.
+
+This composable can be used in Vue 3 components to handle timeouts in a flexible and reactive manner.
+
+## Usage
+
+**Remaning time**: {{ remainingTime }}ms
+
+<div class="maz-flex maz-items-center maz-gap-2">
+  <MazBtn @click="start">
+    Start
+  </MazBtn>
+  <MazBtn color="destructive" @click="stop">
+    Stop
+  </MazBtn>
+  <MazBtn color="warning" @click="pause">
+    Pause
+  </MazBtn>
+  <MazBtn color="secondary" @click="resume">
+    Resume
+  </MazBtn>
+</div>
+
+<script lang="ts" setup>
+  import { useTimer } from 'maz-ui/src/composables/useTimer'
+  import { useToast } from 'maz-ui/src/composables/useToast'
+
+  const toast = useToast()
+
+  const { start, stop, pause, resume, remainingTime } = useTimer({
+    timeout: 4000,
+    callback: () => toast.info('Timeout end', {
+      button: {
+        onClick: start,
+        text: 're-start',
+        closeToast: true,
+      },
+    })
+  })
+</script>
+
+```vue
+<script lang="ts" setup>
+import { useTimer, useToast } from 'maz-ui/composables'
+
+const toast = useToast()
+
+const { start, stop, pause, resume, remainingTime } = useTimer({
+  timeout: 4000,
+  callback: () => toast.info('Timeout end', {
+    button: {
+      onClick: start,
+      text: 're-start',
+      closeToast: true,
+    },
+  })
+})
+</script>
+
+<template>
+  <MazBtn @click="start">
+    Start
+  </MazBtn>
+  <MazBtn color="destructive" @click="stop">
+    Stop
+  </MazBtn>
+  <MazBtn color="warning" @click="pause">
+    Pause
+  </MazBtn>
+  <MazBtn color="secondary" @click="resume">
+    Resume
+  </MazBtn>
+</template>
+```
+
+## Set timeout with start function
+
+Starts the timer with the specified timeout. If the timeout is not provided, it uses the default value of 1000ms.
+
+```ts
+const { start } = useTimer()
+
+start(4000)
+```
+
+## Types
+
+```ts
+export interface TimerOptions {
+  /**
+   * The time in milliseconds
+   * @default 1000
+   */
+  timeout?: number
+  /**
+   * The callback to execute when the timer is finished
+   * @default undefined
+   */
+  callback?: () => unknown
+  /**
+   * The interval to update the remaining time
+   * @default 200
+   */
+  remainingTimeUpdate?: number
+  /**
+   * The offset time to execute the callback
+   * @default 0
+   */
+  callbackOffsetTime?: number
+}
+```

package/docs/src/composables/use-toast.md

@@ -0,0 +1,71 @@
+---
+title: useToast
+description: Vue composable for handling toast plugin in your components
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+::: warning
+You must install [toast plugin](./../plugins/toast.md#install) before use it
+:::
+
+::: tip
+More info about [toast plugin](./../plugins/toast.md) in its documentation
+:::
+
+## Usage
+
+```vue
+<script lang="ts" setup>
+import { useToast } from 'maz-ui/composables'
+
+const toast = useToast()
+
+toast.info('info message', {
+  button: {
+    onClick: () => toast.success('clicked'),
+    text: 'Click me',
+    closeToast: true
+  }
+})
+toast.success('success message', {
+  button: {
+    href: '/composables/use-toast',
+    text: 'Follow me',
+    closeToast: true,
+  }
+})
+toast.warning('warning message')
+toast.error('error message')
+</script>
+```
+
+<script lang="ts" setup>
+  import { onMounted } from 'vue'
+  import { useToast } from 'maz-ui/src/composables/useToast'
+
+  const toast = useToast()
+
+  onMounted(() => {
+    toast.info('info message', {
+      button: {
+        onClick: () => toast.success('clicked'),
+        text: 'Click me',
+        closeToast: true
+      }
+    })
+    toast.success('success message', {
+      button: {
+        href: '/composables/use-toast',
+        text: 'Follow me',
+        closeToast: true,
+      }
+    })
+    toast.warning('warning message')
+    toast.error('error message')
+    toast.message('message')
+  })
+
+</script>

package/docs/src/composables/use-user-visibility.md

@@ -0,0 +1,169 @@
+---
+title: user-visibility
+description: Plugin to see and manage the user page visibility
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+::: tip
+Useful to know if the user is displaying your website
+:::
+
+## Demo
+
+<MazCard overflow-hidden style="width: 100%; margin-bottom: 1rem;">
+  <h3 style="margin-top: 0; margin-bottom: 1rem;">Logs</h3>
+
+  <div v-for="({isVisible}, i) in events" :key="i">
+    isVisible: {{isVisible}}
+  </div>
+</MazCard>
+
+<div class="flex items-start gap-05 items-center flex-wrap">
+  <MazBtn @click="userVisibility.start()" color="info">
+    Start
+  </MazBtn>
+
+<MazBtn @click="userVisibility.destroy()" color="destructive">
+Destroy
+</MazBtn>
+
+</div>
+
+::: tip
+Switch tabs for a second to see events
+:::
+
+## How to use it?
+
+```vue
+<script lang="ts" setup>
+import { useUserVisibility } from 'maz-ui/composables'
+
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+
+const events = ref([])
+
+function callback({ isVisible }) {
+  console.log('isVisible', isVisible)
+  events.value.push({ isVisible })
+}
+
+const options = {
+  immediate: true,
+  once: false,
+  timeout: 1000,
+  ssr: true,
+}
+
+const userVisibility = useUserVisibility({ callback, options })
+
+onMounted(() => {
+  userVisibility.start()
+})
+
+onBeforeUnmount(() => {
+  userVisibility.destroy()
+})
+</script>
+
+<template>
+  <MazBtn color="destructive" @click="userVisibility.destroy()">
+    Destroy
+  </MazBtn>
+
+  <MazBtn color="destructive" @click="userVisibility.destroy()">
+    Destroy
+  </MazBtn>
+
+  <MazCard overflow-hidden style="width: 100%;">
+    <h3>Logs</h3>
+
+    <div v-for="({ isVisible }, i) in events" :key="i">
+      isVisible: {{ isVisible }}
+    </div>
+  </MazCard>
+</template>
+```
+
+<script lang="ts" setup>
+  import { onMounted, ref, onBeforeUnmount } from 'vue'
+
+  import { useUserVisibility } from 'maz-ui/src/composables/useUserVisibility'
+
+  const events = ref([])
+
+  const callback = ({ isVisible }) => {
+    console.log('isVisible', isVisible)
+    events.value.push({ isVisible: isVisible })
+  }
+
+  const options = {
+    immediate: true,
+    once: false,
+    timeout: 1000,
+    ssr: true,
+  }
+
+  const userVisibility = useUserVisibility({ callback, options })
+
+  onMounted(() => {
+    userVisibility.start()
+  })
+
+  onBeforeUnmount(() => {
+    userVisibility.destroy()
+  })
+</script>
+
+## Callback
+
+```ts
+export type UserVisibilyCallback = ({
+  isVisible,
+}: {
+  isVisible: boolean
+}) => void
+```
+
+## Options
+
+```ts
+interface UserVisibilyStrictOptions {
+  immediate: boolean
+  timeout: number
+  once: boolean
+  ssr: boolean // if `true`
+}
+```
+
+### Default Options
+
+```ts
+const defaultOptions: UserVisibilyOptions = {
+  immediate: false,
+  timeout: 5000,
+  once: false,
+  ssr: false,
+}
+```
+
+## Actions
+
+### Start
+
+Will start the user visibility tracking
+
+```ts
+userVisibility.start()
+```
+
+### Destroy
+
+Will destroy the instance and stop the tracking
+
+```ts
+userVisibility.destroy()
+```

package/docs/src/composables/use-wait.md

@@ -0,0 +1,62 @@
+---
+title: useWait
+description: Vue composable for handling wait plugins
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+::: warning
+You must install the [wait plugin](./../plugins/wait.md#install) before using it
+:::
+
+::: tip
+More info about the [wait plugin](./../plugins/wait.md) in its documentation
+:::
+
+## Usage
+
+<MazFullscreenLoader v-if="wait.isLoading('MAIN_LOADER')">
+  Loading
+</MazFullscreenLoader>
+<p v-else> Loaded </p>
+
+```vue
+<script lang="ts" setup>
+import { sleep } from 'maz-ui'
+import { useWait } from 'maz-ui/composables'
+import { onMounted } from 'vue'
+
+const wait = useWait()
+
+onMounted(async () => {
+  wait.start('MAIN_LOADER')
+  await sleep(2000)
+  wait.stop('MAIN_LOADER')
+})
+</script>
+
+<template>
+  <MazFullscreenLoader v-if="wait.isLoading('MAIN_LOADER')">
+    Loading
+  </MazFullscreenLoader>
+  <p v-else>
+    Loaded
+  </p>
+</template>
+```
+
+<script lang="ts" setup>
+  import { onMounted } from 'vue'
+  import { sleep } from 'maz-ui/src/index'
+  import { useWait } from 'maz-ui/src/composables/useWait'
+
+  const wait = useWait()
+
+  onMounted(async () => {
+    wait.start('MAIN_LOADER')
+    await sleep(2000)
+    wait.stop('MAIN_LOADER')
+  })
+</script>

package/docs/src/composables/use-window-size.md

@@ -0,0 +1,18 @@
+---
+title: useWindowSize
+description: This composable provides a simple utility to track the width and height of the browser window with reactivity
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Basic usage
+
+```ts
+const { height, width } = useWindowSize()
+```
+
+::: warning
+More documentation to come
+:::