maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/composables/use-timer.md

@@ -0,0 +1,104 @@
+---
+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."
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-timer"
+---
+
+# useTimer
+
+> 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.
+
+- Package: `maz-ui`
+- Import: `import { useTimer } from 'maz-ui/composables/useTimer'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-timer
+
+---
+
+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 components to handle timeouts in a flexible and reactive manner.
+
+## Usage
+
+**Remaning time**: ms
+
+```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/composables/use-toast.md

@@ -0,0 +1,50 @@
+---
+title: "useToast"
+description: "Vue composable for handling toast plugin in your components"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-toast"
+---
+
+# useToast
+
+> Vue composable for handling toast plugin in your components
+
+- Package: `maz-ui`
+- Import: `import { useToast } from 'maz-ui/composables/useToast'`
+- Nuxt: auto-imported by `@maz-ui/nuxt` when `mazUi.plugins.toast` is enabled
+- Web: https://maz-ui.com/composables/use-toast
+
+**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>
+```

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

@@ -0,0 +1,127 @@
+---
+title: "user-visibility"
+description: "Plugin to see and manage the user page visibility"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-user-visibility"
+---
+
+# user-visibility
+
+> Plugin to see and manage the user page visibility
+
+- Package: `maz-ui`
+- Import: `import { useUserVisibility } from 'maz-ui/composables/useUserVisibility'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-user-visibility
+
+**Tip:**
+
+Useful to know if the user is displaying your website
+
+## Demo
+
+**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>
+```
+
+## 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/composables/use-wait.md

@@ -0,0 +1,50 @@
+---
+title: "useWait"
+description: "Vue composable for handling wait plugins"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-wait"
+---
+
+# useWait
+
+> Vue composable for handling wait plugins
+
+- Package: `maz-ui`
+- Import: `import { useWait } from 'maz-ui/composables/useWait'`
+- Nuxt: auto-imported by `@maz-ui/nuxt` when `mazUi.plugins.wait` is enabled
+- Web: https://maz-ui.com/composables/use-wait
+
+**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
+
+```vue
+<script lang="ts" setup>
+import { sleep } from '@maz-ui/utils'
+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>
+```

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

@@ -0,0 +1,25 @@
+---
+title: "useWindowSize"
+description: "This composable provides a simple utility to track the width and height of the browser window with reactivity"
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-window-size"
+---
+
+# useWindowSize
+
+> This composable provides a simple utility to track the width and height of the browser window with reactivity
+
+- Package: `maz-ui`
+- Import: `import { useWindowSize } from 'maz-ui/composables/useWindowSize'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-window-size
+
+## Basic usage
+
+```ts
+const { height, width } = useWindowSize()
+```
+
+**Warning:**
+
+More documentation to come

package/docs/directives/click-outside.md

@@ -0,0 +1,182 @@
+---
+title: "vClickOutside"
+description: "vClickOutside is a Vue directive to trigger a function when the user clicks outside an element"
+package: "maz-ui"
+url: "https://maz-ui.com/directives/click-outside"
+---
+
+# vClickOutside
+
+> vClickOutside is a Vue directive to trigger a function when the user clicks outside an element
+
+- Package: `maz-ui`
+- Import: `import { vClickOutside } from 'maz-ui/directives/vClickOutside'`
+- Web: https://maz-ui.com/directives/click-outside
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import { vClickOutside } from 'maz-ui/directives'
+import { ref } from 'vue'
+
+const hasClikedOutside = ref(false)
+
+function clikedOutside() {
+  hasClikedOutside.value = true
+  setTimeout(() => hasClikedOutside.value = false, 2000)
+}
+</script>
+
+<template>
+  <div
+    class="flex flex-center rounded-md p-12 bg-surface-300"
+  >
+    <MazCard v-click-outside="clikedOutside">
+      Click outside me
+    </MazCard>
+  </div>
+
+  <div
+    v-if="hasClikedOutside"
+    class="flex flex-center rounded-md bg-sucess text-success-foreground p-4 mt-4"
+  >
+    You clicked outside
+  </div>
+</template>
+```
+
+## Advanced usage with options
+
+The directive can accept an options object to customize its behavior:
+
+```vue
+<script lang="ts" setup>
+import { vClickOutside } from 'maz-ui/directives'
+import { ref } from 'vue'
+
+const hasClickedOutsideWithIgnore = ref(false)
+
+function clickedOutsideWithIgnore() {
+  hasClickedOutsideWithIgnore.value = true
+  setTimeout(() => hasClickedOutsideWithIgnore.value = false, 2000)
+}
+</script>
+
+<template>
+  <MazCard v-click-outside="{ callback: clickedOutsideWithIgnore, ignore: ['.ignore-me'] }">
+    <div class="p-4">
+      <p>Click outside me (but not on the button below)</p>
+      <MazBtn class="ignore-me mt-2" color="secondary">
+        This button is ignored
+      </MazBtn>
+    </div>
+  </MazCard>
+</template>
+```
+
+## Using the `once` option
+
+The directive can be configured to trigger only once:
+
+```vue
+<script lang="ts" setup>
+import { vClickOutside } from 'maz-ui/directives'
+import { ref } from 'vue'
+
+const hasClickedOnce = ref(false)
+
+function clickedOnce() {
+  hasClickedOnce.value = true
+  // This callback will only be triggered once
+}
+</script>
+
+<template>
+  <MazCard v-click-outside="{ callback: clickedOnce, once: true }">
+    Click outside me (works only once)
+  </MazCard>
+</template>
+```
+
+## All options combined
+
+Here's an example using all available options:
+
+```vue
+<script lang="ts" setup>
+import { vClickOutside, type VClickOutsideOptions } from 'maz-ui/directives'
+
+const options: VClickOutsideOptions = {
+  callback: handleClickOutside,
+  ignore: ['.modal', '.tooltip', '.dropdown-menu'],
+  capture: true,
+  once: false
+}
+
+function handleClickOutside(event: Event) {
+  console.log('Clicked outside!', event)
+}
+</script>
+
+<template>
+  <div v-click-outside="options">
+    <!-- Your content -->
+  </div>
+</template>
+```
+
+## API Reference
+
+### Usage Patterns
+
+```vue
+<!-- Simple function -->
+<div v-click-outside="myCallback">...</div>
+
+<!-- With options object -->
+<div v-click-outside="{ callback: myCallback, ignore: ['.ignore'] }">...</div>
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `callback` | `Function` | `undefined` | **Required.** Function to call when clicking outside |
+| `ignore` | `string[]` | `[]` | Array of CSS selectors to ignore when detecting clicks |
+| `capture` | `boolean` | `false` | Whether to use capture phase for event listening |
+| `once` | `boolean` | `false` | Whether to trigger the callback only once |
+
+### Type Definitions
+
+```typescript
+interface VClickOutsideOptions {
+  callback: (...args: any[]) => any
+  ignore?: string[]
+  capture?: boolean
+  once?: boolean
+}
+
+type vClickOutsideBindingValue =
+  | ((...args: any[]) => any)
+  | VClickOutsideOptions
+```
+
+## Global install
+
+### Vue
+
+```typescript
+import { vClickOutsideInstall } from 'maz-ui/directives'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+app.use(vClickOutsideInstall)
+
+app.mount('#app')
+```
+
+### Nuxt
+
+Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.

package/docs/directives/fullscreen-img.md

@@ -0,0 +1,83 @@
+---
+title: "v-fullscreen-img"
+description: "Displays images fullscreen on click"
+package: "maz-ui"
+url: "https://maz-ui.com/directives/fullscreen-img"
+---
+
+# v-fullscreen-img
+
+> Displays images fullscreen on click
+
+- Package: `maz-ui`
+- Import: `import { vFullscreenImg } from 'maz-ui/directives/vFullscreenImg'`
+- Web: https://maz-ui.com/directives/fullscreen-img
+
+## Basic usage
+
+```vue
+<template>
+  <img
+    v-fullscreen-img
+    src="https://placedog.net/1000/500"
+  />
+</template>
+
+<script setup lang="ts">
+  import { vFullscreenImg } from 'maz-ui/directives/vFullscreenImg'
+</script>
+```
+
+## With animate options
+
+```html
+<img
+  v-fullscreen-img="{
+    scaleOnHover: true,
+    blurOnHover: true,
+  }"
+  src="https://placedog.net/1000/600"
+/>
+```
+
+## On custom element
+
+```html
+<MazBtn
+  v-fullscreen-img="'https://placedog.net/1000/700'"
+>
+  Click me to show image
+</MazBtn>
+```
+
+## Global install
+
+### Vue
+
+`main.ts`
+
+```ts
+import { createApp } from 'vue'
+import { vFullscreenImgInstall } from 'maz-ui/directives/vFullscreenImg'
+
+const app = createApp(App)
+
+app.use(vFullscreenImgInstall)
+
+app.mount('#app')
+```
+
+### Nuxt
+
+Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.
+
+## Types
+
+```ts
+interface vFullscreenImgBindingOptions extends vFullscreenImgOptions {
+  src: string
+  alt?: string | null
+}
+
+export type vFullscreenImgBindingValue = string | vFullscreenImgBindingOptions | undefined
+```