maz-ui 5.0.0 → 5.1.0-beta.0

package/docs/composables/use-display-names.md

@@ -0,0 +1,130 @@
+---
+title: "useDisplayNames"
+description: "useDisplayNames is a Vue composable specialized in displaying localized country names (regions) and language names. It supports various code formats including ISO 639-1 (language codes), ISO 3166-1 (country codes), and BCP 47 (language tags), using the Intl.DisplayNames API for internationalization."
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-display-names"
+---
+
+# useDisplayNames
+
+> useDisplayNames is a Vue composable specialized in displaying localized country names (regions) and language names. It supports various code formats including ISO 639-1 (language codes), ISO 3166-1 (country codes), and BCP 47 (language tags), using the Intl.DisplayNames API for internationalization.
+
+- Package: `maz-ui`
+- Import: `import { useDisplayNames } from 'maz-ui/composables/useDisplayNames'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-display-names
+
+## Introduction
+
+`useDisplayNames` allows you to fetch and format localized country names and language names using the `Intl.DisplayNames` API. It supports multiple code formats (ISO 639-1, ISO 3166-1, BCP 47) and is particularly useful for applications that need to display human-readable country or language names based on different locales.
+
+**Warning:**
+
+Depending on your environment (client or node server) and the browser you are using, the `Intl.DisplayNames` results can be differents (e.g, Firefox and Chrome can return different results).
+
+## Key Features
+
+- Displays localized country names (regions) and language names
+- Supports multiple code formats: ISO 639-1 (language codes), ISO 3166-1 (country codes), and BCP 47 (language tags)
+- Works with any locale supported by the browser's Intl.DisplayNames API
+- Provides functions to get individual names or bulk retrieve all available names
+- Handles errors gracefully with fallback values
+- Smart filtering and sorting options for comprehensive lists
+
+## Basic Usage
+
+To see `useDisplayNames` in action, you can try out the following demo. This demo showcases how to use the composable to fetch and display localized language names dynamically based on user input.
+
+```vue
+<script lang="ts" setup>
+import { useDisplayNames } from 'maz-ui/composables/useDisplayNames'
+import { computed, ref } from 'vue'
+
+const selectedLocale = ref('en-US')
+const code = ref('')
+
+const { getDisplayName, getAllDisplayNames } = useDisplayNames(selectedLocale)
+
+const languageDisplayName = getDisplayName(code, { type: 'language' })
+
+const localeOptions = getAllDisplayNames({ type: 'language' })
+</script>
+
+<template>
+  <MazSelect
+    v-model="selectedLocale"
+    label="Select a locale"
+    :max-list-height="350"
+    :options="[
+      { value: 'en-US', label: 'English (en-US)' },
+      { value: 'fr-FR', label: 'French (fr-FR)' },
+      { value: 'es-ES', label: 'Spanish (es-ES)' },
+      { value: 'zh-CN', label: 'Chinese (zh-CN)' },
+      { value: 'de-DE', label: 'German (de-DE)' },
+      { value: 'it-IT', label: 'Italian (it-IT)' },
+      { value: 'ja-JP', label: 'Japanese (ja-JP)' },
+      { value: 'ko-KR', label: 'Korean (ko-KR)' },
+      { value: 'pt-BR', label: 'Portuguese (pt-BR)' },
+      { value: 'ru-RU', label: 'Russian (ru-RU)' },
+    ]"
+    search
+  />
+  <MazSelect
+    v-model="code"
+    label="Select a language"
+    :options="localeOptions?.map(({ name, code }) => ({
+      label: `${name} (${code})`,
+      value: code
+    }))"
+    search
+  />
+  <p>Translated Language: {{ languageDisplayName || 'undefined' }}</p>
+</template>
+```
+
+In this example, the `useDisplayNames` composable is used to fetch and display the language name based on the selected locale and language code (ISO 639-1 or BCP 47 format).
+
+The returned value is reactive and will update automatically when the locale or language code changes if arguments are reactive (use ref or computed).
+
+## Functions
+
+`useDisplayNames` can take a locale as argument to avoid passing this value each time you call the functions. This is useful when you need to fetch multiple country or language names based on the same locale.
+
+It provides the following functions:
+
+### `getDisplayName`
+
+Fetches the localized display name of a country (region) or language based on the provided locale and code (supports ISO 639-1, ISO 3166-1, and BCP 47 formats).
+
+```ts
+function getDisplayName(code: MaybeRefOrGetter<string>, options: {
+  type: MaybeRefOrGetter<Intl.DisplayNamesOptions['type']>,
+  locale?: MaybeRefOrGetter<string>
+}): ComputedRef<string | undefined>
+```
+
+### `getAllDisplayNames`
+
+Fetches the localized display names for all available countries (regions) or languages for a given locale. Supports filtering by code type (ISO 639-1, ISO 3166-1, BCP 47, or all).
+
+```ts
+function getAllDisplayNames(options: {
+  type: MaybeRefOrGetter<Intl.DisplayNamesOptions['type']>,
+  locale?: MaybeRefOrGetter<string>,
+  codes?: MaybeRefOrGetter<string[]>,
+  exclude?: MaybeRefOrGetter<string[]>,
+  preferred?: MaybeRefOrGetter<string[]>,
+  onlyIso?: MaybeRefOrGetter<boolean>,
+  onlyBcp?: MaybeRefOrGetter<boolean>,
+}): ComputedRef<{ name: string, code: string }[]>
+```
+
+## Notes
+
+- The `useDisplayNames` composable is designed to be used with Vue.
+- The composable functions return `ComputedRef` values, which are reactive and will update automatically when their dependencies change.
+- Handle errors gracefully by providing fallback values when the display name cannot be fetched.
+- The `Intl.DisplayNames` API is used internally to fetch and format the display names based on the provided locale and code.
+- The composable supports multiple locales, allowing you to fetch country and language names in different languages.
+- Use the `getAllDisplayNames` function to fetch comprehensive lists of countries or languages with advanced filtering options.
+- Supports various code formats: ISO 639-1 (language codes like 'en', 'fr'), ISO 3166-1 (country codes like 'US', 'FR'), and BCP 47 (language tags like 'en-US', 'fr-FR').

package/docs/composables/use-drag.md

@@ -0,0 +1,185 @@
+---
+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."
+package: "maz-ui"
+url: "https://maz-ui.com/composables/use-drag"
+---
+
+# useDrag
+
+> 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.
+
+- Package: `maz-ui`
+- Import: `import { useDrag } from 'maz-ui/composables/useDrag'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/composables/use-drag
+
+## 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.
+
+```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.