@maz-ui/mcp 5.0.0-beta.3 → 5.0.0-beta.30

package/docs/src/components/maz-input-phone-number.md

@@ -68,34 +68,28 @@ const results = ref<MazInputPhoneNumberData>()
 Control which countries appear in the dropdown and their order.
 
 <ComponentDemo>
-  <div class="maz:space-y-4">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Preferred Countries</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Show your most common countries first</p>
-      <MazInputPhoneNumber
-        v-model="phone1"
-        :preferred-countries="['US', 'FR', 'GB', 'DE', 'CA']"
-        placeholder="Common countries appear first"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Only Specific Countries</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Limit to certain countries only</p>
-      <MazInputPhoneNumber
-        v-model="phone2"
-        :only-countries="['US', 'FR', 'GB', 'DE', 'IT', 'ES']"
-        placeholder="Only European + North American countries"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Ignore Countries</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Remove unwanted countries</p>
-      <MazInputPhoneNumber
-        v-model="phone3"
-        :ignored-countries="['AF', 'AL', 'DZ']"
-        placeholder="Some countries are hidden"
-      />
-    </div>
+  <div class="maz:flex maz:flex-col maz:gap-4">
+    <MazInputPhoneNumber
+      top-label="Preferred Countries"
+      assistive-text="Show your most common countries first"
+      v-model="phone1"
+      :preferred-countries="['US', 'FR', 'GB', 'DE', 'CA']"
+      placeholder="Common countries appear first"
+    />
+    <MazInputPhoneNumber
+      top-label="Only Specific Countries"
+      assistive-text="Limit to certain countries only"
+      v-model="phone2"
+      :only-countries="['US', 'FR', 'GB', 'DE', 'IT', 'ES']"
+      placeholder="Only European + North American countries"
+    />
+    <MazInputPhoneNumber
+      top-label="Ignore Countries"
+      assistive-text="Remove unwanted countries"
+      v-model="phone3"
+      :ignored-countries="['AF', 'AL', 'DZ']"
+      placeholder="Some countries are hidden"
+    />
   </div>
 
 <template #code>
@@ -133,22 +127,22 @@ Control which countries appear in the dropdown and their order.
 Choose how the country selector and phone input are arranged.
 
 <ComponentDemo>
-  <div class="maz:space-y-6">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Responsive (Default)</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Stacks on mobile, side-by-side on desktop</p>
-      <MazInputPhoneNumber orientation="responsive" />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Always Row</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Side-by-side on all screen sizes</p>
-      <MazInputPhoneNumber orientation="row" />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Always Column</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Stacked on all screen sizes</p>
-      <MazInputPhoneNumber orientation="col" />
-    </div>
+  <div class="maz:flex maz:flex-col maz:gap-6">
+    <MazInputPhoneNumber
+      top-label="Responsive"
+      assistive-text="Stacks on mobile, side-by-side on desktop"
+      orientation="responsive"
+    />
+    <MazInputPhoneNumber
+      top-label="Always Row"
+      assistive-text="Side-by-side on all screen sizes"
+      orientation="row"
+    />
+    <MazInputPhoneNumber
+      top-label="Always Column"
+      assistive-text="Stacked on all screen sizes"
+      orientation="col"
+    />
   </div>
 
 <template #code>
@@ -156,13 +150,25 @@ Choose how the country selector and phone input are arranged.
 ```vue
 <template>
   <!-- Responsive layout (default) -->
-  <MazInputPhoneNumber orientation="responsive" />
+  <MazInputPhoneNumber
+    top-label="Responsive"
+    assistive-text="Stacks on mobile, side-by-side on desktop"
+    orientation="responsive"
+  />
 
   <!-- Always side-by-side -->
-  <MazInputPhoneNumber orientation="row" />
+  <MazInputPhoneNumber
+    top-label="Always Row"
+    assistive-text="Side-by-side on all screen sizes"
+    orientation="row"
+  />
 
   <!-- Always stacked -->
-  <MazInputPhoneNumber orientation="col" />
+  <MazInputPhoneNumber
+    top-label="Always Column"
+    assistive-text="Stacked on all screen sizes"
+    orientation="col"
+  />
 </template>
 ```
 
@@ -174,34 +180,30 @@ Choose how the country selector and phone input are arranged.
 Customize what information is shown to users.
 
 <ComponentDemo>
-  <div class="maz:space-y-6">
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Show Country Names</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Display country names instead of calling codes</p>
-      <MazInputPhoneNumber
-        display-country-name
-        :translations="{
-          countrySelect: { placeholder: 'Choose country' }
-        }"
-      />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Show Calling Codes in List</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Help users see the dialing codes</p>
-      <MazInputPhoneNumber show-code-in-list />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Hide Phone Examples</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">
-        Remove the example phone number hints (visible when the phone input is focused)
-      </p>
-      <MazInputPhoneNumber :example="false" />
-    </div>
-    <div>
-      <h4 class="maz:font-semibold maz:mb-2">Hide Country Flags</h4>
-      <p class="maz:text-sm maz:text-muted maz:mb-2">Text-only country selection</p>
-      <MazInputPhoneNumber hide-flags />
-    </div>
+  <div class="maz:flex maz:flex-col maz:gap-4">
+    <MazInputPhoneNumber
+      top-label="Show Country Names"
+      assistive-text="Display country names instead of calling codes"
+      display-country-name
+      :translations="{
+        countrySelect: { placeholder: 'Choose country' }
+      }"
+    />
+    <MazInputPhoneNumber
+      top-label="Show Calling Codes in List"
+      assistive-text="Help users see the dialing codes"
+      show-code-in-list
+    />
+    <MazInputPhoneNumber
+      top-label="Hide Phone Examples"
+      assistive-text="Remove the example phone number hints (visible when the phone input is focused)"
+      :example="false"
+    />
+    <MazInputPhoneNumber
+      top-label="Hide Country Flags"
+      assistive-text="Text-only country selection"
+      hide-flags
+    />
   </div>
 
 <template #code>
@@ -762,34 +764,35 @@ const mobilePhone = ref()
 Understanding what data the component provides.
 
 <ComponentDemo>
-  <div class="maz:space-y-4">
-    <MazInputPhoneNumber
-      v-model="dataPhone"
-      v-model:country-code="dataCountry"
-      label="Enter a phone number to see data"
-      @data="phoneData = $event"
-    />
-    <div v-if="phoneData" class="maz:bg-surface-400 maz:p-4 maz:rounded-md">
-      <h4 class="maz:font-semibold maz:mb-3">📊 Phone Number Data</h4>
-      <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4 maz:text-sm">
-        <div>
-          <strong>Valid:</strong> {{ phoneData?.isValid ? '✅' : '❌' }}
-        </div>
-        <div>
-          <strong>Country:</strong> {{ phoneData?.countryCode || 'None' }}
-        </div>
-        <div>
-          <strong>National Format:</strong> {{ phoneData?.formatNational || 'None' }}
-        </div>
-        <div>
-          <strong>International:</strong> {{ phoneData?.formatInternational || 'None' }}
-        </div>
-        <div>
-          <strong>E164 Format:</strong> {{ phoneData?.e164 || 'None' }}
-        </div>
-        <div>
-          <strong>Phone Type:</strong> {{ phoneData?.type || 'Unknown' }}
-        </div>
+  <MazInputPhoneNumber
+    v-model="dataPhone"
+    v-model:country-code="dataCountry"
+    top-label="Your phone number"
+    placeholder="Enter a phone number to see data"
+    assistive-text="Enter your phone number in international format (e.g. +33612345678)"
+    @data="phoneData = $event"
+  />
+
+  <div v-if="phoneData" class="maz:bg-surface-400 maz:pt-8 maz:rounded-md">
+    <h4 class="maz:font-semibold maz:mb-3">📊 Phone Number Data</h4>
+    <div class="maz:grid maz:grid-cols-1 maz:md:grid-cols-2 maz:gap-4 maz:text-sm">
+      <div>
+        <strong>Valid:</strong> {{ phoneData?.isValid ? '✅' : '❌' }}
+      </div>
+      <div>
+        <strong>Country:</strong> {{ phoneData?.countryCode || 'None' }}
+      </div>
+      <div>
+        <strong>National Format:</strong> {{ phoneData?.formatNational || 'None' }}
+      </div>
+      <div>
+        <strong>International:</strong> {{ phoneData?.formatInternational || 'None' }}
+      </div>
+      <div>
+        <strong>E164 Format:</strong> {{ phoneData?.e164 || 'None' }}
+      </div>
+      <div>
+        <strong>Phone Type:</strong> {{ phoneData?.type || 'Unknown' }}
       </div>
     </div>
   </div>

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-->