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

package/docs/src/components/maz-code-highlight.md

@@ -0,0 +1,233 @@
+---
+title: MazCodeHighlight
+description: MazCodeHighlight displays source code with syntax highlighting powered by shiki. It auto-detects dark/light mode, ships with a copy-to-clipboard button, a language badge, and supports lazy loading.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+
+## Installation requirement
+
+Install [`shiki`](https://shiki.style) in your project to enable highlighting:
+
+::: code-group
+
+```bash [pnpm]
+pnpm add shiki
+```
+
+```bash [npm]
+npm install shiki
+```
+
+```bash [yarn]
+yarn add shiki
+```
+
+:::
+
+If `shiki` is not installed, the component falls back to a plain `<pre><code>` block.
+
+## Basic usage
+
+<ComponentDemo>
+  <MazCodeHighlight code="const greeting = 'Hello, maz-ui!'" language="ts" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight code="const greeting = 'Hello, maz-ui!'" language="ts" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## With slot
+
+The default slot text is used as source code when the `code` prop is not provided. This is useful for plain text blocks.
+
+<ComponentDemo>
+  <MazCodeHighlight language="bash">npm install maz-ui</MazCodeHighlight>
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight language="bash">npm install maz-ui</MazCodeHighlight>
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Languages
+
+Pass any valid [shiki language identifier](https://shiki.style/languages) to the `language` prop. The chosen language is also displayed as a small badge in the top-right corner (the badge fades out on hover when the copy button appears).
+
+<ComponentDemo>
+  <MazCodeHighlight language="vue" :code="vueExample" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight language="vue" :code="vueExample" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+
+  const vueExample = `<script lang="ts" setup>
+  import { ref } from 'vue'
+  const count = ref(0)
+<\/script>
+
+<template>
+  <button @click="count++">Count: {{ count }}</button>
+</template>`
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Custom theme
+
+Override the auto-detected theme with any [shiki built-in theme](https://shiki.style/themes).
+
+<ComponentDemo>
+  <MazCodeHighlight code="console.log('dracula theme')" language="js" theme="dracula" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight code="console.log('dracula theme')" language="js" theme="dracula" />
+</template>
+
+<script lang="ts" setup>
+  import MazCodeHighlight from 'maz-ui/components/MazCodeHighlight'
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
+## Copy to clipboard
+
+A copy button is displayed in the top-right corner on hover (or when focused via keyboard). Clicking it writes the resolved code to the clipboard and shows a check icon for ~1.5s.
+
+### Disable the copy button
+
+Set `:copyable="false"` to hide the button entirely.
+
+<ComponentDemo>
+  <MazCodeHighlight code="const noCopyButton = true" language="ts" :copyable="false" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight code="const noCopyButton = true" language="ts" :copyable="false" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### Copy a different value than the displayed code
+
+Use `copyValue` when the displayed source differs from what should be copied — for example to strip a leading `$` prompt when rendering a shell command. This is the mechanism `MazWindowMockup` uses internally to keep the terminal prompt out of the clipboard.
+
+<ComponentDemo>
+  <MazCodeHighlight code="$ pnpm add maz-ui" copy-value="pnpm add maz-ui" language="bash" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight
+    code="$ pnpm add maz-ui"
+    copy-value="pnpm add maz-ui"
+    language="bash"
+  />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Disable rounded corners
+
+Set `:rounded="false"` to render the highlighted block with squared corners — useful when embedding inside another container that already has its own border-radius (e.g. inside `MazWindowMockup`).
+
+<ComponentDemo>
+  <MazCodeHighlight code="// squared corners" language="ts" :rounded="false" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight code="// squared corners" language="ts" :rounded="false" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+## Custom translations
+
+The copy button's aria-label and tooltip come from the `@maz-ui/translations` package (`codeHighlight.copyToClipboard` / `codeHighlight.copiedToClipboard`). You can override either key per-instance with the `translations` prop without touching the global locale:
+
+<ComponentDemo>
+  <MazCodeHighlight
+    code="const hello = 'world'"
+    language="ts"
+    :translations="{ copyToClipboard: 'Copier le code', copiedToClipboard: 'Copié !' }"
+  />
+
+  <template #code>
+
+```vue
+<template>
+  <MazCodeHighlight
+    code="const hello = 'world'"
+    language="ts"
+    :translations="{
+      copyToClipboard: 'Copier le code',
+      copiedToClipboard: 'Copié !',
+    }"
+  />
+</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>
+  const vueExample = `<script lang="ts" setup>
+  import { ref } from 'vue'
+  const count = ref(0)
+<\/script>
+
+<template>
+  <button @click="count++">Count: {{ count }}</button>
+</template>`
+</script>
+
+<!--@include: ./../../.vitepress/generated-docs/maz-code-highlight.doc.md-->

package/docs/src/components/maz-date-picker.md

@@ -16,6 +16,7 @@ description: A powerful and flexible date picker component with support for sing
 - [Basic Usage](#basic-usage)
 - [Date Formats](#date-formats)
 - [Date Selection](#date-selection)
+- [Custom Trigger](#custom-trigger)
 - [Time Selection](#time-selection)
 - [Range Selection](#range-selection)
 - [Internationalization](#internationalization)
@@ -273,6 +274,58 @@ const date = ref()
   </template>
 </ComponentDemo>
 
+## Custom Trigger
+
+By default MazDatePicker renders a readonly `MazInput` as the field that opens the calendar. Use the `#trigger` slot to replace it with your own element - a button, a custom input, an icon... Clicking the slotted element opens the calendar automatically (no `@click` needed), and the slot exposes the current open state plus functions for programmatic control.
+
+### Slot bindings
+
+| Binding | Type | Description |
+| --- | --- | --- |
+| `is-open` | `boolean` | Whether the calendar is currently open |
+| `open` | `() => void` | Open the calendar programmatically |
+| `close` | `() => void` | Close the calendar programmatically |
+| `toggle` | `() => void` | Toggle the calendar programmatically |
+
+<ComponentDemo>
+  <MazDatePicker v-model="triggerDate" auto-close hide-header>
+    <template #trigger="{ isOpen }">
+      <MazBtn color="secondary" :class="{ 'maz:ring-2 maz:ring-offset-2 maz:ring-secondary': isOpen }">
+        {{ triggerDate || 'Pick a date' }}
+      </MazBtn>
+    </template>
+  </MazDatePicker>
+
+<template #code>
+
+```vue
+<template>
+  <MazDatePicker v-model="date" auto-close>
+    <!-- Clicking the button opens the picker automatically. -->
+    <template #trigger="{ isOpen }">
+      <MazBtn color="secondary" :class="{ 'maz:ring-2 maz:ring-secondary': isOpen }">
+        {{ date || 'Pick a date' }}
+      </MazBtn>
+    </template>
+  </MazDatePicker>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const date = ref()
+</script>
+```
+
+</template>
+</ComponentDemo>
+
+::: tip
+The model value is not passed through the slot - use your own `v-model` ref (here `date`) to display the selected value in your custom trigger. The exposed `open` / `close` / `toggle` functions are only needed when you want to drive the picker from your own logic.
+:::
+
+> In `inline` mode the calendar is always visible, so the `trigger` slot is not rendered. To open the picker from an element rendered outside the component, use the `custom-element-selector` prop instead.
+
 ## Time Selection
 
 ### Date + Time (24h format)
@@ -896,7 +949,7 @@ const disabledHours = [0, 1, 2, 11, 22, 23]
 
 ## Internationalization
 
-MazDatePicker supports full internationalization. **By default, it uses the locale from the [MazUiTranslations](../guide/translations.md) plugin**, but you can override it:
+MazDatePicker supports full internationalization. **By default, it uses the locale from the [MazUiTranslations](../ecosystem/translations.md) plugin**, but you can override it:
 
 <ComponentDemo>
   <div class="maz:grid maz:grid-cols-1 maz:mob-l:grid-cols-2 maz:gap-4">
@@ -1021,6 +1074,7 @@ const formatExample2 = ref('03/15/2024')
 const formatExample3 = ref('15-03-2024')
 const transformedDate = ref()
 const newDateValue = ref()
+const triggerDate = ref()
 // Date selection
 const dateSelection = ref()
 const inlineDate = ref()

package/docs/src/components/maz-dialog.md

@@ -103,10 +103,56 @@ For long content, you can enable scrolling in content part (Header and footer sl
   </template>
 </ComponentDemo>
 
+## Width
+
+On tablet and up, the dialog is sized by two CSS variables coming from the active theme preset (`components.dialog`):
+
+- `--maz-dialog-max-width` (default `38rem`)
+- `--maz-dialog-min-width` (default `32rem`)
+
+You can set these defaults globally per preset — see [the theme `components.dialog` documentation](./../ecosystem/themes.md#dialog-sizing). To change the width of a single dialog, pass the `max-width` / `min-width` props — they always override the preset:
+
+<ComponentDemo>
+  <MazBtn @click="widthOpened = true">Open Wide Dialog</MazBtn>
+
+  <MazDialog v-model="widthOpened" title="Custom width" max-width="50rem" min-width="40rem">
+    <p>
+      This dialog overrides the preset width through props.
+    </p>
+    <template #footer="{ close }">
+      <MazBtn @click="close">
+        Confirm
+      </MazBtn>
+    </template>
+  </MazDialog>
+
+<template #code>
+
+```vue
+<template>
+  <MazDialog
+    v-model="isOpen"
+    title="Custom width"
+    max-width="50rem"
+    min-width="40rem"
+  >
+    <p>This dialog overrides the preset width through props.</p>
+  </MazDialog>
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+::: tip
+The default widths are expressed in `rem`, so they scale with the preset's `base-font-size`. Presets with a larger base size (e.g. `ocean` at `16px`) ship rem values adjusted to keep the rendered pixel width consistent across presets.
+:::
+
 <!--@include: ./../../.vitepress/generated-docs/maz-dialog.doc.md-->
 
 <script setup>
   import { ref } from 'vue'
   const isOpen = ref(false)
   const scollableOpened = ref(false)
+  const widthOpened = ref(false)
 </script>

package/docs/src/components/maz-dropdown.md

@@ -16,10 +16,12 @@ description: MazDropdown is a standalone dropdown menu component and versatile d
 <ComponentDemo>
   <MazDropdown
     :items="[
+      { label: 'Louis Mazel', textColor: 'muted' },
       { label: 'Action', onClick: () => toast.success('CLICKED') },
       { label: 'Link (href)', href: 'https://www.google.com', target: '_blank', color: 'secondary' },
       { label: 'Router Link', to: { name: 'index' }, color: 'destructive' },
     ]"
+    items-size="sm"
   >
     Dropdown Menu
   </MazDropdown>
@@ -82,6 +84,7 @@ This provides the best user experience across all devices without requiring manu
 ## Open dropdown only on click
 
 <MazDropdown
+  :model-value="true"
   :items="[
     { label: 'Action', onClick: () => toast.success('CLICKED') },
     { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
@@ -220,8 +223,9 @@ You can provide an icon to replace the default chevron icon and disable the anim
   fab
   pastel
   :chevron="false"
-  icon="/bars-3.svg"
+  :icon="MazBars3"
   size="xl"
+  items-size="sm"
   :items="[
     { label: 'Action', onClick: () => toast.success('CLICKED') },
     { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
@@ -230,23 +234,34 @@ You can provide an icon to replace the default chevron icon and disable the anim
   :close-on-click="false"
 />
 
-```html{2-7}
-<MazDropdown
-  color="primary"
-  fab
-  pastel
-  :chevron="false"
-  icon="/bars-3.svg"
-  size="xl"
-  :items="[
-    { label: 'Action', onClick: () => toast.success('CLICKED') },
-    { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
-    { label: 'Router Link', to: { name: 'index' } },
-  ]"
-  :close-on-click="false"
-/>
+::: details View code
+
+```vue{7-13}
+<script lang="ts" setup>
+  import { MazBars3 } from '@maz-ui/icons/raw/MazBars3'
+</script>
+
+<template>
+  <MazDropdown
+    color="primary"
+    fab
+    pastel
+    :chevron="false"
+    :icon="MazBars3"
+    items-size="sm"
+    size="xl"
+    :items="[
+      { label: 'Action', onClick: () => toast.success('CLICKED') },
+      { label: 'Link (href)', href: 'https://www.google.com', target: '_blank' },
+      { label: 'Router Link', to: { name: 'index' } },
+    ]"
+    :close-on-click="false"
+  />
+</template>
 ```
 
+:::
+
 ## Custom slots
 
 ### Custom dropdown panel
@@ -654,6 +669,7 @@ type MazDropdownMenuItem = {
   import { ref, onMounted } from 'vue'
   import { useToast } from 'maz-ui/composables/useToast'
   import { MazChevronUpDown } from '@maz-ui/icons/raw/MazChevronUpDown'
+  import { MazBars3 } from '@maz-ui/icons/raw/MazBars3'
 
   const toast = useToast()
 

package/docs/src/components/maz-icon.md

@@ -8,7 +8,7 @@ description: A flexible icon component that accepts Vue components, raw SVG stri
 {{ $frontmatter.description }}
 
 ::: tip
-Download the bundled [icons pack](#all-bundled-icons) or use [`@maz-ui/icons`](../guide/icons.md) for the full set.
+Download the bundled [icons pack](#all-bundled-icons) or use [`@maz-ui/icons`](../ecosystem/icons/.md) for the full set.
 :::
 
 ## How it works
@@ -177,15 +177,26 @@ Inject extra attributes onto the rendered `<svg>` (or onto the inlined raw SVG)
 <MazIcon :icon="MazStar" :svg-attributes="{ 'data-testid': 'star', fill: 'currentColor' }" />
 ```
 
-## SSR — base URL for relative URLs
+## SSR
 
-When you render `MazIcon icon="/icons/star.svg"` on the server, `fetch('/icons/star.svg')` cannot resolve without a host. Provide a base URL via Vue's `provide` to fix this:
+Components, raw SVG strings and SVG `data:` URIs (e.g. a small `?url` import inlined by Vite) are always part of the server HTML, without any request.
+
+The server never waits for the network to render a URL icon:
+
+- once the server has the SVG in its cache, it inlines it;
+- otherwise, it renders an empty placeholder reserving the icon box and fetches the SVG in the background for the next renders. The client loads the icon in the placeholder.
+
+A relative URL (`/icons/star.svg`, from your `public/` directory) can only be fetched by the server with an absolute base URL, see below.
+
+## Base URL for relative URLs
+
+Prefix every relative URL icon by providing a base URL via Vue's `provide`. An absolute base also lets the server fetch them:
 
 ```ts
 import { createApp } from 'vue'
 
 const app = createApp(App)
-app.provide('mazIconPath', 'https://your-app.com')
+app.provide('mazIconPath', 'https://cdn.your-app.com')
 ```
 
 In Nuxt, set `mazUi.general.defaultMazIconPath` in `nuxt.config` and `@maz-ui/nuxt` wires the provide for you.
@@ -220,7 +231,7 @@ This pack is the Heroicons set plus a few additions specific to maz-ui.
   Download pack
 </MazBtn>
 
-Source: [Heroicons](https://heroicons.com/) — see also the [icon set page](./../guide/icon-set.md).
+Source: [Heroicons](https://heroicons.com/) — see also the [icon set page](./../ecosystem/icons/icon-set.md).
 
 <div class="flex items-start flex-wrap gap-05">
   <div v-for="({ component, name }, i) in iconsList" :key="i" class="flex flex-col flex-center maz:p-2 maz:rounded-md maz:border">

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

@@ -204,6 +204,11 @@ Customize what information is shown to users.
       assistive-text="Text-only country selection"
       hide-flags
     />
+    <MazInputPhoneNumber
+      top-label="Flags of maz-ui"
+      assistive-text="No request to flagcdn.com, works offline"
+      :flag-src="loadCountryFlag"
+    />
   </div>
 
 <template #code>
@@ -224,12 +229,36 @@ Customize what information is shown to users.
 
   <!-- Hide country flags -->
   <MazInputPhoneNumber hide-flags />
+
+  <!-- Flags of maz-ui, no request to flagcdn.com: import { loadCountryFlag } from 'maz-ui/country-flags' -->
+  <MazInputPhoneNumber :flag-src="loadCountryFlag" />
+
+  <!-- Your own files: public/flags/fr.svg... -->
+  <MazInputPhoneNumber flag-src="/flags/{code}.svg" />
 </template>
 ```
 
 </template>
 </ComponentDemo>
 
+### Flags source
+
+By default, the flags come from the [flagcdn.com](https://flagcdn.com) CDN. The `flag-src` prop, passed to the country selector, takes:
+
+- `loadCountryFlag` from `maz-ui/country-flags`: the flags of `@maz-ui/icons`, without any request to a third party, offline (hybrid apps with Capacitor or Cordova, PWAs);
+- a URL template of your own files: `'/flags/{code}.svg'` (`{CODE}` for uppercase codes);
+- your own function: `(code) => string | undefined | Promise<string | undefined>`.
+
+Each flag is loaded only when visible, and a code without flag displays a badge. Set it once for the whole app with `defaults.global.flagSrc` of the MazUi plugin, or `mazUi.flags` of the Nuxt module (`'local'` or a URL template):
+
+```ts
+import { loadCountryFlag } from 'maz-ui/country-flags'
+
+app.use(MazUi, { theme: { preset: mazUi }, defaults: { global: { flagSrc: loadCountryFlag } } })
+```
+
+See [MazSelectCountry](./maz-select-country.md#flags-source) for the details (bundle, Content Security Policy, PWA precache).
+
 ## Smart Country Detection
 
 Let the component automatically detect the user's country.
@@ -886,6 +915,7 @@ interface MazInputPhoneNumberData {
 <!--@include: ./../../.vitepress/generated-docs/maz-input-phone-number.doc.md-->
 
 <script setup lang="ts">
+  import { loadCountryFlag } from 'maz-ui/country-flags'
   import { ref } from 'vue'
 
   // Basic usage

package/docs/src/components/maz-lazy-img.md

@@ -21,4 +21,68 @@ import MazLazyImg from 'maz-ui/components/MazLazyImg'
 </template>
 ```
 
+::: tip Performance
+`MazLazyImg` relies on the [`vLazyImg`](./../directives/lazy-img.md) directive, whose `IntersectionObserver`s are pooled and shared across every instance - rendering many images (galleries, lists, avatars) stays cheap.
+:::
+
+## Responsive sources
+
+Pass an object with `sources` to serve different images depending on the media query (like a native `<picture>`).
+
+```vue
+<template>
+  <MazLazyImg
+    :src="{
+      sources: [
+        { srcset: 'https://placedog.net/600/400', media: '(max-width: 600px)' },
+        { srcset: 'https://placedog.net/1500/1000', media: '(min-width: 601px)' },
+      ],
+    }"
+    block
+  />
+</template>
+```
+
+## Image height full
+
+By default the image is displayed with `width: 100%`. Enable `image-height-full` to fill the **height** instead: the image keeps its aspect ratio, fills 100% of the height and overflows/crops horizontally. Handy for wide images or SVGs inside a fixed-height container.
+
+```vue
+<template>
+  <div style="height: 200px;">
+    <MazLazyImg image-height-full src="https://placedog.net/1500/1000" />
+  </div>
+</template>
+```
+
+## Fallback on error
+
+Provide `fallback-src` to swap the image when it fails to load.
+
+<MazLazyImg
+  block
+  src="https://broken-link-image-src.example"
+  fallback-src="https://placedog.net/500/500?id=42"
+/>
+
+```vue
+<template>
+  <MazLazyImg
+    src="https://broken-link-image-src.example"
+    fallback-src="https://placedog.net/500/500"
+    block
+  />
+</template>
+```
+
+## Without loader
+
+Hide the spinner shown while the image is loading with `hide-loader`.
+
+```vue
+<template>
+  <MazLazyImg src="https://placedog.net/1000/1000" hide-loader block />
+</template>
+```
+
 <!--@include: ./../../.vitepress/generated-docs/maz-lazy-img.doc.md-->