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

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

@@ -68,6 +68,32 @@ You can use the `top-label` attribute to display a top label above the textarea.
   </template>
 </ComponentDemo>
 
+## With assistive text
+
+You can use the `assistive-text` attribute to display a assistive text below the textarea.
+
+<ComponentDemo>
+  <MazTextarea
+    v-model="value"
+    top-label="Your message"
+    placeholder="Type your message..."
+    assistive-text="This is an assistive text"
+  />
+
+<template #code>
+
+```html
+<MazTextarea
+  v-model="value"
+  top-label="Your message"
+  placeholder="Type your message..."
+  assistive-text="This is an assistive text"
+/>
+```
+
+  </template>
+</ComponentDemo>
+
 ## With label and append slots
 
 You can use the `label` and `append` slots to customize the label and the append element.
@@ -84,7 +110,7 @@ You can use the `label` and `append` slots to customize the label and the append
       </span>
     </template>
     <template #append>
-      <MazBtn icon="paper-airplane" size="sm" @click="sendMessage" />
+      <MazBtn icon="/paper-airplane.svg" size="sm" @click="sendMessage" />
     </template>
   </MazTextarea>
 

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

@@ -9,6 +9,21 @@ description: MazTimeline is a step/progress timeline component for Vue 3 with su
 
 <!--@include: ./../../.vitepress/mixins/getting-started.md-->
 
+---
+
+Control the current step:
+
+<MazRadioButtons
+  :model-value="currentStep"
+  size="sm"
+  :options="[
+    { label: 'None', value: -1 },
+    ...steps.map((step, index) => ({ label: index, value: index })),
+    { label: 'All Completed', value: 99 },
+  ]"
+  @update:model-value="currentStep = $event"
+/>
+
 ## Basic usage
 
 <ComponentDemo>
@@ -292,6 +307,40 @@ Customize the indicator border radius with the `rounded-size` prop.
   </template>
 </ComponentDemo>
 
+## Custom Icons
+
+<ComponentDemo>
+  <MazTimeline :model-value="0" :steps="iconsSteps" direction="horizontal" size="lg" />
+
+  <template #code>
+
+```vue
+<template>
+  <MazTimeline
+    v-model="currentStep"
+    :steps="steps"
+    size="lg"
+  />
+</template>
+
+<script lang="ts" setup>
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+</script>
+```
+
+  </template>
+</ComponentDemo>
+
 ## Custom slots
 
 MazTimeline provides scoped slots for full customization.
@@ -378,6 +427,10 @@ MazTimeline provides scoped slots for full customization.
 
 <script lang="ts" setup>
   import { ref } from 'vue'
+  import { MazComputerDesktop } from '@maz-ui/icons/MazComputerDesktop'
+  import { MazCommandLine } from '@maz-ui/icons/MazCommandLine'
+  import { MazClipboardDocumentList } from '@maz-ui/icons/MazClipboardDocumentList'
+  import { MazClipboardDocumentCheck } from '@maz-ui/icons/MazClipboardDocumentCheck'
 
   const currentStep = ref(1)
   const clickableStep = ref(0)
@@ -410,6 +463,13 @@ MazTimeline provides scoped slots for full customization.
     { title: 'Complete', subtitle: 'All done!' },
   ]
 
+  const iconsSteps = [
+    { title: 'PO', subtitle: 'Writing PRD', icon: MazClipboardDocumentList },
+    { title: 'Dev', subtitle: 'Building Code', icon: MazCommandLine },
+    { title: 'Tech Lead', subtitle: 'Review Code', icon: MazComputerDesktop },
+    { title: 'QA', subtitle: 'Testing', icon: MazClipboardDocumentCheck },
+  ]
+
   const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructive']
   const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
   const roundedSizes = ['full', 'lg', 'md', 'sm', 'none']

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-form-validator.md

@@ -151,7 +151,7 @@ Each field in `fieldsStates` contains:
         v-model="stateModel.age"
         label="Age (18-100)"
         type="number"
-        :hint="stateErrors.age"s
+        :hint="stateErrors.age"
         :error="!!stateErrors.age"
         :success="stateFields.age.valid"
       />
@@ -365,7 +365,7 @@ Requires `useFormField` with `ref` option or `validationEvents`.
       :success="eagerEmailValid"
       :class="{ 'has-error-eager': eagerEmailHasError }"
     />
-    <MazBtn type="submit" :loading="eagerSubmitting">Submit</MazBtn>
+    <MazBtn type="submit" :loading="eagerSubmitting" :disabled="!eagerIsValid">Submit</MazBtn>
   </form>
 
   <template #code>
@@ -381,7 +381,7 @@ const schema = {
   email: pipe(string(), nonEmpty('Required'), email('Invalid email')),
 }
 
-const { isSubmitting, handleSubmit } = useFormValidator({
+const { isSubmitting, handleSubmit, isValid } = useFormValidator({
   schema,
   options: {
     mode: 'eager',
@@ -430,6 +430,8 @@ const {
       :error="emailHasError"
       :success="emailValid"
     />
+
+    <MazBtn type="submit" :loading="isSubmitting" :disabled="!isValid">Submit</MazBtn>
   </form>
 </template>
 ```
@@ -614,6 +616,8 @@ const { value: name, hasError, errorMessage, isValid } = useFormField<string>('n
 
 Pass a template ref to `useFormField`. It will automatically detect interactive elements and attach blur listeners.
 
+The `ref` option is **reactive**: if the field is rendered conditionally (e.g. with `v-if`), the blur listeners are attached automatically as soon as the element appears in the DOM, and removed when it is unmounted. You don't need to handle anything special.
+
 ```vue
 <script setup>
 import { useFormField } from 'maz-ui/composables'
@@ -635,6 +639,41 @@ const { value, errorMessage, hasError } = useFormField<string>('email', {
 </template>
 ```
 
+Because it is reactive, the same code works even when the input is wrapped in a `v-if`:
+
+```vue
+<script setup>
+import { useFormField } from 'maz-ui/composables'
+import { useTemplateRef, ref } from 'vue'
+
+const isVisible = ref(false)
+
+const { value, errorMessage, hasError } = useFormField<string>('email', {
+  ref: useTemplateRef('emailRef'),
+  formIdentifier: 'my-form',
+})
+</script>
+
+<template>
+  <MazInput
+    v-if="isVisible"
+    ref="emailRef"
+    v-model="value"
+    :hint="errorMessage"
+    :error="hasError"
+  />
+</template>
+```
+
+You can also pass a raw `HTMLElement` directly. In that case it won't be reactive, so the element must already exist in the DOM:
+
+```ts
+const { value } = useFormField<string>('email', {
+  ref: document.querySelector('input'),
+  formIdentifier: 'my-form',
+})
+```
+
 #### Option 2: Using `validationEvents`
 
 If your component emits a `blur` event, you can use `v-bind` with `validationEvents`.
@@ -1074,7 +1113,7 @@ useFormField<FieldType>(
   options?: {
     defaultValue?: FieldType,                         // Default value for this field
     mode?: 'lazy' | 'aggressive' | 'eager' | 'blur' | 'progressive', // Override form mode
-    ref?: Ref<HTMLElement | ComponentInstance>,       // Template ref for blur detection
+    ref?: Ref<HTMLElement | ComponentInstance> | HTMLElement, // Reactive template ref (v-if friendly) or raw element
     formIdentifier?: string | symbol,                 // Must match useFormValidator's identifier
   }
 )
@@ -1113,7 +1152,7 @@ interface FormValidatorOptions<Model> {
 interface FormFieldOptions<FieldType> {
   defaultValue?: FieldType
   mode?: 'eager' | 'lazy' | 'aggressive' | 'blur' | 'progressive'
-  ref?: Ref<HTMLElement | ComponentInstance>
+  ref?: Ref<HTMLElement | ComponentInstance> | HTMLElement
   formIdentifier?: string | symbol
 }
 
@@ -1166,14 +1205,13 @@ const { value, validationEvents } = useFormField<string>('name')
 // Then: v-bind="validationEvents" on your input
 ```
 
-### Element Not Found Warning
+### Conditionally Rendered Fields (`v-if`)
 
-**Problem**: `No element found for ref in field 'name'`
+The `ref` option is reactive, so a field wrapped in `v-if` works out of the box: blur listeners are attached as soon as the element is rendered and removed when it is unmounted.
 
-**Solutions**:
-1. Ensure the ref is bound to an HTML element or Vue component
-2. Make sure the component has a `$el` property
-3. For custom components, add `data-interactive` attribute
+If blur validation still doesn't trigger:
+1. Ensure the `ref` is bound to an HTML element or a Vue component exposing `$el`
+2. For custom components, add the `data-interactive` attribute
 
 ### Mismatched Form Identifiers
 
@@ -1310,6 +1348,7 @@ const eagerSchema = {
 const {
   isSubmitting: eagerSubmitting,
   handleSubmit: handleEager,
+  isValid: eagerIsValid,
 } = useFormValidator({
   schema: eagerSchema,
   options: { mode: 'eager', scrollToError: '.has-error-eager', identifier: 'form-eager' },

package/docs/src/directives/click-outside.md

@@ -11,8 +11,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -21,8 +20,7 @@ description: vClickOutside is a Vue directive to trigger a function when the use
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -44,8 +42,7 @@ function clikedOutside() {
 
 <template>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="clikedOutside">
       Click outside me
@@ -54,8 +51,7 @@ function clikedOutside() {
 
   <div
     v-if="hasClikedOutside"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-success); color: black;"
-    class="flex flex-center rounded"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside
   </div>
@@ -71,8 +67,7 @@ The directive can accept an options object to customize its behavior:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOutsideWithIgnore, ignore: ['.ignore-me'] }">
       <div class="maz:p-4">
@@ -86,8 +81,7 @@ The directive can accept an options object to customize its behavior:
 
   <div
     v-if="hasClickedOutsideWithIgnore"
-    style="padding: 16px; margin-top: 16px; background-color: var(--maz-warning); color: black;"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:bg-sucess maz:text-success-foreground maz:p-4 maz:mt-4"
   >
     You clicked outside (button clicks are ignored)
   </div>
@@ -128,8 +122,7 @@ The directive can be configured to trigger only once:
 
 <ComponentDemo>
   <div
-    style="padding: 50px; background-color: var(--maz-surface-300);"
-    class="maz:flex maz:flex-center maz:rounded-md"
+    class="maz:flex maz:flex-center maz:rounded-md maz:p-12 maz:bg-surface-300"
   >
     <MazCard v-click-outside="{ callback: clickedOnce, once: true }">
       Click outside me (works only once)
@@ -249,7 +242,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 <script lang="ts" setup>
   import { ref } from 'vue'

package/docs/src/directives/fullscreen-img.md

@@ -83,7 +83,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 ## Types
 

package/docs/src/directives/lazy-img.md

@@ -10,7 +10,7 @@ description: vLazyImg is a Vue directive to lazy load images with many options.
 ## Basic usage
 
 <img
-  style="background-color: var(--maz-surface-300); width: 80%;"
+  style="background-color: var(--maz-color-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="'https://placedog.net/1500/1000'"
 />
@@ -23,7 +23,7 @@ import { vLazyImg } from 'maz-ui/directives'
 <template>
   <img
     v-lazy-img="'https://placedog.net/1500/1000'"
-    style="background-color: var(--maz-surface-300); width: 80%;"
+    style="background-color: var(--maz-color-surface-300); width: 80%;"
     class="flex flex-center rounded"
   >
 </template>
@@ -54,7 +54,7 @@ import { vLazyImg } from 'maz-ui/directives'
 > Open the developer console to show logs
 
 <img
-  style="background-color: var(--maz-surface-300); width: 80%;"
+  style="background-color: var(--maz-color-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="lazyBinding"
 />
@@ -83,7 +83,7 @@ const lazyBinding: vLazyImgBindingValue = {
 <template>
   <img
     v-lazy-img="lazyBinding"
-    style="background-color: var(--maz-surface-300); width: 80%;"
+    style="background-color: var(--maz-color-surface-300); width: 80%;"
     class="flex flex-center rounded"
   >
 </template>
@@ -129,7 +129,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 ## Types
 

package/docs/src/directives/tooltip.md

@@ -400,6 +400,29 @@ The `offset` (in px) option allows you to adjust the position of the tooltip rel
   </template>
 </ComponentDemo>
 
+## Conditionally disable
+
+Pass `false`, `null` or `undefined` as the binding value to silently disable the tooltip — no popover instance is created, no listeners are attached, and no warning is logged. This is the recommended way to skip the tooltip on the fly without conditionally rendering two different elements:
+
+```vue
+<script lang="ts" setup>
+import { vTooltip } from 'maz-ui/directives'
+import { computed, ref } from 'vue'
+
+const label = ref<string>('')
+const tooltipBinding = computed(() => label.value ? { text: label.value } : false)
+</script>
+
+<template>
+  <!-- When label is empty the directive becomes a no-op -->
+  <MazBtn v-tooltip="tooltipBinding">
+    Hover me
+  </MazBtn>
+</template>
+```
+
+If the binding switches back to a valid value later, the tooltip mounts as expected. Toggling the value off again destroys the existing popover instance.
+
 ## Global install
 
 ### Vue
@@ -421,7 +444,7 @@ app.mount('#app')
 
 ### Nuxt
 
-Please refer to the [Nuxt module documentation](./../guide/nuxt.md) for more information.
+Please refer to the [Nuxt module documentation](./../ecosystem/nuxt.md) for more information.
 
 ## Types