maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/directives/lazy-img.md

@@ -0,0 +1,182 @@
+---
+title: "vLazyImg"
+description: "vLazyImg is a Vue directive to lazy load images with many options. Images are loaded when they enter the viewport, using a shared IntersectionObserver for optimal performance."
+package: "maz-ui"
+url: "https://maz-ui.com/directives/lazy-img"
+---
+
+# vLazyImg
+
+> vLazyImg is a Vue directive to lazy load images with many options. Images are loaded when they enter the viewport, using a shared IntersectionObserver for optimal performance.
+
+- Package: `maz-ui`
+- Import: `import { vLazyImg } from 'maz-ui/directives/vLazyImg'`
+- Web: https://maz-ui.com/directives/lazy-img
+
+**Tip: Performance**
+
+Every element bound to the directive shares a pooled `IntersectionObserver` (grouped by observer options) and keeps its state per element. You can render hundreds of lazy images - like a list of [`MazAvatar`](../components/maz-avatar.md) - with only a handful of observers and no leak when elements unmount.
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import { vLazyImg } from 'maz-ui/directives'
+</script>
+
+<template>
+  <img
+    v-lazy-img="'https://placedog.net/1500/1000'"
+    style="background-color: var(--maz-surface-300); width: 80%;"
+    class="flex flex-center rounded"
+  >
+</template>
+```
+
+## Use background image
+
+> Instead of `v-lazy-img` use `v-lazy-img:bg-image`
+
+```vue
+<template>
+  <div
+    v-lazy-img:bg-image="'https://placedog.net/1500/1000'"
+    style="height: 200px; width: 100%; background-size: contain;"
+    class="flex flex-center rounded"
+  />
+</template>
+```
+
+## Disable lazy loading
+
+Set `disabled: true` to load the image immediately, bypassing the `IntersectionObserver`. Useful for above-the-fold images or server-side rendering.
+
+```vue
+<template>
+  <img
+    v-lazy-img="{ src: 'https://placedog.net/1500/1000', disabled: true }"
+  >
+</template>
+```
+
+## Fallback image on error
+
+Provide a `fallbackSrc` to replace the image when it fails to load. Set `fallbackSrc: false` to keep the broken image instead of loading the default placeholder.
+
+```vue
+<template>
+  <img
+    v-lazy-img="{
+      src: 'https://broken-link.example',
+      fallbackSrc: '/images/fallback.png',
+    }"
+  >
+</template>
+```
+
+## Options
+
+> Open the developer console to show logs
+
+```vue
+<script lang="ts" setup>
+import { vLazyImg, type vLazyImgBindingValue } from 'maz-ui/directives'
+
+const lazyBinding: vLazyImgBindingValue = {
+  src: 'https://placedog.net/1500/1000',
+  baseClass: 'custom-class',
+  loadingClass: 'custom-class-loading',
+  loadedClass: 'custom-class-loaded',
+  errorClass: 'custom-class-error',
+  fallbackClass: 'custom-class-fallback',
+  observerOnce: false, // run onIntersecting each time the user scrolls onto the image
+  loadOnce: false,
+  onLoading: (el: Element) => console.log('loading', el),
+  onLoaded: (el: Element) => console.log('loaded', el),
+  onError: (el: Element) => console.log('error', el),
+  onIntersecting: (el: Element) => console.log('intersecting', el),
+}
+</script>
+
+<template>
+  <img
+    v-lazy-img="lazyBinding"
+    style="background-color: var(--maz-surface-300); width: 80%;"
+    class="flex flex-center rounded"
+  >
+</template>
+```
+
+## Global install
+
+### Vue
+
+```typescript
+import { vLazyImgInstall, type vLazyImgOptions } from 'maz-ui/directives'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+// all options (optional)
+const vLazyImgOptions: vLazyImgOptions = {
+  baseClass: 'm-lazy-img',
+  loadedClass: 'm-lazy-loaded',
+  loadingClass: 'm-lazy-loading',
+  errorClass: 'm-lazy-error',
+  fallbackClass: 'm-lazy-fallback',
+  observerOnce: true,
+  loadOnce: true,
+  observerOptions: {
+    root: undefined,
+    rootMargin: undefined,
+    threshold: 0.1,
+  },
+  fallbackSrc: '/images/fallback.png', // or `false` to disable the default placeholder
+  onLoading: (el: Element) => console.log('loading', el),
+  onLoaded: (el: Element) => console.log('loaded', el),
+  onError: (el: Element) => console.log('error', el),
+  onIntersecting: (el: Element) => console.log('intersecting', el),
+}
+
+app.use(vLazyImgInstall, vLazyImgOptions)
+
+app.mount('#app')
+```
+
+### Nuxt
+
+Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.
+
+## Types
+
+```ts
+export interface vLazyImgOptions {
+  baseClass?: string
+  loadingClass?: string
+  loadedClass?: string
+  errorClass?: string
+  fallbackClass?: string
+  observerOnce?: boolean
+  loadOnce?: boolean
+  observerOptions?: {
+    root?: HTMLElement | null
+    threshold: number
+    rootMargin?: string
+  }
+  /** Image loaded on error - set to `false` to keep the broken image */
+  fallbackSrc?: string | false
+  onLoading?: (el: Element) => unknown
+  onLoaded?: (el: Element) => unknown
+  onError?: (el: Element) => unknown
+  onIntersecting?: (el: Element) => unknown
+}
+
+interface vLazyImgBindingOptions extends vLazyImgOptions {
+  /** The source of the image when the binding value is an options object */
+  src?: string
+  /** Load the image immediately, bypassing the IntersectionObserver */
+  disabled?: boolean
+}
+
+export type vLazyImgBindingValue = string | vLazyImgBindingOptions
+```

package/docs/directives/tooltip.md

@@ -0,0 +1,298 @@
+---
+title: "vTooltip"
+description: "vTooltip is a Vue directive to display a text when the user hovers an element"
+package: "maz-ui"
+url: "https://maz-ui.com/directives/tooltip"
+---
+
+# vTooltip
+
+> vTooltip is a Vue directive to display a text when the user hovers an element
+
+- Package: `maz-ui`
+- Import: `import { vTooltip } from 'maz-ui/directives/vTooltip'`
+- Web: https://maz-ui.com/directives/tooltip
+
+## Basic usage
+
+```vue
+<script lang="ts" setup>
+import { vTooltip } from 'maz-ui/directives'
+</script>
+
+<template>
+  <MazBtn v-tooltip="'This is a top tooltip'">
+    Top
+  </MazBtn>
+  <MazBtn v-tooltip.right="'This is a top tooltip'">
+    Right
+  </MazBtn>
+  <MazBtn v-tooltip.left="'This is a top tooltip'">
+    Left
+  </MazBtn>
+  <MazBtn v-tooltip.bottom="'This is a top tooltip'">
+    Bottom
+  </MazBtn>
+</template>
+```
+
+## Colors
+
+```html
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'primary' }">
+  Primary
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'secondary' }" color="secondary">
+  Secondary
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'success' }" color="success">
+  Success
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'warning' }" color="warning">
+  Warning
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'destructive' }" color="destructive">
+  destructive
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'info' }" color="info">
+  Info
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'accent' }" color="accent">
+  Accent
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'contrast' }" color="contrast">
+  Contrast
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', color: 'default' }" color="surface">
+  Background
+</MazBtn>
+```
+
+## Position
+
+You can change the position of the tooltip by passing a `position` option or using the directive modifier (e.g. `v-tooltip.top`).
+
+```html
+<MazBtn v-tooltip.bottom="{ text: 'Tooltip text' }">
+  Bottom
+</MazBtn>
+
+<MazBtn v-tooltip.left="{ text: 'Tooltip text' }">
+  Left
+</MazBtn>
+
+<MazBtn v-tooltip.right="{ text: 'Tooltip text' }">
+  Right
+</MazBtn>
+
+<MazBtn v-tooltip.top="{ text: 'Tooltip text' }">
+  Top
+</MazBtn>
+
+<MazBtn v-tooltip.top-start="{ text: 'Tooltip text' }">
+  Top start
+</MazBtn>
+
+<MazBtn v-tooltip.top-end="{ text: 'Tooltip text' }">
+  Top end
+</MazBtn>
+
+<MazBtn v-tooltip.bottom-start="{ text: 'Tooltip text' }">
+  Bottom start
+</MazBtn>
+
+<MazBtn v-tooltip.bottom-end="{ text: 'Tooltip text' }">
+  Bottom end
+</MazBtn>
+```
+
+## HTML content
+
+You can also use HTML content in the tooltip by passing a string to the `html` option.
+
+```html
+<MazBtn v-tooltip="{ html: '<strong>Tooltip</strong> text <br> with <br> line breaks' }">
+  HTML
+</MazBtn>
+```
+
+## Customization
+
+You can customize the tooltip by passing a `panelClass` or `panelStyle` option.
+
+```html
+<MazBtn v-tooltip="{ text: 'Custom panel class', panelClass: 'text-red-500!' }">
+  panelClass
+</MazBtn>
+<MazBtn v-tooltip="{ text: 'Custom panel style', panelStyle: 'background-color: red; color: white;' }">
+  panelStyle
+</MazBtn>
+```
+
+## Trigger
+
+You can change the trigger mode of the tooltip by passing a `trigger` option.
+
+The default trigger is `hover`.
+
+The `adaptive` trigger will use the `click` trigger on touch devices (mobile and tablet) and the `hover` trigger on non-touch devices (desktop).
+
+```html
+<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'click' }">
+  Click
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'hover' }">
+  Hover
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', trigger: 'adaptive' }">
+  Adaptive
+</MazBtn>
+```
+
+## Offset
+
+The `offset` (in px) option allows you to adjust the position of the tooltip relative to the original element.
+
+```html
+<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 0 }">
+  0
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 10 }">
+  10
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 20 }">
+  20
+</MazBtn>
+
+<MazBtn v-tooltip="{ text: 'Tooltip text', offset: 40 }">
+  40
+</MazBtn>
+```
+
+## Open programmatically
+
+```vue
+<script lang="ts" setup>
+  import { vTooltip } from 'maz-ui/directives'
+  import { ref } from 'vue'
+
+  const open = ref(true)
+</script>
+
+<template>
+  <MazBtn v-tooltip.top="{ text: 'Tooltip text', open: open }">
+    Primary
+  </MazBtn>
+  <MazBtn color="secondary" @click="open = !open">
+    Toggle tooltip
+  </MazBtn>
+</template>
+```
+
+## Conditionally disable
+
+Pass `false`, `null` or `undefined` as the binding value to silently disable the tooltip - no popover instance is created, no listeners are attached, and no warning is logged. This is the recommended way to skip the tooltip on the fly without conditionally rendering two different elements:
+
+```vue
+<script lang="ts" setup>
+import { vTooltip } from 'maz-ui/directives'
+import { computed, ref } from 'vue'
+
+const label = ref<string>('')
+const tooltipBinding = computed(() => label.value ? { text: label.value } : false)
+</script>
+
+<template>
+  <!-- When label is empty the directive becomes a no-op -->
+  <MazBtn v-tooltip="tooltipBinding">
+    Hover me
+  </MazBtn>
+</template>
+```
+
+If the binding switches back to a valid value later, the tooltip mounts as expected. Toggling the value off again destroys the existing popover instance.
+
+## Global install
+
+### Vue
+
+```typescript
+import { vTooltipInstall } from 'maz-ui/directives'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+// Options are optional
+app.use(vTooltipInstall, {
+  position: 'top',
+  color: 'primary',
+})
+
+app.mount('#app')
+```
+
+### Nuxt
+
+Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.
+
+## Types
+
+```ts
+interface VTooltipOptions extends Partial<Omit<MazPopoverProps, 'modelValue'>> {
+  /**
+   * Text to display in the tooltip
+   */
+  text?: string
+  /**
+   * HTML content (alternative to text)
+   */
+  html?: string
+  /**
+   * Color variant of the tooltip
+   * @default default
+   */
+  color?: MazPopoverProps['color']
+  /**
+   * Position of the tooltip
+   * @default top
+   */
+  position?: PopoverPosition
+  /**
+   * Trigger of the tooltip
+   * @default hover
+   */
+  trigger?: MazPopoverTrigger
+  /**
+   * Close on click outside
+   * @default false
+   */
+  closeOnClickOutside?: boolean
+  /**
+   * Close on escape
+   * @default false
+   */
+  closeOnEscape?: boolean
+
+  /**
+   * Open the tooltip
+   * @default false
+   */
+  open?: boolean
+}
+
+type VTooltipBindingValue
+  = | string
+    | VTooltipOptions
+```

package/docs/directives/zoom-img.md

@@ -0,0 +1,100 @@
+---
+title: "vZoomImg"
+description: "vZoomImg is a Vue directive to enlarge an image like a modal on click, if you have several images, you can pass them like a carousel"
+package: "maz-ui"
+url: "https://maz-ui.com/directives/zoom-img"
+---
+
+# vZoomImg
+
+> vZoomImg is a Vue directive to enlarge an image like a modal on click, if you have several images, you can pass them like a carousel
+
+- Package: `maz-ui`
+- Import: `import { vZoomImg } from 'maz-ui/directives/vZoomImg'`
+- Web: https://maz-ui.com/directives/zoom-img
+
+> Can be mixed with [vLazyImg](./lazy-img.md) directive
+
+## Basic usage
+
+> Click on the photo
+
+```vue
+<script lang="ts" setup>
+import { vZoomImg } from 'maz-ui/directives'
+</script>
+
+<template>
+  <MazCard overflow-hidden>
+    <img
+      v-zoom-img="{ src: 'https://placedog.net/1500/1000' }"
+      src="https://placedog.net/1500/1000"
+    >
+  </MazCard>
+
+  <MazBtn v-zoom-img="{ src: 'https://placedog.net/1000/500' }">
+    Show photo
+  </MazBtn>
+</template>
+```
+
+## Options
+
+```vue
+<script lang="ts" setup>
+import { vZoomImg, type vZoomImgBindingValue } from 'maz-ui/directives'
+
+const zoomImgBinding: vZoomImgBindingValue = {
+  src: 'https://placedog.net/1200/800',
+  alt: 'alt image', // will be set on the zoomed image
+  blur: false,
+  scale: false,
+  disabled: false
+}
+</script>
+
+<template>
+  <MazCard overflow-hidden>
+    <img
+      v-zoom-img="zoomImgBinding"
+      src="https://placedog.net/1200/800"
+    >
+  </MazCard>
+</template>
+```
+
+## Global install
+
+### Vue
+
+```typescript
+import { vZoomImgInstall, type vZoomImgOptions } from 'maz-ui/directives'
+import { createApp } from 'vue'
+
+const app = createApp(App)
+
+app.use(vZoomImgInstall)
+
+app.mount('#app')
+```
+
+### Nuxt
+
+Please refer to the [Nuxt module documentation](../ecosystem/nuxt.md) for more information.
+
+## Types
+
+```ts
+export interface vZoomImgOptions {
+  disabled?: boolean
+  scale?: boolean
+  blur?: boolean
+}
+
+interface vZoomImgBindingOptions extends vZoomImgOptions {
+  src: string
+  alt?: string
+}
+
+export type vZoomImgBindingValue = string | vZoomImgBindingOptions
+```