@maz-ui/mcp 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -0,0 +1,239 @@
+---
+title: useDrag
+description: useDrag is a Vue composable that tracks a pointer drag gesture (touch, mouse and pen) in real time, exposing the live offset, distance and direction.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Introduction
+
+`useDrag` follows a pointer drag on an element and gives you the **live** offset, distance and direction, plus `onStart` / `onMove` / `onEnd` callbacks. It is the low-level gesture primitive behind components like [MazBottomSheet](../components/maz-bottom-sheet.md) (drag-to-dismiss), and it's useful to build sliders, sortable handles, swipeable cards, bottom sheets, custom carousels, etc.
+
+It is built on top of [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events), so it works with **touch, mouse and pen**.
+
+::: tip
+For discrete directional swipe detection (left / right / up / down with a threshold) rather than real-time tracking, use [useSwipe](./use-swipe.md).
+:::
+
+## Key Features
+
+- Real-time pointer tracking (touch, mouse and pen)
+- Live reactive state: `isDragging`, `offsetX`, `offsetY`, `distance`, `direction`
+- `onStart` / `onMove` / `onEnd` callbacks with a full state snapshot
+- Axis locking (`x`, `y` or `both`)
+- Activation threshold, pointer-type filtering and reactive `disabled`
+- Listeners are followed on the document, so the drag keeps working when the pointer leaves the element
+- Automatically attaches/detaches when the target appears/disappears, and cleans up on unmount
+
+## Basic Usage
+
+Drag the card down: it follows your pointer and snaps back on release.
+
+<div class="drag-demo">
+  <div
+    ref="dragHandle"
+    class="drag-card"
+    :class="{ '--dragging': dragging }"
+    :style="{ transform: dragOffset ? `translateY(${dragOffset}px)` : undefined }"
+  >
+    {{ dragging ? `Dragging — ${Math.round(dragOffset)}px ${dragDirection ?? ''}` : 'Drag me down' }}
+  </div>
+</div>
+
+```vue
+<script lang="ts" setup>
+import { useDrag } from 'maz-ui/composables'
+import { ref } from 'vue'
+
+const dragHandle = ref<HTMLElement>()
+const dragOffset = ref(0)
+
+const { isDragging: dragging, direction: dragDirection } = useDrag(dragHandle, {
+  axis: 'y',
+  onMove: ({ offsetY }) => {
+    dragOffset.value = Math.max(0, offsetY)
+  },
+  onEnd: ({ offsetY }) => {
+    if (offsetY > 150) {
+      // trigger an action when dragged far enough
+    }
+    dragOffset.value = 0
+  },
+})
+</script>
+
+<template>
+  <div
+    ref="dragHandle"
+    class="drag-card"
+    :class="{ '--dragging': dragging }"
+    :style="{ transform: dragOffset ? `translateY(${dragOffset}px)` : undefined }"
+  >
+    {{ dragging ? `Dragging — ${Math.round(dragOffset)}px ${dragDirection ?? ''}` : 'Drag me down' }}
+  </div>
+</template>
+
+<style>
+.drag-card {
+  touch-action: none;
+  cursor: grab;
+  user-select: none;
+}
+.drag-card:not(.--dragging) {
+  transition: transform 0.25s ease;
+}
+</style>
+```
+
+## Options
+
+`useDrag(target, options)` - the `target` is a `MaybeRefOrGetter<HTMLElement | string | null | undefined>` and `options` accepts:
+
+```ts
+interface UseDragOptions {
+  /**
+   * Restrict the tracking to a single axis. Off-axis movement is ignored.
+   * @default 'both'
+   */
+  axis?: 'x' | 'y' | 'both'
+  /**
+   * Minimum distance (px) the pointer must travel before the drag becomes active.
+   * @default 0
+   */
+  threshold?: number
+  /**
+   * Pointer types allowed to initiate the drag.
+   * @default ['mouse', 'touch', 'pen']
+   */
+  pointerTypes?: ('mouse' | 'touch' | 'pen')[]
+  /**
+   * Reactively disable the gesture.
+   * @default false
+   */
+  disabled?: MaybeRefOrGetter<boolean>
+  /**
+   * Call `event.preventDefault()` on each pointer move while dragging.
+   * @default false
+   */
+  preventDefault?: boolean
+  /**
+   * Call `event.stopPropagation()` on the pointer events.
+   * @default false
+   */
+  stopPropagation?: boolean
+  /**
+   * Attach the listeners as soon as the target is available. When `false`, call `start()` manually.
+   * @default true
+   */
+  immediate?: boolean
+  /** Called once when the drag becomes active (threshold reached). */
+  onStart?: (state: DragState) => void
+  /** Called on every pointer move while dragging. */
+  onMove?: (state: DragState) => void
+  /** Called when the drag ends (pointer up or cancel). */
+  onEnd?: (state: DragState) => void
+}
+```
+
+Each callback receives a `DragState` snapshot:
+
+```ts
+interface DragState {
+  /** Pointer offset from the drag start on the X axis (`0` when axis is `'y'`). */
+  offsetX: number
+  /** Pointer offset from the drag start on the Y axis (`0` when axis is `'x'`). */
+  offsetY: number
+  /** Absolute distance dragged from the start. */
+  distance: number
+  /** Dominant direction of the drag. */
+  direction: 'up' | 'down' | 'left' | 'right' | undefined
+  /** Pointer position when the drag started. */
+  startX: number
+  startY: number
+  /** Current pointer position. */
+  x: number
+  y: number
+  /** The underlying pointer event. */
+  event: PointerEvent
+}
+```
+
+## Composable Return
+
+```ts
+interface UseDragReturn {
+  /** Whether a drag is currently active (threshold reached). */
+  isDragging: Readonly<Ref<boolean>>
+  /** Reactive pointer offset from the drag start on the X axis. */
+  offsetX: Readonly<Ref<number>>
+  /** Reactive pointer offset from the drag start on the Y axis. */
+  offsetY: Readonly<Ref<number>>
+  /** Reactive absolute distance dragged from the start. */
+  distance: Readonly<Ref<number>>
+  /** Reactive dominant direction of the drag. */
+  direction: Readonly<Ref<'up' | 'down' | 'left' | 'right' | undefined>>
+  /** Manually attach the listeners. */
+  start: () => void
+  /** Manually detach the listeners (also cancels an ongoing drag). */
+  stop: () => void
+}
+```
+
+## Notes
+
+- Add `touch-action: none` on the draggable element to prevent the browser from scrolling while dragging.
+- The composable attaches automatically on mount (`immediate: true` by default) and cleans up on unmount; use `start()` / `stop()` for manual control.
+- `onEnd` only fires when an actual drag happened (the threshold was reached), so a simple tap will not trigger it.
+- The target can be a ref, a getter or a CSS selector string, and the listeners re-attach automatically when it changes.
+
+<script lang="ts" setup>
+import { useDrag } from 'maz-ui/composables/useDrag'
+import { ref } from 'vue'
+
+const dragHandle = ref()
+const dragOffset = ref(0)
+
+const { isDragging: dragging, direction: dragDirection } = useDrag(dragHandle, {
+  axis: 'y',
+  onMove: ({ offsetY }) => {
+    dragOffset.value = Math.max(0, offsetY)
+  },
+  onEnd: () => {
+    dragOffset.value = 0
+  },
+})
+</script>
+
+<style>
+.drag-demo {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 12px;
+  padding: 1rem;
+  height: 220px;
+  display: flex;
+  justify-content: center;
+  align-items: flex-start;
+  overflow: hidden;
+}
+.drag-card {
+  touch-action: none;
+  cursor: grab;
+  user-select: none;
+  width: 100%;
+  max-width: 320px;
+  padding: 2.5rem 1rem;
+  border-radius: 12px;
+  text-align: center;
+  font-size: 1.1rem;
+  color: white;
+  background: var(--vp-c-brand-1, #6366f1);
+}
+.drag-card:not(.--dragging) {
+  transition: transform 0.25s ease;
+}
+.drag-card.--dragging {
+  cursor: grabbing;
+}
+</style>

package/docs/src/composables/use-form-validator.md

@@ -151,7 +151,7 @@ Each field in `fieldsStates` contains:
         v-model="stateModel.age"
         label="Age (18-100)"
         type="number"
-        :hint="stateErrors.age"s
+        :hint="stateErrors.age"
         :error="!!stateErrors.age"
         :success="stateFields.age.valid"
       />
@@ -365,7 +365,7 @@ Requires `useFormField` with `ref` option or `validationEvents`.
       :success="eagerEmailValid"
       :class="{ 'has-error-eager': eagerEmailHasError }"
     />
-    <MazBtn type="submit" :loading="eagerSubmitting">Submit</MazBtn>
+    <MazBtn type="submit" :loading="eagerSubmitting" :disabled="!eagerIsValid">Submit</MazBtn>
   </form>
 
   <template #code>
@@ -381,7 +381,7 @@ const schema = {
   email: pipe(string(), nonEmpty('Required'), email('Invalid email')),
 }
 
-const { isSubmitting, handleSubmit } = useFormValidator({
+const { isSubmitting, handleSubmit, isValid } = useFormValidator({
   schema,
   options: {
     mode: 'eager',
@@ -430,6 +430,8 @@ const {
       :error="emailHasError"
       :success="emailValid"
     />
+
+    <MazBtn type="submit" :loading="isSubmitting" :disabled="!isValid">Submit</MazBtn>
   </form>
 </template>
 ```
@@ -614,6 +616,8 @@ const { value: name, hasError, errorMessage, isValid } = useFormField<string>('n
 
 Pass a template ref to `useFormField`. It will automatically detect interactive elements and attach blur listeners.
 
+The `ref` option is **reactive**: if the field is rendered conditionally (e.g. with `v-if`), the blur listeners are attached automatically as soon as the element appears in the DOM, and removed when it is unmounted. You don't need to handle anything special.
+
 ```vue
 <script setup>
 import { useFormField } from 'maz-ui/composables'
@@ -635,6 +639,41 @@ const { value, errorMessage, hasError } = useFormField<string>('email', {
 </template>
 ```
 
+Because it is reactive, the same code works even when the input is wrapped in a `v-if`:
+
+```vue
+<script setup>
+import { useFormField } from 'maz-ui/composables'
+import { useTemplateRef, ref } from 'vue'
+
+const isVisible = ref(false)
+
+const { value, errorMessage, hasError } = useFormField<string>('email', {
+  ref: useTemplateRef('emailRef'),
+  formIdentifier: 'my-form',
+})
+</script>
+
+<template>
+  <MazInput
+    v-if="isVisible"
+    ref="emailRef"
+    v-model="value"
+    :hint="errorMessage"
+    :error="hasError"
+  />
+</template>
+```
+
+You can also pass a raw `HTMLElement` directly. In that case it won't be reactive, so the element must already exist in the DOM:
+
+```ts
+const { value } = useFormField<string>('email', {
+  ref: document.querySelector('input'),
+  formIdentifier: 'my-form',
+})
+```
+
 #### Option 2: Using `validationEvents`
 
 If your component emits a `blur` event, you can use `v-bind` with `validationEvents`.
@@ -1074,7 +1113,7 @@ useFormField<FieldType>(
   options?: {
     defaultValue?: FieldType,                         // Default value for this field
     mode?: 'lazy' | 'aggressive' | 'eager' | 'blur' | 'progressive', // Override form mode
-    ref?: Ref<HTMLElement | ComponentInstance>,       // Template ref for blur detection
+    ref?: Ref<HTMLElement | ComponentInstance> | HTMLElement, // Reactive template ref (v-if friendly) or raw element
     formIdentifier?: string | symbol,                 // Must match useFormValidator's identifier
   }
 )
@@ -1113,7 +1152,7 @@ interface FormValidatorOptions<Model> {
 interface FormFieldOptions<FieldType> {
   defaultValue?: FieldType
   mode?: 'eager' | 'lazy' | 'aggressive' | 'blur' | 'progressive'
-  ref?: Ref<HTMLElement | ComponentInstance>
+  ref?: Ref<HTMLElement | ComponentInstance> | HTMLElement
   formIdentifier?: string | symbol
 }
 
@@ -1166,14 +1205,13 @@ const { value, validationEvents } = useFormField<string>('name')
 // Then: v-bind="validationEvents" on your input
 ```
 
-### Element Not Found Warning
+### Conditionally Rendered Fields (`v-if`)
 
-**Problem**: `No element found for ref in field 'name'`
+The `ref` option is reactive, so a field wrapped in `v-if` works out of the box: blur listeners are attached as soon as the element is rendered and removed when it is unmounted.
 
-**Solutions**:
-1. Ensure the ref is bound to an HTML element or Vue component
-2. Make sure the component has a `$el` property
-3. For custom components, add `data-interactive` attribute
+If blur validation still doesn't trigger:
+1. Ensure the `ref` is bound to an HTML element or a Vue component exposing `$el`
+2. For custom components, add the `data-interactive` attribute
 
 ### Mismatched Form Identifiers
 
@@ -1310,6 +1348,7 @@ const eagerSchema = {
 const {
   isSubmitting: eagerSubmitting,
   handleSubmit: handleEager,
+  isValid: eagerIsValid,
 } = useFormValidator({
   schema: eagerSchema,
   options: { mode: 'eager', scrollToError: '.has-error-eager', identifier: 'form-eager' },

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

@@ -12,11 +12,19 @@ description: useSwipe is a Vue composable that simplifies the management of "swi
 `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.
 
+It is built on top of [Pointer Events](https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events), so it works with **touch, mouse and pen** out of the box.
+
+::: tip
+For a real-time drag gesture (follow the pointer, snap back, drag-to-dismiss…) rather than discrete directional detection, use [useDrag](./use-drag.md).
+:::
+
 ## Key Features
 
 - Detects swipes in all 4 directions (left, right, up, down)
+- Works with touch, mouse and pen (Pointer Events)
 - Provides key information about the swipe movement (start/end coordinates, horizontal/vertical distance)
 - Allows you to configure callbacks for each swipe direction
+- Restrict the gesture to specific pointer types
 - Possibility to customize the swipe detection threshold
 - Automatically handles the addition and removal of event listeners
 - Can be used with any HTML element
@@ -27,7 +35,7 @@ You can use this information to implement specific interactions in your applicat
   <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)
+      (works with touch, mouse and pen)
     </span>
     <br><br>
     Last swipe direction: {{lastSwipeDirection || 'None'}}
@@ -74,7 +82,7 @@ onUnmounted(() => {
     <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)
+        (works with touch, mouse and pen)
       </span>
       <br><br>
       Last swipe direction: {{ lastSwipeDirection || 'None' }}
@@ -153,35 +161,41 @@ interface UseSwipeOptions {
    */
   element: HTMLElement | string | Ref<HTMLElement>
   /** Callback executed when a left swipe is detected. */
-  onLeft?: (event: TouchEvent) => void
+  onLeft?: (event: PointerEvent) => void
   /** Callback executed when a right swipe is detected. */
-  onRight?: (event: TouchEvent) => void
+  onRight?: (event: PointerEvent) => void
   /** Callback executed when an up swipe is detected. */
-  onUp?: (event: TouchEvent) => void
+  onUp?: (event: PointerEvent) => void
   /** Callback executed when a down swipe is detected. */
-  onDown?: (event: TouchEvent) => void
+  onDown?: (event: PointerEvent) => 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.
+   * Pointer types that can trigger the swipe.
+   * @default ['mouse', 'touch', 'pen']
+   */
+  pointerTypes?: ('mouse' | 'touch' | 'pen')[]
+  /**
+   * Whether to prevent the default behavior of the pointer move event
+   * (the move listener becomes non-passive when enabled).
    * @default false
    */
-  preventDefaultOnTouchMove?: boolean
+  preventDefaultOnMove?: 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.
+   * Whether to start listening immediately on instantiation.
    * @default false
    */
   immediate?: boolean
   /**
-   * Whether to trigger the swipe event only on touchend/mouseup.
+   * Whether to trigger the swipe event only on pointer up.
    * @default false
    */
   triggerOnEnd?: boolean
@@ -220,4 +234,5 @@ interface UseSwipeReturn {
 - 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.
+- If you want to prevent the default behavior of pointer move or mousewheel events, you can set the `preventDefaultOnMove` and `preventDefaultOnMouseWheel` options, respectively.
+- Use the `pointerTypes` option to restrict the gesture to specific input types (e.g. `['touch']` for touch-only).

package/docs/src/directives/click-outside.md

@@ -11,8 +11,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -21,8 +20,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -44,8 +42,7 @@ function clikedOutside() {
 
 <template>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -54,8 +51,7 @@ function clikedOutside() {
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -71,8 +67,7 @@ The directive can accept an options object to customize its behavior:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOutsideWithIgnore, ignore: ['.ignore-me'] }">
       <div class="maz:p-4">
@@ -86,8 +81,7 @@ The directive can accept an options object to customize its behavior:
 
   <div
     v-if="hasClickedOutsideWithIgnore"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-warning); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside (button clicks are ignored)
   </div>
@@ -128,8 +122,7 @@ The directive can be configured to trigger only once:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOnce, once: true }">
       Click outside me (works only once)
@@ -249,7 +242,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 <script lang="ts" setup>
   import { ref } from 'vue'

package/docs/src/directives/fullscreen-img.md

@@ -83,7 +83,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 ## Types