@maz-ui/mcp 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/src/components/maz-window-mockup.md

@@ -0,0 +1,249 @@
+---
+title: MazWindowMockup
+description: MazWindowMockup renders a macOS-style window frame in three variants — browser, terminal, and editor — to showcase content, demos, or code examples in your documentation or UI.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+
+::: info Optional: shiki for code variants
+When you pass the `code` prop, `MazWindowMockup` mounts `MazCodeHighlight` internally for syntax highlighting. This requires the [`shiki`](https://shiki.style) optional peer dependency to be installed. See the [MazCodeHighlight installation note](/components/maz-code-highlight#installation-requirement).
+:::
+
+## Browser variant
+
+The default variant. Displays an address bar with the `url` prop and a copy-URL button on the right side of the bar.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <div style="padding: 1rem; text-align: center;">Browser content goes here</div>
+  </MazWindowMockup>
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <div>Browser content goes here</div>
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+### Hide the URL copy button
+
+Set `:hide-url-copy="true"` to remove the copy-URL button from the title bar.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="80px" :hide-url-copy="true" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="80px" :hide-url-copy="true" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### With screenshot
+
+Use this variant to display a screenshot of a website.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <img :src="screenshot" alt="Maz UI Demo Dashboard" width="100%">
+  </MazWindowMockup>
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="100px">
+    <img src="/img/screenshots/maz-ui-home-desktop.webp" alt="Maz UI Demo Dashboard" width="100%">
+  </MazWindowMockup>
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Terminal variant
+
+Displays a centered title and a `$` prompt prefix in front of the code (when `code` is provided). The prompt prefix is **not** copied to the clipboard — the copy button only writes the raw `code` value.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" title="zsh" code="pnpm add maz-ui" language="bash" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" title="zsh" code="pnpm add maz-ui" language="bash" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+### Custom prompt
+
+Replace the default `$` with any character via the `prompt` prop.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" prompt="❯" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" prompt="❯" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### Without prompt
+
+Hide the default prompt by setting `hide-prompt` to `true`.
+
+<ComponentDemo>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" :hide-prompt="true" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="terminal" code="git status" language="bash" :hide-prompt="true" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Editor variant
+
+Shows a filename tab anchored to the bottom of the title bar — matching the look of real editors like VSCode.
+
+<ComponentDemo>
+  <MazWindowMockup variant="editor" filename="App.vue" :code="vueCode" language="vue" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup variant="editor" filename="App.vue" :code="vueCode" language="vue" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+
+  const vueCode = `<template>
+  <MazBtn>Click me</MazBtn>
+</template>`
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## With code and language props
+
+Pass `code` and `language` to display highlighted source code via `MazCodeHighlight`. The inner highlighter automatically renders with squared corners so it sits flush against the window's border.
+
+<ComponentDemo>
+  <MazWindowMockup code="import MazBtn from 'maz-ui/components/MazBtn'" language="ts" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup code="import MazBtn from 'maz-ui/components/MazBtn'" language="ts" />
+</template>
+
+<script lang="ts" setup>
+  import MazWindowMockup from 'maz-ui/components/MazWindowMockup'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Empty-state placeholder
+
+When neither `code` nor a slot content is provided, the content area renders an empty placeholder. Pass the optional `label` prop to display a centered text inside it.
+
+<ComponentDemo>
+  <MazWindowMockup url="https://maz-ui.com" min-height="160px" label="Preview" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup url="https://maz-ui.com" min-height="160px" label="Preview" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Custom translations
+
+The URL copy button's aria-label and tooltip come from the `@maz-ui/translations` package (`windowMockup.copyUrlToClipboard` / `windowMockup.urlCopiedToClipboard`). Override per-instance with the `translations` prop:
+
+<ComponentDemo>
+  <MazWindowMockup
+    url="https://maz-ui.com"
+    min-height="80px"
+    :translations="{ copyUrlToClipboard: 'Copier l\'URL', urlCopiedToClipboard: 'URL copiée !' }"
+  />
+
+  <template #code>
+
+```vue
+<template>
+  <MazWindowMockup
+    url="https://maz-ui.com"
+    min-height="80px"
+    :translations="{
+      copyUrlToClipboard: 'Copier l\'URL',
+      urlCopiedToClipboard: 'URL copiée !',
+    }"
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+For app-wide translations, set up the [maz-ui translations plugin](/translations) and the component will pick up your locale automatically.
+
+<script lang="ts" setup>
+  import screenshot from './../assets/interface-screenshot.png'
+
+  const vueCode = `<template>
+  <MazBtn>Click me</MazBtn>
+</template>`
+</script>
+
+<!--@include: ./../../.vitepress/generated-docs/maz-window-mockup.doc.md-->

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>