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

package/docs/src/components/maz-markdown-editor.md

@@ -0,0 +1,369 @@
+---
+title: MazMarkdownEditor
+description: MazMarkdownEditor is a GitHub-style markdown editor with Write/Preview/Split tabs, a configurable formatting toolbar, optional line numbers, and a sanitized preview. It shares the same states, labels and theming as MazTextarea, is SSR-friendly, and supports custom renderers.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+
+## Installation requirement
+
+The preview relies on [`marked`](https://marked.js.org) for parsing and [`dompurify`](https://github.com/cure53/DOMPurify) for sanitization. Both are loaded lazily (only when the preview is rendered), so install them in your project:
+
+::: code-group
+
+```bash [pnpm]
+pnpm add marked dompurify
+```
+
+```bash [npm]
+npm install marked dompurify
+```
+
+```bash [yarn]
+yarn add marked dompurify
+```
+
+:::
+
+If they are not installed, the preview falls back to a safe, escaped plain-text block. You can also provide your own renderer with the [`renderFunction`](#custom-renderer) prop to avoid these dependencies entirely.
+
+## Basic usage
+
+The component exposes a `v-model` bound to the raw markdown string and two tabs: **Write** (textarea) and **Preview** (rendered, sanitized HTML).
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="basic" placeholder="markdown goes here" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazMarkdownEditor from 'maz-ui/components/MazMarkdownEditor'
+
+  const content = ref('# Hello maz-ui\n\nThis is **markdown** with a [link](https://maz-ui.com).')
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Toolbar
+
+The formatting toolbar is opt-in. Set `toolbar` to `true` to display the full toolbar. Buttons act on the current textarea selection and preserve the native undo/redo history (`Cmd/Ctrl + Z`).
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="withToolbar" toolbar />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" toolbar />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazMarkdownEditor from 'maz-ui/components/MazMarkdownEditor'
+
+  const content = ref('Select some text and click **Bold**.')
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+### Available actions
+
+The full toolbar exposes the following action keys:
+
+| Key | Result |
+| --- | --- |
+| `heading` | Heading dropdown (`#`, `##`, `###`) |
+| `bold` | `**bold**` |
+| `italic` | `_italic_` |
+| `strikethrough` | `~~strikethrough~~` |
+| `quote` | `> quote` |
+| `code` | `` `inline code` `` |
+| `codeBlock` | fenced ` ``` ` code block |
+| `link` | `[text](url)` |
+| `image` | `![alt](url)` |
+| `bulletList` | `- item` |
+| `orderedList` | `1. item` |
+| `checkList` | `- [ ] task` |
+| `table` | markdown table skeleton |
+
+### Configure the toolbar
+
+Pass an **ordered array of action keys** to display only a subset (and control their order):
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="withToolbarConfig" :toolbar="['heading', 'bold', 'italic', 'link', 'codeBlock']" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor
+    v-model="content"
+    :toolbar="['heading', 'bold', 'italic', 'link', 'codeBlock']"
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Keyboard shortcuts
+
+Classic markdown shortcuts are enabled by default and work whenever the textarea is focused. They preserve the native undo/redo history. The toolbar buttons also display their shortcut in the tooltip. Use `mod` for `Cmd` on macOS and `Ctrl` elsewhere.
+
+| Shortcut | Action |
+| --- | --- |
+| `mod + B` | Bold |
+| `mod + I` | Italic |
+| `mod + Shift + X` | Strikethrough |
+| `mod + K` | Link |
+| `mod + E` | Inline code |
+| `mod + Shift + E` | Code block |
+| `mod + Shift + .` | Quote |
+| `mod + Shift + 8` | Bulleted list |
+| `mod + Shift + 7` | Numbered list |
+| `mod + Shift + L` | Task list |
+| `mod + Alt + 1/2/3` | Heading 1/2/3 |
+
+Disable them with `:shortcuts="false"`:
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" toolbar :shortcuts="false" />
+</template>
+```
+
+::: tip
+Image and table insertions have no default shortcut (to avoid clashing with browser shortcuts). Use the toolbar buttons or the `toolbar` slot helpers for those.
+:::
+
+## List continuation
+
+Pressing <kbd>Enter</kbd> inside a list automatically inserts the next marker, just like a desktop markdown editor:
+
+- Bulleted lists (`-`, `*`, `+`) repeat the marker.
+- Numbered lists increment the index (`1.` → `2.`).
+- Task lists insert a fresh unchecked box (`- [ ] `).
+- Indentation is preserved.
+
+Pressing <kbd>Enter</kbd> again on an empty item removes the marker and exits the list. This works out of the box, no configuration required.
+
+## Label & assistive text
+
+Like `MazTextarea`, the editor supports a static `top-label` (or `label`), the `required` asterisk and an `assistive-text` displayed below the editor.
+
+<ComponentDemo>
+  <MazMarkdownEditor
+    v-model="withLabel"
+    top-label="Description"
+    placeholder="Markdown goes here"
+    assistive-text="Markdown is supported"
+    required
+  />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor
+    v-model="content"
+    top-label="Description"
+    assistive-text="Markdown is supported"
+    required
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## States
+
+Use `error`, `success`, `warning`, `disabled` and `readonly` to reflect validation states, consistent with the other form components.
+
+<ComponentDemo>
+  <div class="maz:flex maz:flex-col maz:gap-4">
+    <MazMarkdownEditor v-model="stateError" error assistive-text="This field has an error" />
+    <MazMarkdownEditor v-model="stateSuccess" success assistive-text="Looks good!" />
+    <MazMarkdownEditor v-model="stateDisabled" disabled />
+  </div>
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" error assistive-text="This field has an error" />
+  <MazMarkdownEditor v-model="content" success assistive-text="Looks good!" />
+  <MazMarkdownEditor v-model="content" disabled />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Split mode
+
+A third tab displays the editor and the preview side by side. Switch to it from the toolbar tabs, or control it with `v-model:mode` (`'write' | 'preview' | 'split'`). On small screens the two panes stack vertically.
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="splitContent" mode="split" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" mode="split" />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazMarkdownEditor from 'maz-ui/components/MazMarkdownEditor'
+
+  const content = ref('# Split view\n\nType on the left, see the **preview** on the right.')
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Line numbers
+
+Enable the `line-numbers` prop to display a gutter on the left of the editor. Numbers reflect logical lines and stay in sync with the textarea scroll.
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="lineNumbersContent" line-numbers />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" line-numbers />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Custom renderer {#custom-renderer}
+
+Provide a `render-function` to use your own markdown engine (e.g. `markdown-it`, a Nuxt Content renderer, or a server-side pipeline). It receives the raw markdown and returns an HTML string (sync or async). The result is still sanitized when `sanitize` is enabled.
+
+<ComponentDemo>
+  <MazMarkdownEditor v-model="customRender" :render-function="upperCaseRenderer" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" :render-function="renderer" />
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazMarkdownEditor from 'maz-ui/components/MazMarkdownEditor'
+
+  const content = ref('Rendered by a custom function')
+
+  function renderer(markdown: string) {
+    return `<p>${markdown.toUpperCase()}</p>`
+  }
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Sanitization
+
+By default, the rendered HTML is sanitized with DOMPurify to prevent XSS. Disabling it (`:sanitize="false"`) renders the raw output of the renderer; only do this when the markdown source is fully trusted.
+
+```vue
+<template>
+  <!-- Trusted content only -->
+  <MazMarkdownEditor v-model="content" :sanitize="false" />
+</template>
+```
+
+## Controlled mode
+
+The active tab is available through `v-model:mode` (`'write' | 'preview' | 'split'`).
+
+```vue
+<template>
+  <MazMarkdownEditor v-model="content" v-model:mode="mode" />
+  <p>Current tab: {{ mode }}</p>
+</template>
+
+<script lang="ts" setup>
+  import { ref } from 'vue'
+  import MazMarkdownEditor from 'maz-ui/components/MazMarkdownEditor'
+
+  const content = ref('')
+  const mode = ref<'write' | 'preview' | 'split'>('write')
+</script>
+```
+
+## Custom translations
+
+The tab labels, the empty-preview text and the toolbar button labels come from the `@maz-ui/translations` package (`markdownEditor.*`). You can override any key per-instance with the `translations` prop without touching the global locale:
+
+<ComponentDemo>
+  <MazMarkdownEditor
+    v-model="translated"
+    toolbar
+    :translations="{ write: 'Édition', preview: 'Aperçu', emptyPreview: 'Rien à afficher' }"
+  />
+
+  <template #code>
+
+```vue
+<template>
+  <MazMarkdownEditor
+    v-model="content"
+    toolbar
+    :translations="{ write: 'Édition', preview: 'Aperçu', emptyPreview: 'Rien à afficher' }"
+  />
+</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 { ref } from 'vue'
+
+  const basic = ref('# Hello maz-ui\n\nThis is **markdown** with a [link](https://maz-ui.com).')
+  const withToolbar = ref('Select some text and click **Bold**.')
+  const withToolbarConfig = ref('Only a few buttons here.')
+  const splitContent = ref('# Split view\n\nType on the left, see the **preview** on the right.')
+  const lineNumbersContent = ref('Line one\nLine two\nLine three')
+  const withLabel = ref('')
+  const stateError = ref('Invalid content')
+  const stateSuccess = ref('Valid content')
+  const stateDisabled = ref('Disabled editor')
+  const customRender = ref('Rendered by a custom function')
+  const translated = ref('Localized **markdown** editor.')
+
+  function upperCaseRenderer(markdown: string) {
+    return `<p>${markdown.toUpperCase()}</p>`
+  }
+</script>
+
+<!--@include: ./../../.vitepress/generated-docs/maz-markdown-editor.doc.md-->

package/docs/src/components/maz-pull-to-refresh.md

@@ -1,6 +1,6 @@
 ---
 title: MazPullToRefresh
-description: MazPullToRefresh is a standalone component to add pull to refresh feature
+description: MazPullToRefresh adds a native-feeling pull to refresh gesture to your app or to any scroll container, with a progress ring, haptic feedback and translated, accessible feedback.
 ---
 
 # {{ $frontmatter.title }}
@@ -9,41 +9,200 @@ description: MazPullToRefresh is a standalone component to add pull to refresh f
 
 <!--@include: ./../../.vitepress/mixins/getting-started.md-->
 
+## Key Features
+
+- Works on the window **and on any scroll container**: the closest scrollable ancestor is detected automatically, so it fits app shells with a fixed layout and a scrolling `<main>`
+- Starts only when the container is scrolled to the top, never in the middle of a list
+- Rubber band resistance beyond the trigger distance, and a progress ring that fills while pulling
+- Ignores horizontal swipes and multi-touch gestures, and prevents the native bounce (and the browser's own pull to refresh) while pulling
+- Haptic feedback when the trigger distance is reached (devices supporting `navigator.vibrate`)
+- Texts from [@maz-ui/translations](./../ecosystem/translations.md), overridable with the `translations` prop or the slots
+- Accessible: the refresh is announced to screen readers, `aria-busy` is set while refreshing, and `refresh()` is exposed for a button usable with a keyboard or a mouse
+- Optional `standalone-mode` to enable it only in an installed PWA (browsers already have their own pull to refresh)
+- Built on the headless [usePullToRefresh](./../composables/use-pull-to-refresh.md) composable
+
 ## Demo
 
-![MazPullToRefresh](/img/maz-pull-to-refresh.gif)
+<div class="maz:flex maz:flex-col maz:items-center maz:gap-3 vp-raw">
+  <p class="maz:text-sm maz:text-muted">
+    Pull down inside the box on a touch device (or with the touch emulation of your browser's device toolbar).
+  </p>
+  <div class="maz:h-80 maz:w-full maz:max-w-sm maz:overflow-y-auto maz:rounded-lg maz:border maz:border-divider maz:bg-container">
+    <MazPullToRefresh ref="demo" :on-refresh="refreshDemo">
+      <ul class="maz:m-0 maz:list-none maz:p-0">
+        <li v-for="item in items" :key="item" class="maz:border-b maz:border-divider maz:px-4 maz:py-3">
+          {{ item }}
+        </li>
+      </ul>
+    </MazPullToRefresh>
+  </div>
+  <MazBtn size="sm" :loading="demo?.isRefreshing" @click="demo?.refresh()">
+    Refresh ({{ refreshCount }})
+  </MazBtn>
+</div>
+
+<script lang="ts" setup>
+import { ref, useTemplateRef } from 'vue'
+
+const demo = useTemplateRef('demo')
+const refreshCount = ref(0)
+const items = ref(Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`))
+
+async function refreshDemo() {
+  await new Promise(resolve => setTimeout(resolve, 1000))
+  refreshCount.value++
+  items.value = [`New item ${refreshCount.value}`, ...items.value]
+}
+</script>
 
 ## Basic usage
 
-Wrap your app inside this component
+Wrap your app (or a page) inside the component and give it the function that reloads your data. The spinner stays visible until the returned promise settles.
 
 ```vue
 <script lang="ts" setup>
 import MazPullToRefresh from 'maz-ui/components/MazPullToRefresh'
 
-async function pullToRefreshAction() {
-  // do promise or just `window.location.reload()`
+async function refresh() {
+  await fetchData()
 }
 </script>
 
+<template>
+  <MazPullToRefresh :on-refresh="refresh">
+    <main>App content</main>
+  </MazPullToRefresh>
+</template>
+```
+
+With Nuxt, `refreshNuxtData` reloads every `useFetch` / `useAsyncData` of the page:
+
+```vue
+<template>
+  <MazPullToRefresh :on-refresh="() => refreshNuxtData()" standalone-mode>
+    <NuxtPage />
+  </MazPullToRefresh>
+</template>
+```
+
+## Inside a scroll container
+
+The pull can only start when its scroll container is at the top. By default, the component uses its **closest scrollable ancestor** (`overflow-y: auto | scroll`), or the window if there is none. Typical app shells with a fixed layout and a scrolling `<main>` work without configuration:
+
+```vue
+<template>
+  <div class="app-shell maz:fixed maz:inset-0 maz:flex maz:flex-col">
+    <header>…</header>
+    <main class="maz:flex-1 maz:overflow-y-auto">
+      <MazPullToRefresh :on-refresh="refresh">
+        <slot />
+      </MazPullToRefresh>
+    </main>
+  </div>
+</template>
+```
+
+Use `container-selector` when the scroll container is not an ancestor of the component:
+
+```vue
+<template>
+  <MazPullToRefresh container-selector="#page-scroller" :on-refresh="refresh">
+    …
+  </MazPullToRefresh>
+</template>
+```
+
+## Installed apps only
+
+Browsers already provide their own pull to refresh. With `standalone-mode`, the component is only active when the app runs as an installed PWA (`display-mode: standalone`):
+
+```vue
+<template>
+  <MazPullToRefresh standalone-mode :on-refresh="refresh">
+    …
+  </MazPullToRefresh>
+</template>
+```
+
+## Tuning the gesture
+
+| Prop           | Default          | Effect                                                                                  |
+| -------------- | ---------------- | --------------------------------------------------------------------------------------- |
+| `distance`     | `80`             | Pull distance (px, after resistance) needed to trigger a refresh                        |
+| `max-distance` | `distance * 1.6` | Upper bound of the rubber band beyond `distance`                                        |
+| `resistance`   | `0.5`            | Ratio between the finger movement and the pull distance (lower is stiffer)              |
+| `min-duration` | `400`            | Minimum duration (ms) of the refreshing state, so fast refreshes still show the feedback |
+| `haptic`       | `true`           | Short vibration when `distance` is reached                                              |
+
+## Customize the indicator
+
+The three states have their own slot. Each one receives the pull `progress` (0 to 1) and the current `distance` in px.
+
+```vue
+<template>
+  <MazPullToRefresh :on-refresh="refresh" header-class="maz:bg-surface-600">
+    <template #pull-before="{ progress }">
+      <span>{{ Math.round(progress * 100) }}%</span>
+    </template>
+    <template #pull-ready>
+      <span>Let go!</span>
+    </template>
+    <template #pull-loading>
+      <MazSpinner color="secondary" />
+    </template>
+
+    <main>App content</main>
+  </MazPullToRefresh>
+</template>
+```
+
+`spinner-color` sets the color of the progress ring, the ready arrow and the default spinner (`primary` by default).
+
+## Translations
+
+Texts come from [@maz-ui/translations](./../ecosystem/translations.md) (`pullToRefresh.pull`, `pullToRefresh.release`, `pullToRefresh.refreshing`). Override them per instance with the `translations` prop:
+
+```vue
 <template>
   <MazPullToRefresh
-    header-class="maz:bg-bg-dark maz:text-foreground-light"
-    class="maz:flex maz:min-h-screen maz:w-full maz:flex-col"
-    :action="pullToRefreshAction"
-    spinner-color="contrast"
-    standalone-mode
-    :disabled="false"
+    :on-refresh="refresh"
+    :translations="{ pull: 'Swipe down', release: 'Release', refreshing: 'Updating…' }"
   >
-    <div>
-      App Content
-    </div>
+    …
+  </MazPullToRefresh>
+</template>
+```
+
+## Accessibility
+
+The gesture is touch only. To give keyboard and mouse users the same action, call the exposed `refresh()` from a button: the indicator and the events behave exactly as with the gesture.
+
+```vue
+<script lang="ts" setup>
+import { useTemplateRef } from 'vue'
+
+const pullToRefresh = useTemplateRef('pullToRefresh')
+</script>
+
+<template>
+  <MazBtn :loading="pullToRefresh?.isRefreshing" @click="pullToRefresh?.refresh()">
+    Refresh
+  </MazBtn>
+
+  <MazPullToRefresh ref="pullToRefresh" :on-refresh="refresh">
+    …
   </MazPullToRefresh>
 </template>
 ```
 
-::: warning
-More documentation to come
-:::
+While refreshing, the root element has `aria-busy="true"` and the refreshing text is announced through a polite live region. The visual indicator is hidden from assistive technologies.
+
+## Events
+
+The events follow the life of a refresh: `start`, then `loaded` and `response` (with the value resolved by `on-refresh`) or `error`, and always `finish`. An error thrown by `on-refresh` is emitted, never thrown again.
+
+## Headless usage
+
+Need a different indicator, or a gesture on an element without wrapping it? Use the [usePullToRefresh](./../composables/use-pull-to-refresh.md) composable.
 
 <!--@include: ./../../.vitepress/generated-docs/maz-pull-to-refresh.doc.md-->