@maz-ui/mcp 5.0.1-beta.0 → 5.1.0-beta.1

package/docs/components/maz-ticker.md

@@ -0,0 +1,427 @@
+---
+title: "MazTicker"
+description: "MazTicker is a scrolling ticker component that continuously animates content in a loop with configurable speed, direction, pause controls, and gradient overlays"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-ticker"
+---
+
+# MazTicker
+
+> MazTicker is a scrolling ticker component that continuously animates content in a loop with configurable speed, direction, pause controls, and gradient overlays
+
+- Package: `maz-ui`
+- Import: `import MazTicker from 'maz-ui/components/MazTicker'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-ticker
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+```vue
+<template>
+  <MazTicker>
+    <span>Vue 3</span>
+    <span>Nuxt 3</span>
+    <span>TypeScript</span>
+    <span>TailwindCSS</span>
+    <span>Maz UI</span>
+  </MazTicker>
+</template>
+
+<script lang="ts" setup>
+  import MazTicker from 'maz-ui/components/MazTicker'
+</script>
+```
+
+## Screenshots gallery
+
+A vertical ticker with images, similar to a screenshot showcase. Uses `orientation="vertical"` with `pause-on-hover` for user-friendly browsing.
+
+```vue
+<template>
+  <div class="flex gap-4 overflow-hidden" style="height: 300px">
+    <MazTicker
+      orientation="vertical"
+      :overlay="false"
+      :duration="30"
+      pause-on-hover
+    >
+      <img
+        v-for="i in 4"
+        :key="i"
+        :src="`https://picsum.photos/seed/maz-ticker-${i}/400/225`"
+        :alt="`Screenshot ${i}`"
+        class="rounded-lg border border-gray-200 object-cover dark:border-gray-700"
+        style="width: 400px; height: 225px"
+      />
+    </MazTicker>
+    <MazTicker
+      orientation="vertical"
+      :overlay="false"
+      :duration="30"
+      reverse
+      pause-on-hover
+    >
+      <img
+        v-for="i in 4"
+        :key="i"
+        :src="`https://picsum.photos/seed/maz-ticker-${i + 4}/400/225`"
+        :alt="`Screenshot ${i + 4}`"
+        class="rounded-lg border border-gray-200 object-cover dark:border-gray-700"
+        style="width: 400px; height: 225px"
+      />
+    </MazTicker>
+    <MazTicker
+      class="hidden md:flex"
+      orientation="vertical"
+      :overlay="false"
+      :duration="30"
+      pause-on-hover
+    >
+      <img
+        v-for="i in 4"
+        :key="i"
+        :src="`https://picsum.photos/seed/maz-ticker-${i + 8}/400/225`"
+        :alt="`Screenshot ${i + 8}`"
+        class="rounded-lg border border-gray-200 object-cover dark:border-gray-700"
+        style="width: 400px; height: 225px"
+      />
+    </MazTicker>
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import MazTicker from 'maz-ui/components/MazTicker'
+</script>
+```
+
+## 3D Screenshots showcase
+
+Create an eye-catching 3D perspective effect with tilted vertical tickers, inspired by the Nuxt UI Marquee screenshots demo.
+
+```vue
+<template>
+  <div
+    class="overflow-hidden rounded-lg bg-gray-100 dark:bg-gray-800"
+    style="height: 400px; perspective: 1500px"
+  >
+    <div
+      class="flex gap-4"
+      style="height: 900px; margin-top: -300px; margin-left: -150px; transform: rotateX(55deg) rotateZ(30deg); transform-origin: center center"
+    >
+      <MazTicker
+        reverse
+        orientation="vertical"
+        :overlay="false"
+        :duration="40"
+        style="width: 300px; flex-shrink: 0"
+      >
+        <img
+          v-for="i in 4"
+          :key="i"
+          :src="`https://picsum.photos/seed/maz-3d-${i}/460/258`"
+          :alt="`Screenshot ${i}`"
+          width="460"
+          height="258"
+          loading="lazy"
+          class="rounded-lg border border-gray-200 bg-white object-cover dark:border-gray-700"
+          style="width: 300px; height: 168px"
+        />
+      </MazTicker>
+      <MazTicker
+        orientation="vertical"
+        :overlay="false"
+        :duration="40"
+        style="width: 300px; flex-shrink: 0"
+      >
+        <img
+          v-for="i in 4"
+          :key="i"
+          :src="`https://picsum.photos/seed/maz-3d-${i + 4}/460/258`"
+          :alt="`Screenshot ${i + 4}`"
+          width="460"
+          height="258"
+          loading="lazy"
+          class="rounded-lg border border-gray-200 bg-white object-cover dark:border-gray-700"
+          style="width: 300px; height: 168px"
+        />
+      </MazTicker>
+      <MazTicker
+        reverse
+        orientation="vertical"
+        :overlay="false"
+        :duration="40"
+        style="width: 300px; flex-shrink: 0"
+      >
+        <img
+          v-for="i in 4"
+          :key="i"
+          :src="`https://picsum.photos/seed/maz-3d-${i + 8}/460/258`"
+          :alt="`Screenshot ${i + 8}`"
+          width="460"
+          height="258"
+          loading="lazy"
+          class="rounded-lg border border-gray-200 bg-white object-cover dark:border-gray-700"
+          style="width: 300px; height: 168px"
+        />
+      </MazTicker>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import MazTicker from 'maz-ui/components/MazTicker'
+</script>
+```
+
+## Orientation
+
+### Horizontal (default)
+
+By default, the ticker will scroll horizontally.
+
+```vue
+<template>
+  <MazTicker orientation="horizontal">
+    <span>Item 1</span>
+    <span>Item 2</span>
+    <span>Item 3</span>
+  </MazTicker>
+</template>
+```
+
+### Vertical
+
+Otherwise, the ticker will scroll vertically.
+
+```vue
+<template>
+  <div style="height: 100px">
+    <MazTicker orientation="vertical">
+      <div class="py-2">Item 1</div>
+      <div class="py-2">Item 2</div>
+      <div class="py-2">Item 3</div>
+    </MazTicker>
+  </div>
+</template>
+```
+
+## Reverse direction
+
+```vue
+<template>
+  <MazTicker>
+    <span>Normal direction</span>
+  </MazTicker>
+  <MazTicker reverse>
+    <span>Reverse direction</span>
+  </MazTicker>
+</template>
+```
+
+## Speed control
+
+Control the animation speed with the `duration` prop (in seconds). Lower values = faster.
+
+```vue
+<template>
+  <MazTicker :duration="5">
+    <span>Fast (5s)</span>
+  </MazTicker>
+  <MazTicker :duration="20">
+    <span>Normal (20s)</span>
+  </MazTicker>
+  <MazTicker :duration="40">
+    <span>Slow (40s)</span>
+  </MazTicker>
+</template>
+```
+
+## Repeat
+
+The `repeat` prop controls how many times the content is duplicated to create a seamless loop. The default value is `4`. Increase it when your content is short to avoid visible gaps during the animation.
+
+```vue
+<template>
+  <MazTicker :repeat="2">
+    <span>Repeat 2</span>
+  </MazTicker>
+  <MazTicker :repeat="10">
+    <span>Repeat 10</span>
+  </MazTicker>
+</template>
+```
+
+## Custom gap
+
+```vue
+<template>
+  <MazTicker gap="0.5rem">
+    <span>Small gap</span>
+  </MazTicker>
+  <MazTicker gap="3rem">
+    <span>Large gap</span>
+  </MazTicker>
+</template>
+```
+
+## Overlay
+
+### Without overlay
+
+You can disable the overlay by setting the `overlay` prop to `false`.
+
+```vue
+<template>
+  <MazTicker :overlay="false" :repeat="10">
+    <span>No gradient overlay</span>
+  </MazTicker>
+</template>
+```
+
+### Custom overlay size
+
+You can change the size of the overlay by setting the `overlay-size` prop to a CSS value.
+
+```vue
+<template>
+  <MazTicker overlay-size="10%" :repeat="10">
+    <span>Small overlay (10%)</span>
+  </MazTicker>
+  <MazTicker overlay-size="50%" :repeat="10">
+    <span>Large overlay (50%)</span>
+  </MazTicker>
+</template>
+```
+
+## Pause controls
+
+### Pause on hover
+
+When a child element is hovered, the animation will pause.
+
+```vue
+<template>
+  <MazTicker pause-on-hover>
+    <span>Hover me to pause</span>
+  </MazTicker>
+</template>
+```
+
+### Pause on focus
+
+When a child element is focused, the animation will pause.
+
+```vue
+<template>
+  <MazTicker pause-on-focus>
+    <a href="#">Focusable link 1</a>
+    <a href="#">Focusable link 2</a>
+    <a href="#">Focusable link 3</a>
+  </MazTicker>
+</template>
+```
+
+### Programmatic pause
+
+You can control the animation programmatically with the `paused` prop.
+
+```vue
+<template>
+  <MazBtn size="sm" @click="isPaused = !isPaused">
+    {{ isPaused ? 'Resume' : 'Pause' }}
+  </MazBtn>
+  <MazTicker :paused="isPaused">
+    <span>Controlled by button</span>
+  </MazTicker>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazTicker from 'maz-ui/components/MazTicker'
+  import MazBtn from 'maz-ui/components/MazBtn'
+
+  const isPaused = ref(false)
+</script>
+```
+
+## Custom content
+
+MazTicker accepts any HTML content, not just text.
+
+```vue
+<template>
+  <MazTicker pause-on-hover :duration="15">
+    <MazBadge color="primary">Vue 3</MazBadge>
+    <MazBadge color="success">Nuxt 3</MazBadge>
+    <MazBadge color="info">TypeScript</MazBadge>
+    <MazBadge color="warning">TailwindCSS</MazBadge>
+    <MazBadge color="accent">Maz UI</MazBadge>
+  </MazTicker>
+</template>
+
+<script lang="ts" setup>
+  import MazTicker from 'maz-ui/components/MazTicker'
+  import MazBadge from 'maz-ui/components/MazBadge'
+</script>
+```
+
+## Slots
+
+### Before and after
+
+Replace the default before and after slots with custom content.
+
+```vue
+<template>
+  <MazTicker>
+    <template #before>
+      <div class="flex items-center px-4 font-semibold">Latest:</div>
+    </template>
+    <span>Breaking news item</span>
+    <template #after>
+      <div class="flex items-center px-4 font-semibold">End</div>
+    </template>
+  </MazTicker>
+</template>
+```
+
+## Timing function
+
+```vue
+<template>
+  <MazTicker animation-timing-function="linear" :repeat="10">
+    <span>Linear (default)</span>
+  </MazTicker>
+  <MazTicker animation-timing-function="ease-in-out" :repeat="10">
+    <span>Ease in out</span>
+  </MazTicker>
+</template>
+```
+
+## MazTicker API
+
+`import MazTicker from 'maz-ui/components/MazTicker'`
+
+### Props
+
+- `orientation` (`MazTickerOrientation`, default: `"horizontal"`): Scrolling direction. Values: `'horizontal'`, `'vertical'` (non exhaustive).
+- `reverse` (`boolean`, default: `false`): Reverse the scrolling direction.
+- `duration` (`number`, default: `20`): Duration of one full animation cycle in seconds.
+- `gap` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}%` ``, default: `"1rem"`): Gap between repeated content blocks (CSS value).
+- `repeat` (`number`, default: `4`): Number of times the content is duplicated for seamless looping.
+- `pause-on-hover` (`boolean`, default: `false`): Pause animation on mouse hover.
+- `pause-on-focus` (`boolean`, default: `false`): Pause animation when a child element receives focus.
+- `paused` (`boolean`, default: `false`): Programmatic pause control - takes precedence over pauseOnHover and pauseOnFocus.
+- `overlay` (`boolean`, default: `true`): Show gradient overlays on edges to fade content in/out.
+- `overlay-size` (`` `${number}rem` | `${number}px` | `${number}em` | `${number}vw` | `${number}vh` | `${number}vmin` | `${number}vmax` | `${number}%` | `${number}ch` | `${number}cm` | `${number}mm` | `${number}in` | `${number}ex` | `${number}pc` | `${number... ``, default: `"33%"`): Size of the gradient overlay zones (CSS value).
+- `animation-timing-function` (`string`, default: `"linear"`): CSS animation timing function.
+
+### Slots
+
+- `#before`: Static content before the scrolling area
+- `#overlay-start`: Custom overlay for the start edge (left in horizontal, top in vertical). Replaces default gradient.
+- `#default`: Content to scroll (repeated for seamless animation)
+- `#overlay-end`: Custom overlay for the end edge (right in horizontal, bottom in vertical). Replaces default gradient.
+- `#after`: Static content after the scrolling area