@maz-ui/mcp 5.0.0-beta.47 → 5.0.0-beta.49

package/dist/mcp.mjs

@@ -7,7 +7,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const version = "5.0.0-beta.46";
+const version = "5.0.0-beta.48";
 
 class MetadataExtractor {
   extract(name, type, content, manualTags = []) {

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

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

package/docs/src/composables/use-form-validator.md

@@ -1,6 +1,6 @@
 ---
 title: useFormValidator
-description: Vue composables for form validation with Valibot - useFormValidator and useFormField provide a flexible and typed approach to handle form validation in your Vue applications.
+description: Vue composables for form validation with any Standard Schema library (Valibot, Zod, ArkType...) - useFormValidator and useFormField provide a flexible and typed approach to handle form validation in your Vue applications.
 ---
 
 # {{ $frontmatter.title }}
@@ -9,7 +9,7 @@ description: Vue composables for form validation with Valibot - useFormValidator
 
 ## Introduction
 
-`useFormValidator` and `useFormField` are two Vue composables that work together to provide powerful form validation using [Valibot](https://valibot.dev/guides/introduction/).
+`useFormValidator` and `useFormField` are two Vue composables that work together to provide powerful form validation. They are **validation library agnostic**: any library implementing [Standard Schema](https://standardschema.dev) works out of the box, like [Valibot](https://valibot.dev), [Zod](https://zod.dev) or [ArkType](https://arktype.io). See [Validation Libraries](#validation-libraries).
 
 - **useFormValidator**: Initializes form validation for your entire form. Use it in your form's parent component.
 - **useFormField**: Manages individual field validation states. Use it when you need fine-grained control over a field or when fields are in child components.
@@ -23,6 +23,24 @@ description: Vue composables for form validation with Valibot - useFormValidator
 
 ## Quick Start
 
+Install the validation library of your choice (Valibot is used in most examples of this page):
+
+::: code-group
+
+```bash [valibot]
+pnpm add valibot
+```
+
+```bash [zod]
+pnpm add zod
+```
+
+```bash [arktype]
+pnpm add arktype
+```
+
+:::
+
 Here's the simplest form you can create with `useFormValidator`:
 
 <ComponentDemo>
@@ -104,6 +122,186 @@ const onSubmit = handleSubmit((data) => {
   </template>
 </ComponentDemo>
 
+## Validation Libraries
+
+`useFormValidator` relies on [Standard Schema](https://standardschema.dev), a common interface shared by the main validation libraries. Maz-UI does not ship any validation library: install the one you prefer and pass its schemas. Valibot, Zod and ArkType are declared as optional peer dependencies of `maz-ui`, so your package manager warns you if the installed version is not supported.
+
+| Library | Supported versions |
+|---------|--------------------|
+| [Valibot](https://valibot.dev) | `>=1.0.0 <2.0.0` |
+| [Zod](https://zod.dev) | `>=3.24.0 <5.0.0` (v3 and v4) |
+| [ArkType](https://arktype.io) | `>=2.0.0 <3.0.0` |
+| [Others](https://standardschema.dev/#what-schema-libraries-implement-the-spec) | Any library implementing Standard Schema V1 |
+
+The `schema` option is always a **plain object** where each key is a field name and each value is a schema of your library. Do not wrap it with `object()` / `z.object()`.
+
+### Same form, different libraries
+
+::: code-group
+
+```ts [valibot]
+import { useFormValidator } from 'maz-ui/composables'
+import { email, minLength, nonEmpty, pipe, string } from 'valibot'
+
+const { model, errorMessages, handleSubmit } = useFormValidator({
+  schema: {
+    email: pipe(string(), nonEmpty('Email is required'), email('Invalid email')),
+    password: pipe(string(), minLength(8, 'Min 8 characters')),
+  },
+})
+```
+
+```ts [zod]
+import { useFormValidator } from 'maz-ui/composables'
+import { z } from 'zod'
+
+const { model, errorMessages, handleSubmit } = useFormValidator({
+  schema: {
+    email: z.string().min(1, 'Email is required').pipe(z.email('Invalid email')),
+    password: z.string().min(8, 'Min 8 characters'),
+  },
+})
+```
+
+```ts [arktype]
+import { type } from 'arktype'
+import { useFormValidator } from 'maz-ui/composables'
+
+const { model, errorMessages, handleSubmit } = useFormValidator({
+  schema: {
+    email: type('string.email'),
+    password: type('string >= 8'),
+  },
+})
+```
+
+:::
+
+### Live example with Zod
+
+<ComponentDemo>
+  <form class="maz:flex maz:flex-col maz:gap-4" @submit="onSubmitZod">
+    <MazInput
+      v-model="zodModel.username"
+      label="Username"
+      :hint="zodErrors.username"
+      :error="!!zodErrors.username"
+      :success="zodStates.username.valid"
+    />
+    <MazInput
+      v-model="zodModel.age"
+      label="Age"
+      type="number"
+      :hint="zodErrors.age"
+      :error="!!zodErrors.age"
+      :success="zodStates.age.valid"
+    />
+    <MazBtn type="submit" :loading="zodSubmitting">
+      Submit
+    </MazBtn>
+  </form>
+
+  <template #code>
+
+```vue
+<script lang="ts" setup>
+import { useFormValidator } from 'maz-ui/composables'
+import { z } from 'zod'
+
+const schema = {
+  username: z.string().min(1, 'Username is required').min(3, 'Min 3 characters'),
+  age: z.number({ error: 'Age is required' }).min(18, 'Min 18').max(100, 'Max 100'),
+}
+
+const {
+  model,
+  errorMessages,
+  fieldsStates,
+  isSubmitting,
+  handleSubmit,
+} = useFormValidator({ schema })
+
+const onSubmit = handleSubmit((data) => {
+  // data is typed as { username: string, age: number }
+  console.log('Form submitted:', data)
+})
+</script>
+
+<template>
+  <form @submit="onSubmit">
+    <MazInput
+      v-model="model.username"
+      label="Username"
+      :hint="errorMessages.username"
+      :error="!!errorMessages.username"
+      :success="fieldsStates.username.valid"
+    />
+    <MazInput
+      v-model="model.age"
+      label="Age"
+      type="number"
+      :hint="errorMessages.age"
+      :error="!!errorMessages.age"
+      :success="fieldsStates.age.valid"
+    />
+    <MazBtn type="submit" :loading="isSubmitting">
+      Submit
+    </MazBtn>
+  </form>
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### Mixing libraries
+
+Each field is validated by its own schema, so you can mix libraries in the same form (useful during a progressive migration from one library to another):
+
+```ts
+import { useFormValidator } from 'maz-ui/composables'
+import { email, pipe, string } from 'valibot'
+import { z } from 'zod'
+
+const { model } = useFormValidator({
+  schema: {
+    email: pipe(string(), email('Invalid email')),
+    age: z.number().min(18, 'Min 18'),
+  },
+})
+```
+
+### Custom schema
+
+You can also write your own validator by implementing the `StandardSchemaV1` interface (exported by `maz-ui/composables`). `validate` can be synchronous or return a `Promise`:
+
+```ts
+import type { StandardSchemaV1 } from 'maz-ui/composables'
+import { useFormValidator } from 'maz-ui/composables'
+
+const frenchZipCode: StandardSchemaV1<string, string> = {
+  '~standard': {
+    version: 1,
+    vendor: 'my-app',
+    validate: value =>
+      typeof value === 'string' && /^\d{5}$/.test(value)
+        ? { value }
+        : { issues: [{ message: 'Invalid zip code' }] },
+  },
+}
+
+const { model } = useFormValidator({
+  schema: { zipCode: frenchZipCode },
+})
+```
+
+### Good to know
+
+- **Empty values**: `undefined` and `null` field values are validated as an empty string (`''`). To make a field required, use a length rule (`nonEmpty()` with Valibot, `.min(1)` with Zod). An optional field with a format rule (email, URL...) has to accept the empty string explicitly, for example `z.email().or(z.literal(''))` with Zod or `union([literal(''), pipe(string(), email())])` with Valibot.
+- **Error messages**: `errorMessages` contains the message of the first issue of each field, whatever the library.
+- **Issues type**: `errors` and `fieldsStates[field].errors` are typed as `ValidationIssues`, the Standard Schema issue shape (`message` and `path`). At runtime, they are the native issues of your library, so you can cast them to access library specific properties (for example `BaseIssue<unknown>` from Valibot or `z.core.$ZodIssue` from Zod).
+- **Type inference**: the `model` type (input) and the `handleSubmit` payload type (output, after transformations) are inferred from the schemas whatever the library.
+
 ## Understanding Form State
 
 `useFormValidator` returns several reactive values to help you manage your form:
@@ -699,7 +897,7 @@ const { value, errorMessage, hasError, validationEvents } = useFormField<string>
 
 ## TypeScript Type Inference
 
-The form model is automatically typed based on your schema:
+The form model is automatically typed based on your schema, whatever the validation library:
 
 ```ts
 const schema = {
@@ -745,7 +943,23 @@ const { value: email } = useFormField<string>('email', {
 
 ## Async Validation
 
-Use Valibot's `pipeAsync` and `checkAsync` for async validations like checking username availability:
+Async validations (like checking username availability) are supported by every library: Valibot's `pipeAsync` and `checkAsync`, Zod's async `refine`, etc. The example below uses Valibot, here is the Zod equivalent of the schema:
+
+```ts
+import { z } from 'zod'
+
+const schema = {
+  username: z
+    .string()
+    .min(1, 'Username is required')
+    .min(3, 'Min 3 characters')
+    .refine(async (value) => {
+      // Simulate API call
+      await new Promise(resolve => setTimeout(resolve, 2000))
+      return value !== 'taken'
+    }, 'Username is already taken'),
+}
+```
 
 <ComponentDemo>
   <div class="maz:mb-4">
@@ -1065,7 +1279,7 @@ If your custom component isn't detected for blur events, add `data-interactive`:
 
 ```ts
 useFormValidator<TSchema>({
-  schema: TSchema,                                    // Valibot validation schema (required)
+  schema: TSchema,                                    // Object of Standard Schema field schemas: Valibot, Zod, ArkType... (required)
   model?: Ref<Model>,                                 // External model ref (optional)
   defaultValues?: DeepPartial<Model>,                 // Initial values (optional)
   options?: {
@@ -1140,6 +1354,14 @@ useFormField<FieldType>(
 ### Types
 
 ```ts
+// Standard Schema issue (https://standardschema.dev)
+interface ValidationIssue {
+  readonly message: string
+  readonly path?: ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+}
+
+type ValidationIssues = ValidationIssue[]
+
 interface FormValidatorOptions<Model> {
   mode?: 'eager' | 'lazy' | 'aggressive' | 'blur' | 'progressive'
   throttledFields?: Partial<Record<keyof Model, number | true>>
@@ -1252,9 +1474,29 @@ import {
   pipeAsync,
   checkAsync,
 } from 'valibot'
+import { z } from 'zod'
 
 const toast = useToast()
 
+// Zod Demo
+const zodSchema = {
+  username: z.string().min(1, 'Username is required').min(3, 'Min 3 characters'),
+  age: z.number({ error: 'Age is required' }).min(18, 'Min 18').max(100, 'Max 100'),
+}
+
+const {
+  model: zodModel,
+  errorMessages: zodErrors,
+  fieldsStates: zodStates,
+  isSubmitting: zodSubmitting,
+  handleSubmit: handleZod,
+} = useFormValidator({ schema: zodSchema })
+
+const onSubmitZod = handleZod(async (data) => {
+  await sleep(1000)
+  toast.success(`Welcome ${data.username} (${data.age})!`, { position: 'top' })
+})
+
 // Quick Start Demo
 const quickStartSchema = {
   email: pipe(string(), nonEmpty('Email is required'), email('Invalid email')),

package/docs/src/guide/migration-v5.md

@@ -86,7 +86,8 @@ The MCP server is read-only — it ships docs, not code edits — so the assista
 9. **`MazAvatar` size scale fixed.** A CSS-unit `size` now renders at its real value (`size="2rem"` is a 32px avatar, it was ~96px before). Multiply your unit values by 3 to keep the same render, or switch to a `MazSize` keyword (`'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'`). The upgrade tool does the ×3 rewrite for you on static values.
 10. Rename **`MazPullToRefresh`**'s `on-click` prop to `on-refresh` (handled by the upgrade tool).
 11. Replace bare **`from 'maz-ui'`** utility imports with **`from '@maz-ui/utils'`** (the root re-export of utils was removed; handled by the upgrade tool). Components/composables/directives/plugins stay on their subpaths; types remain importable from `maz-ui`.
-12. That's it for most apps. Everything else is opt-in.
+12. If you use **`useFormValidator` / `useFormField`** with Valibot, add **`valibot`** to your own dependencies (it is no longer installed by `maz-ui`). The composables now accept any [Standard Schema](https://standardschema.dev) library (Valibot, Zod, ArkType...).
+13. That's it for most apps. Everything else is opt-in.
 
 ## Prerequisites
 
@@ -642,6 +643,48 @@ import type { MazColor, MazSize } from 'maz-ui'
 
 `maz-ui` and its `@maz-ui/*` packages ship **ESM only** (no CommonJS build). This was already the case in v4, but if you consume the library from a CommonJS context (old Jest without ESM, `require()`), use a bundler/test runner with ESM support (Vitest, Jest ≥ 29 with ESM, or native `import`).
 
+### 20. `useFormValidator`: validation library agnostic (Standard Schema)
+
+`useFormValidator` and `useFormField` no longer depend on Valibot. They accept any library implementing [Standard Schema](https://standardschema.dev): Valibot (>= 1.0), Zod (>= 3.24), ArkType (>= 2.0), or your own validator. Your existing Valibot schemas keep working as is: same validation, same error messages, same inferred types for `model` and the `handleSubmit` payload.
+
+```ts
+// v4 and v5 - unchanged
+import { pipe, string, minLength } from 'valibot'
+useFormValidator({ schema: { name: pipe(string(), minLength(3)) } })
+
+// v5 - Zod (or mix both in the same schema)
+import { z } from 'zod'
+useFormValidator({ schema: { name: z.string().min(3) } })
+```
+
+What can break:
+
+**`valibot` is no longer a dependency of `maz-ui`.** Valibot, Zod and ArkType are now declared as optional peer dependencies (`valibot >=1.0.0 <2.0.0`, `zod >=3.24.0 <5.0.0`, `arktype >=2.0.0 <3.0.0`). If your app imports `valibot` without declaring it (it was installed transitively), add it:
+
+```bash
+pnpm add valibot
+```
+
+**Issue types are now the Standard Schema ones.** `ValidationIssues` (returned by `errors`, `fieldsStates[field].errors`, `useFormField().errors` and the `onError` payload of `handleSubmit`) is now typed as an array of `{ message: string, path?: ... }` instead of Valibot's `BaseIssue<unknown>`. Only TypeScript is affected: at runtime, the issues are still the native Valibot objects. If you read Valibot specific properties (`kind`, `type`, `input`, `expected`, `received`, `requirement`...), cast the issue:
+
+```ts
+import type { BaseIssue } from 'valibot'
+
+// v4
+const type = errors.value.email[0].type
+
+// v5
+const type = (errors.value.email[0] as BaseIssue<unknown>).type
+```
+
+**`FormSchema` values are typed as `StandardSchemaV1`.** If you typed a schema object with `FormSchema<Model>` and then read Valibot specific properties of its entries (`schema.email.type`, `schema.email.pipe`...), declare the object with `as const satisfies FormSchema<Model>` or without annotation, so TypeScript keeps the Valibot types.
+
+```bash
+# Find usages to check
+rg "useFormValidator|useFormField" src/
+rg "from 'valibot'" src/
+```
+
 ## Informational changes (probably no action needed)
 
 ### Theme colors are now emitted as OKLCh

package/docs/src/index.md

@@ -465,7 +465,7 @@ description: Build amazing interfaces with Maz-UI - standalone components & tool
       </div>
       <h3 class="maz:text-base maz:font-semibold">useFormValidator</h3>
       <p class="maz:dark:text-gray-300 maz:text-muted maz:text-sm">
-        A Vue composable designed to simplify form validation using Valibot as the validation library. Offers a flexible and typed approach to handle form validation.
+        A Vue composable designed to simplify form validation with any Standard Schema library (Valibot, Zod, ArkType...). Offers a flexible and typed approach to handle form validation.
       </p>
       <div class="maz:flex-1"></div>
       <MazBtn color="surface" outlined size="sm" block href="/composables/use-form-validator">Discover</MazBtn>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/mcp",
   "type": "module",
-  "version": "5.0.0-beta.47",
+  "version": "5.0.0-beta.49",
   "description": "Maz-UI ModelContextProtocol Client",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -43,7 +43,7 @@
   "dependencies": {
     "@maz-ui/utils": "5.0.0-beta.46",
     "@modelcontextprotocol/sdk": "^1.32.0",
-    "maz-ui": "5.0.0-beta.47"
+    "maz-ui": "5.0.0-beta.49"
   },
   "devDependencies": {
     "@maz-ui/eslint-config": "5.0.0-beta.47",