@maz-ui/mcp 5.0.0 → 5.1.0-beta.0

package/docs/components/maz-input-tags.md

@@ -0,0 +1,112 @@
+---
+title: "MazInputTags"
+description: "MazInputTags is a standalone component like free inputs to help user select many values and return an Array of strings. Color options are also available."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-input-tags"
+---
+
+# MazInputTags
+
+> MazInputTags is a standalone component like free inputs to help user select many values and return an Array of strings. Color options are also available.
+
+- Package: `maz-ui`
+- Import: `import MazInputTags from 'maz-ui/components/MazInputTags'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-input-tags
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+## Basic usage
+
+**Returned value**
+
+```vue
+<script lang="ts" setup>
+import MazInputTags from 'maz-ui/components/MazInputTags'
+import { ref } from 'vue'
+
+const tags = ref(['tags 1', 'tags 2'])
+const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <MazInputTags
+    v-model="tags"
+    label="Enter tags"
+    color="info"
+  />
+</template>
+```
+
+## Sizing
+
+```vue
+<script lang="ts" setup>
+import MazInputTags from 'maz-ui/components/MazInputTags'
+import { ref } from 'vue'
+
+const tags = ref(['tags 1', 'tags 2'])
+const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <div class="flex flex-col gap-2">
+    <MazInputTags
+      v-for="size in sizes"
+      :key="size"
+      v-model="tags"
+      :size="size"
+      placeholder="Enter tags"
+      color="secondary"
+    />
+  </div>
+</template>
+```
+
+```vue
+<script lang="ts" setup>
+import MazInputTags from 'maz-ui/components/MazInputTags'
+import { ref } from 'vue'
+
+const tags = ref(['tags 1', 'tags 2'])
+const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
+</script>
+
+<template>
+  <MazInputTags
+    v-model="tags"
+    label="Enter tags"
+    color="info"
+  />
+
+  <MazInputTags
+    v-model="tags"
+    placeholder="Enter tags"
+    color="secondary"
+    size="sm"
+  />
+</template>
+```
+
+## MazInputTags API
+
+`import MazInputTags from 'maz-ui/components/MazInputTags'`
+
+### Props
+
+- `model-value` (`(string | number)[]`, `v-model`): The modelValue of the input.
+- `placeholder` (`string`): The placeholder of the input.
+- `label` (`string`): The label of the input.
+- `disabled` (`boolean`, default: `false`): Disable the input.
+- `error` (`boolean`, default: `false`): Display the input with error style.
+- `success` (`boolean`, default: `false`): Display the input with success style.
+- `warning` (`boolean`, default: `false`): Display the input with warning style.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): The size of the input.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): The color of the input.
+- `block` (`boolean`): The input will be displayed in full width.
+- `add-tags-on-blur` (`boolean`, default: `true`): Add tags on blur.
+- `hint` (`string`): The hint text to display below the input.
+
+### Events
+
+- `@update:model-value` (payload: `value?: (string | number)[] | undefined`)

package/docs/{src/components → components}/maz-input.md

@@ -1,20 +1,22 @@
 ---
-title: MazInput
-description: MazInput is a standalone component that replaces the standard html input text with a beautiful design system. Many options like colors, sizes, disabled, loading, error, warning, valid states, error messages and icons are included.
+title: "MazInput"
+description: "MazInput is a standalone component that replaces the standard html input text with a beautiful design system. Many options like colors, sizes, disabled, loading, error, warning, valid states, error messages and icons are included."
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-input"
 ---
 
-# {{ $frontmatter.title }}
+# MazInput
 
-{{ $frontmatter.description }}
+> MazInput is a standalone component that replaces the standard html input text with a beautiful design system. Many options like colors, sizes, disabled, loading, error, warning, valid states, error messages and icons are included.
 
-<!--@include: ./../../.vitepress/mixins/getting-started.md-->
+- Package: `maz-ui`
+- Import: `import MazInput from 'maz-ui/components/MazInput'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-input
 
-## Basic usage
-
-<ComponentDemo>
-  <MazInput v-model="inputValue" label="Label" name="firstname" />
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
 
-<template #code>
+## Basic usage
 
 ```vue
 <script setup>
@@ -33,127 +35,55 @@ const inputValue = ref()
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Top label
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" top-label="Top label" placeholder="Placeholder" autocomplete="off" />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" top-label="Top label" placeholder="Placeholder" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Assistive text
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" top-label="Top label" assistive-text="Assistive text" placeholder="Placeholder" />
-  <br />
-  <br />
-  <MazInput v-model="inputValue" error top-label="Top label" assistive-text="Assistive text" placeholder="Placeholder" />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" top-label="Top label" assistive-text="Assistive text" placeholder="Placeholder" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Password
 
-<ComponentDemo>
-  <form>
-    <MazInput v-model="passwordValue" label="Label" type="password" name="password" autocomplete="nope" />
-  </form>
-
-<template #code>
-
 ```html
 <MazInput v-model="passwordValue" label="Label" type="password" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Placeholder
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" placeholder="placeholder" autocomplete="off" />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" placeholder="placeholder" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Required
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" label="label required" required autocomplete="off" />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" label="label required" required />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Disabled
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" label="label disabled" disabled autocomplete="off" />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" label="label disabled" disabled />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Hint
 
 > Will replace the label, useful to display short message
 
-<ComponentDemo>
-  <MazInput v-model="defaultInputValue" label="label hint" hint="An error occured" error autocomplete="off" />
-
-<template #code>
-
 ```html
 <MazInput v-model="defaultInputValue" label="label hint" hint="An error occured" error />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Icons
 
-<MazInput
-  v-model="inputValue"
-  label="label icons"
-  start-icon="/banknotes.svg"
-  end-icon="/user.svg"
-  autocomplete="off"
-/>
-
 ### Use icon name
 
-::: details View code
+**Details: View code**
 
 When you use the properties `end-icon`, `start-icon` or `icon` with the icon name (string), the component uses `<MazIcon icon="..." />` component.
 
@@ -163,11 +93,9 @@ Check out how [MazIcon](./maz-icon.md) works, see all available icons and downlo
 <MazInput v-model="inputValue" label="label icons" start-icon="/banknotes.svg" end-icon="/user.svg" />
 ```
 
-:::
-
 ### Use your own SVG icons
 
-::: details View code
+**Details: View code**
 
 ```html
 <MazInput v-model="inputValue" label="label icons">
@@ -203,11 +131,9 @@ Check out how [MazIcon](./maz-icon.md) works, see all available icons and downlo
 </MazInput>
 ```
 
-:::
-
 ### Use [vite-svg-loader](https://github.com/jpkleemans/vite-svg-loader)
 
-::: details View code
+**Details: View code**
 
 ```vue
 <script lang="ts" setup>
@@ -229,13 +155,11 @@ const inputValue = ref('value')
 </template>
 ```
 
-:::
-
 ### Pass a full `MazIconProps` object
 
-`startIcon` and `endIcon` also accept a full `MazIconProps` object — pass the same shape `<MazIcon>` accepts to override the size, set a `<title>` for screen readers, attach `svgAttributes`, etc.
+`startIcon` and `endIcon` also accept a full `MazIconProps` object - pass the same shape `<MazIcon>` accepts to override the size, set a `<title>` for screen readers, attach `svgAttributes`, etc.
 
-::: details View code
+**Details: View code**
 
 ```vue
 <script lang="ts" setup>
@@ -259,28 +183,14 @@ const inputValue = ref('value')
 </template>
 ```
 
-:::
-
 ## Auto focus
 
 > Will focus automatically the component
 
-<ComponentDemo>
-  <MazInput
-    v-model="inputValue"
-    label="label auto-focus"
-    autocomplete="off"
-  />
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" label="label auto-focus" auto-focus />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Debounce
 
 > The value emit by the input will be delayed, usefull for searching
@@ -289,40 +199,13 @@ const inputValue = ref('value')
 >
 > If the debounce is true, the default debounce delay is 500ms
 
-<ComponentDemo>
-  <MazInput v-model="inputValue" label="label debounce" :debounce="1000" autocomplete="off" />
-
-  <p class="maz:mt-2">
-    modelValue: {{ inputValue ?? 'null' }}
-  </p>
-
-<template #code>
-
 ```html
 <MazInput v-model="inputValue" label="label debounce" :debounce="1000" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Sizes
 
-> Use the attribute `size` with a value in {{ sizes.join(', ') }}
-
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-2 maz:items-start">
-    <MazInput
-      v-for="size in sizes"
-      :key="size"
-      v-model="inputValue"
-      :label="['mini', 'xs'].includes(size) ? undefined : size"
-      :placeholder="['mini', 'xs'].includes(size) ? size : undefined"
-      :size="size"
-      autocomplete="off"
-    />
-  </div>
-
-<template #code>
+> Use the attribute `size` with a value in
 
 ```vue
 <script setup lang="ts">
@@ -340,32 +223,15 @@ const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
 </template>
 ```
 
-  </template>
-</ComponentDemo>
+**Note: Zoom on iOS**
 
-::: info Zoom on iOS
 iOS zooms the page when a focused field has a font size below `16px` (most sizes with a `14px` `base-font-size`). This applies to every form field: `MazInput` and the components built on it, `MazTextarea`, `MazInputCode`... To prevent it without changing the design of the fields, enable the `general.preventIosInputZoom` option of [@maz-ui/nuxt](../ecosystem/nuxt.md), or call [preventIosInputZoom](../ecosystem/utils/prevent-ios-input-zoom.md) from `@maz-ui/utils` in a Vue app.
-:::
 
 ## Colors
 
-::: tip
+**Tip:**
+
 Click on each input to show colors
-:::
-
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-2 maz:items-start">
-    <MazInput
-      v-for="name in colors"
-      :key="name"
-      v-model="inputValue"
-      :label="name"
-      :color="name"
-      autocomplete="off"
-    />
-  </div>
-
-<template #code>
 
 ```vue
 <script setup>
@@ -383,25 +249,10 @@ const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructi
 </template>
 ```
 
-  </template>
-</ComponentDemo>
-
 ## Rounded Size
 
 Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'`
 
-<ComponentDemo>
-  <div class="maz:flex maz:flex-col maz:gap-2 maz:items-start">
-    <MazInput rounded-size="none" placeholder="Rounded input" autocomplete="off" />
-    <MazInput rounded-size="sm" placeholder="Rounded input" autocomplete="off" />
-    <MazInput rounded-size="md" placeholder="Rounded input" autocomplete="off" />
-    <MazInput rounded-size="lg" placeholder="Rounded input" autocomplete="off" />
-    <MazInput rounded-size="xl" placeholder="Rounded input" autocomplete="off" />
-    <MazInput rounded-size="full" placeholder="Rounded input" autocomplete="off" />
-  </div>
-
-<template #code>
-
 ```html
 <MazInput rounded-size="none" placeholder="Rounded input" />
 <MazInput rounded-size="sm" placeholder="Rounded input" />
@@ -411,71 +262,73 @@ Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' |
 <MazInput rounded-size="full" placeholder="Rounded input" />
 ```
 
-  </template>
-</ComponentDemo>
-
 ## State
 
-<ComponentDemo title="destructive">
-  <MazInput v-model="inputValue" label="Label" error autocomplete="off" />
-
-<template #code>
+**destructive**
 
 ```html
 <MazInput v-model="inputValue" label="Label" error />
 ```
 
-  </template>
-</ComponentDemo>
-
-<br />
-<br />
-
-<ComponentDemo title="Warning">
-  <MazInput v-model="inputValue" label="Label" warning autocomplete="off" />
-
-<template #code>
+**Warning**
 
 ```html
 <MazInput v-model="inputValue" label="Label" warning />
 ```
 
-  </template>
-</ComponentDemo>
-
-<br />
-<br />
-
-<ComponentDemo title="Success">
-  <MazInput v-model="inputValue" label="Label" success autocomplete="off" />
-
-<template #code>
+**Success**
 
 ```html
 <MazInput v-model="inputValue" label="Label" success />
 ```
 
-  </template>
-</ComponentDemo>
-
-<script setup lang="ts">
-  import { ref, computed } from 'vue'
-  const inputValue = ref()
-  const passwordValue = ref()
-  const defaultInputValue = ref('any value')
-
-  const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
-
-  const colors = [
-    'primary',
-    'secondary',
-    'info',
-    'success',
-    'warning',
-    'destructive',
-    'accent',
-    'contrast',
-  ]
-</script>
-
-<!--@include: ./../../.vitepress/generated-docs/maz-input.doc.md-->
+## MazInput API
+
+`import MazInput from 'maz-ui/components/MazInput'`
+
+### Props
+
+- `model-value` (`T`, `v-model`): The current value of the input field. This prop is used for two-way data binding with v-model.
+- `placeholder` (`string`): Text displayed when the input is empty to guide the user.
+- `label` (`string`): Floating label that appears inside the input and moves up when focused or filled. Provides better UX than traditional placeholders.
+- `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
+- `assistive-text` (`string`): Helper text displayed below the input to provide additional context or validation feedback.
+- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Theme color that affects the border and focus states of the input.
+- `type` (`InputTypeHTMLAttribute`, default: `"text"`): HTML input type attribute that determines the input behavior and validation. Values: `'text'`, `'password'`, `'email'`, `'number'`, `'tel'`, `'url'`, `'search'`, `'date'`, `'time'`, `'datetime-local'`, `'month'`, `'week'` (non exhaustive).
+- `required` (`boolean`, default: `false`): Makes the input field mandatory for form submission.
+- `disabled` (`boolean`, default: `false`): Disables the input field, preventing user interaction and form submission.
+- `readonly` (`boolean`): Makes the input field read-only, allowing selection but preventing modification.
+- `id` (`string`): Unique identifier for the input element, used for form labels and accessibility.
+- `error` (`boolean`, default: `false`): Applies error styling (red border and text) to indicate validation failure.
+- `success` (`boolean`, default: `false`): Applies success styling (green border and text) to indicate successful validation.
+- `warning` (`boolean`, default: `false`): Applies warning styling (orange border and text) to indicate potential issues.
+- `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
+- `input-classes` (`string`): Additional CSS classes to apply specifically to the input wrapper element.
+- `border` (`boolean`, default: `true`): Controls whether the input has a visible border. Set to false for borderless inputs.
+- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
+- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Controls the height and text size of the input component.
+- `debounce` (`number | boolean`, default: `false`): Enables input debouncing to limit the frequency of value updates. When true, uses 500ms delay. When a number, uses that value as delay in milliseconds.
+- `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.
+- `border-active` (`boolean`, default: `false`): When true, shows the colored border immediately instead of only on focus.
+- `start-icon` (`any`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
+- `end-icon` (`any`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
+- `rounded-size` (`MazRoundedSize`, default: `'md'`): Controls the border radius of the input component. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
+- `block` (`boolean`): Makes the input expand to the full width of its container.
+- `name` (`string`): The name of the input field. Used for form submission and validation.
+- `autocomplete` (`string`): The autocomplete attribute for the input field. Used for form submission and validation.
+- `loading` (`boolean`, default: `false`): Loading state for the input field. Used to show a loading spinner.
+
+### Events
+
+- `@update:model-value` (payload: `value?: T | undefined`): Triggered when the input value changes, used for v-model two-way binding. This event is debounced if the debounce prop is enabled
+- `@click` (payload: `event: Event`): Triggered when the user clicks on the input field
+- `@blur` (payload: `event: Event`): Triggered when the input field loses focus (user clicks outside or tabs away)
+- `@change` (payload: `event: Event`): Triggered when the input value changes and the field loses focus. Different from input event which fires on every keystroke
+- `@focus` (payload: `event: Event`): Triggered when the input field gains focus (user clicks or tabs into the field)
+- `@input` (payload: `event: Event`): Triggered on every keystroke or input interaction (real-time input changes). This is the raw input event, not debounced
+
+### Slots
+
+- `#start-icon`: Custom content for the inline-start edge of the input field (left in LTR, right in RTL).
+- `#end-icon`: Custom content for the inline-end edge of the input field (right in LTR, left in RTL).
+- `#loader`: Loader slot.

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

@@ -0,0 +1,113 @@
+---
+title: "MazLazyImg"
+description: "MazLazyImg is a standalone component to display images and svgs with lazy loading"
+package: "maz-ui"
+url: "https://maz-ui.com/components/maz-lazy-img"
+---
+
+# MazLazyImg
+
+> MazLazyImg is a standalone component to display images and svgs with lazy loading
+
+- Package: `maz-ui`
+- Import: `import MazLazyImg from 'maz-ui/components/MazLazyImg'`
+- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
+- Web: https://maz-ui.com/components/maz-lazy-img
+
+> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)
+
+```vue
+<script setup lang="ts">
+import MazLazyImg from 'maz-ui/components/MazLazyImg'
+</script>
+
+<template>
+  <MazLazyImg src="https://placedog.net/1000/1000" block />
+</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.
+
+```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>
+```
+
+## MazLazyImg API
+
+`import MazLazyImg from 'maz-ui/components/MazLazyImg'`
+
+### Props
+
+- `src` (`MazImage | null`): The source of the image.
+- `alt` (`string`): The alt of the image.
+- `hide-loader` (`boolean`): Remove the loader.
+- `observer-once` (`boolean`, default: `true`): Remove the observer once the image is loaded.
+- `load-once` (`boolean`): Remove the observer once the image is loaded.
+- `image-height-full` (`boolean`): Make the image height full.
+- `observer-options` (`{ root?: HTMLElement | null | undefined; threshold: number; rootMargin?: string | undefined; }`): The options of the observer.
+- `fallback-src` (`string`): The fallback src to replace the src on loading error.
+- `img-class` (`ClassValue`): The classes of the image element.
+- `block` (`boolean`): The image will be displayed in full width.
+
+### Events
+
+- `@intersecting` (payload: `el: Element`): Emitted when the image is intersecting
+- `@loading` (payload: `el: Element`): Emitted when the image is loading
+- `@loaded` (payload: `el: Element`): Emitted when the image is loaded
+- `@error` (payload: `el: Element`): Emitted when the image is in error
+
+### Slots
+
+- `#default`