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

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

@@ -1,15 +1,20 @@
 ---
 title: vLazyImg
-description: vLazyImg is a Vue directive to lazy load images with many options. The image will be loaded on user's scroll
+description: vLazyImg is a Vue directive to lazy load images with many options. Images are loaded when they enter the viewport, using a shared IntersectionObserver for optimal performance.
 ---
 
 # {{ $frontmatter.title }}
 
 {{ $frontmatter.description }}
 
+::: tip Performance
+Every element bound to the directive shares a pooled `IntersectionObserver` (grouped by observer options) and keeps its state per element. You can render hundreds of lazy images - like a list of [`MazAvatar`](./../components/maz-avatar.md) - with only a handful of observers and no leak when elements unmount.
+:::
+
 ## Basic usage
 
 <img
+  alt="Lazy loaded image"
   style="background-color: var(--maz-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="'https://placedog.net/1500/1000'"
@@ -49,11 +54,41 @@ import { vLazyImg } from 'maz-ui/directives'
 </template>
 ```
 
+## Disable lazy loading
+
+Set `disabled: true` to load the image immediately, bypassing the `IntersectionObserver`. Useful for above-the-fold images or server-side rendering.
+
+```vue
+<template>
+  <img
+    v-lazy-img="{ src: 'https://placedog.net/1500/1000', disabled: true }"
+  >
+</template>
+```
+
+## Fallback image on error
+
+Provide a `fallbackSrc` to replace the image when it fails to load. Set `fallbackSrc: false` to keep the broken image instead of loading the default placeholder.
+
+<img class="maz:size-40" v-lazy-img="{ src: 'https://broken-link.example' }" alt="broken image" />
+
+```vue
+<template>
+  <img
+    v-lazy-img="{
+      src: 'https://broken-link.example',
+      fallbackSrc: '/images/fallback.png',
+    }"
+  >
+</template>
+```
+
 ## Options
 
 > Open the developer console to show logs
 
 <img
+  alt="Lazy loaded image with options"
   style="background-color: var(--maz-surface-300); width: 80%;"
   class="flex flex-center rounded"
   v-lazy-img="lazyBinding"
@@ -61,8 +96,7 @@ import { vLazyImg } from 'maz-ui/directives'
 
 ```vue
 <script lang="ts" setup>
-import { vLazyImg, vLazyImgBindingValue } from 'maz-ui/directives'
-import { ref } from 'vue'
+import { vLazyImg, type vLazyImgBindingValue } from 'maz-ui/directives'
 
 const lazyBinding: vLazyImgBindingValue = {
   src: 'https://placedog.net/1500/1000',
@@ -71,7 +105,7 @@ const lazyBinding: vLazyImgBindingValue = {
   loadedClass: 'custom-class-loaded',
   errorClass: 'custom-class-error',
   fallbackClass: 'custom-class-fallback',
-  observerOnce: false, // launch onIntersecting function each times where the user scrolls on the image
+  observerOnce: false, // run onIntersecting each time the user scrolls onto the image
   loadOnce: false,
   onLoading: (el: Element) => console.log('loading', el),
   onLoaded: (el: Element) => console.log('loaded', el),
@@ -94,7 +128,6 @@ const lazyBinding: vLazyImgBindingValue = {
 ### Vue
 
 ```typescript
-import errorPhoto from 'path/to/error-photo.png'
 import { vLazyImgInstall, type vLazyImgOptions } from 'maz-ui/directives'
 import { createApp } from 'vue'
 
@@ -109,13 +142,12 @@ const vLazyImgOptions: vLazyImgOptions = {
   fallbackClass: 'm-lazy-fallback',
   observerOnce: true,
   loadOnce: true,
-  noUseErrorPhoto: false,
   observerOptions: {
     root: undefined,
     rootMargin: undefined,
     threshold: 0.1,
   },
-  errorPhoto,
+  fallbackSrc: '/images/fallback.png', // or `false` to disable the default placeholder
   onLoading: (el: Element) => console.log('loading', el),
   onLoaded: (el: Element) => console.log('loaded', el),
   onError: (el: Element) => console.log('error', el),
@@ -129,7 +161,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
 
@@ -147,7 +179,8 @@ export interface vLazyImgOptions {
     threshold: number
     rootMargin?: string
   }
-  fallbackSrc?: string
+  /** Image loaded on error - set to `false` to keep the broken image */
+  fallbackSrc?: string | false
   onLoading?: (el: Element) => unknown
   onLoaded?: (el: Element) => unknown
   onError?: (el: Element) => unknown
@@ -155,7 +188,9 @@ export interface vLazyImgOptions {
 }
 
 interface vLazyImgBindingOptions extends vLazyImgOptions {
+  /** The source of the image when the binding value is an options object */
   src?: string
+  /** Load the image immediately, bypassing the IntersectionObserver */
   disabled?: boolean
 }
 
@@ -164,7 +199,6 @@ export type vLazyImgBindingValue = string | vLazyImgBindingOptions
 
 <script lang="ts" setup>
   import { vLazyImg, type vLazyImgBindingValue } from 'maz-ui/directives/vLazyImg'
-  import { ref } from 'vue'
 
   const lazyBinding: vLazyImgBindingValue = {
     src: 'https://placedog.net/1500/1000',
@@ -173,7 +207,6 @@ export type vLazyImgBindingValue = string | vLazyImgBindingOptions
     loadedClass: 'custom-class-loaded',
     errorClass: 'custom-class-error',
     fallbackClass: 'custom-class-fallback',
-    noUseErrorPhoto: true,
     observerOnce: false,
     loadOnce: true,
     onLoading: (el: Element) => console.log('loading', el),

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
 

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

@@ -107,7 +107,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/ecosystem/eslint-config.md

@@ -114,6 +114,8 @@ defineConfig({
     detectComponentClasses: true,
     // Monorepo: directory used to resolve `tailwindcss` and the config file.
     cwd: 'apps/web',
+    // Custom `maz/tailwind-no-arbitrary-px` rule — see "Custom rules" below.
+    noArbitraryPx: true,
   },
 })
 ```
@@ -135,12 +137,98 @@ defineConfig({
 
 The plugin recognizes the most common class-name utilities out of the box (`clsx`, `cn`, `tw-merge`, `cva`, `tv`, …); see the [plugin docs](https://github.com/schoero/eslint-plugin-better-tailwindcss) for the full list and how to register your own.
 
+## Custom rules
+
+`@maz-ui/eslint-config` ships its own ESLint plugin under the **`maz/*`** namespace. Rules are grouped by category — `maz/tailwind-*` today, with room for `maz/js-*` and others as they get added.
+
+### `maz/tailwind-no-arbitrary-px`
+
+Forbids `px` units inside Tailwind arbitrary value classes (`w-[16px]`, `m-[-16px]`, `[gap:24px]`, …) and **autofixes** them to `rem` (or `em`) using your project's root font-size. Whitespace inside brackets (e.g. `[up to 100px]`) is left alone, so plain prose is never rewritten by accident.
+
+::: info Registered only when `tailwindcss` is enabled
+The `maz` plugin and the `maz/tailwind-*` rules are only added to the flat-config when `tailwindcss` is set to anything other than `false`. With `tailwindcss: false` *(default)*, neither the plugin nor the rule appear in the resolved config — keeping the preset zero-cost for non-Tailwind projects. To use the rule without opting into the full Tailwind preset, register `mazPlugin` manually (see [Use the plugin directly](#use-the-plugin-directly)).
+:::
+
+When `tailwindcss` is on, the rule is enabled with defaults. You can tune it two ways:
+
+**Standard ESLint override** *(idiomatic, max control)*
+
+```ts
+defineConfig({
+  tailwindcss: 'recommended',
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 10, unit: 'em' }],
+  },
+})
+```
+
+User `rules` overrides are applied in a *trailing* flat-config block, so they win over the defaults wired in by `tailwindcssConfigs`.
+
+**Ergonomic shortcut** *(set defaults via `tailwindcss.noArbitraryPx`)*
+
+```ts
+defineConfig({
+  tailwindcss: {
+    preset: 'recommended',
+    noArbitraryPx: {
+      baseFontSize: 16, // default — divide px by this to get rem
+      unit: 'rem', // default — output unit ('rem' | 'em')
+      severity: 'error', // default — 'off' | 'warn' | 'error'
+    },
+  },
+})
+```
+
+| `noArbitraryPx` value              | Behavior                                            |
+| ---------------------------------- | --------------------------------------------------- |
+| `true` *(default)*                 | Enabled with defaults (`baseFontSize: 16`, `rem`).  |
+| `false`                            | Disabled.                                           |
+| `{ baseFontSize, unit, severity }` | Override any subset of the defaults.                |
+
+If both are set, the standard `rules` override wins (it's the last block applied).
+
+What the autofix does (with `baseFontSize: 16`):
+
+| Before                  | After                    |
+| ----------------------- | ------------------------ |
+| `w-[16px]`              | `w-[1rem]`               |
+| `m-[-16px]`             | `m-[-1rem]`              |
+| `tracking-[.5px]`       | `tracking-[0.03125rem]`  |
+| `p-[16px_8px]`          | `p-[1rem_0.5rem]`        |
+| `[gap:24px]`            | `[gap:1.5rem]`           |
+| `w-[calc(100%-16px)]`   | `w-[calc(100%-1rem)]`    |
+| `md:hover:w-[16px]`     | `md:hover:w-[1rem]`      |
+
+The rule fires on:
+
+- JSX `className` strings and template literals
+- Vue SFC static `class="…"` attributes (via `vue-eslint-parser`)
+- Vue dynamic `:class` bindings, including string literals inside arrays / objects
+- Function-call arguments and tagged template literals (`clsx`, `cn`, `cva`, `tw`, …)
+
+### Use the plugin directly
+
+If you don't want the full Tailwind preset (or just prefer wiring rules yourself), import `mazPlugin` and register it in your own flat-config block. This is also the way to use `maz/tailwind-*` rules **without** enabling `tailwindcss` in `defineConfig`:
+
+```ts
+import { mazPlugin } from '@maz-ui/eslint-config'
+
+export default [{
+  files: ['**/*.{ts,tsx,vue}'],
+  plugins: { maz: mazPlugin },
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 16, unit: 'rem' }],
+  },
+}]
+```
+
 ## What it includes
 
 - **Antfu base** — TypeScript-aware rules, Stylistic formatting, modern import order.
 - **SonarJS** — code quality and complexity heuristics, with a relaxed set for `*.spec.ts` / `*.test.ts`.
 - **Vue rules** (when Vue/Nuxt is detected) — block-tag order, naming conventions, template a11y.
 - **Tailwind plugin** (opt-in) — class ordering, duplicate / deprecated / unknown / conflicting class detection — see [Tailwind support](#tailwind-support).
+- **`maz/*` custom rules** — namespaced ESLint plugin shipped with the preset; see [Custom rules](#custom-rules).
 - **Markdown** — prose linting baseline.
 - **vueAccessibility** (opt-in) — `eslint-plugin-vuejs-accessibility` rules with the AudioWorklet globals fix.
 
@@ -151,6 +239,7 @@ The plugin recognizes the most common class-name utilities out of the box (`clsx
 ```ts
 import {
   baseRules,
+  mazPlugin,
   sonarjsRules,
   tailwindcssConfigs,
   vueRules,
@@ -158,14 +247,19 @@ import {
 
 export default [
   {
+    plugins: { maz: mazPlugin },
     rules: {
       ...baseRules(true), // production = true → no-console: 'error'
       ...sonarjsRules,
       ...vueRules,
+      'maz/tailwind-no-arbitrary-px': 'error',
     },
   },
   // Drop in just the Tailwind block, with whatever preset and settings you want.
-  ...tailwindcssConfigs('stylistic', { entryPoint: 'src/main.css' }),
+  ...tailwindcssConfigs('stylistic', {
+    entryPoint: 'src/main.css',
+    noArbitraryPx: { unit: 'em' },
+  }),
 ]
 ```
 

package/docs/src/{guide/icons.md → ecosystem/icons/index.md}

@@ -151,7 +151,7 @@ Never worry about imports again with automatic component resolution.
 
 ::: warning Troubleshooting
 
-If your are already using [`MazComponentsResolver`](./resolvers.md#mazcomponentsresolver), you should place `MazIconsResolver` before `MazComponentsResolver` in the `resolvers` array.
+If your are already using [`MazComponentsResolver`](../../guide/resolvers.md#mazcomponentsresolver), you should place `MazIconsResolver` before `MazComponentsResolver` in the `resolvers` array.
 
 :::
 

package/docs/src/ecosystem/node/exec-promise.md

@@ -0,0 +1,87 @@
+---
+title: execPromise
+description: Promise-based wrapper around `child_process.exec` with structured stdout/stderr/error logging, package-scoped prefixes, and per-call log silencing.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { execPromise, logger } from '@maz-ui/node'
+
+try {
+  const { stdout } = await execPromise('npm --version')
+  logger.log('npm version:', stdout.trim())
+}
+catch (error) {
+  logger.error('Command failed', error)
+}
+```
+
+## API
+
+```ts
+function execPromise(
+  command: string,
+  options?: ExecPromiseOptions,
+): Promise<{ stdout: string, stderr: string }>
+
+interface ExecPromiseOptions {
+  logger?: CustomLogger
+  packageName?: string
+  noSuccess?: boolean
+  noStdout?: boolean
+  noStderr?: boolean
+  noError?: boolean
+  logLevel?: LogLevel
+  cwd?: string
+}
+```
+
+### Options
+
+| Option        | Type          | Default     | Description                                                                       |
+| ------------- | ------------- | ----------- | --------------------------------------------------------------------------------- |
+| `logger`      | `CustomLogger` | built-in    | Custom logger (must expose `log`, `error`, `info`, `warn`, `debug` methods).      |
+| `packageName` | `string`      | —           | Prepended to logs as `[name]: ` — useful when many commands share a logger.       |
+| `noSuccess`   | `boolean`     | `false`     | Skip the `info` line printed when the command finishes successfully.              |
+| `noStdout`    | `boolean`     | `false`     | Don't pipe stdout to the logger (still returned in the promise result).           |
+| `noStderr`    | `boolean`     | `false`     | Don't pipe stderr to the logger (still returned in the promise result).           |
+| `noError`     | `boolean`     | `false`     | Don't log errors before rejecting.                                                |
+| `logLevel`    | `LogLevel`    | unchanged   | Temporarily sets the default logger's level for this call.                        |
+| `cwd`         | `string`      | `process.cwd()` | Working directory for the command.                                                |
+
+The returned promise **resolves** with `{ stdout, stderr }` on success and **rejects** with the exec error on failure.
+
+## Examples
+
+Run a build silently, only reporting success/failure:
+
+```ts
+await execPromise('npm run build', {
+  packageName: 'build',
+  noStdout: true,
+  noStderr: true,
+})
+```
+
+Use a custom logger for an isolated subsystem:
+
+```ts
+import { createLogger, execPromise } from '@maz-ui/node'
+
+const ciLogger = createLogger({ level: 2 })
+
+await execPromise('npm test', {
+  logger: ciLogger,
+  packageName: 'tests',
+})
+```
+
+## Notes
+
+- `execPromise` uses Node's `child_process.exec`, which buffers all output in memory. For commands that produce very large streams, prefer `child_process.spawn` directly.
+- `stdout`/`stderr` are still returned in the promise result even when `noStdout`/`noStderr` are set — the flags only affect logging.

package/docs/src/ecosystem/node/index.md

@@ -0,0 +1,53 @@
+---
+title: '@maz-ui/node'
+description: Lightweight Node.js utilities — promise-based shell execution, an opinionated consola-backed logger, and a banner printer for CLIs.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+<NpmBadge package="@maz-ui/node" />
+
+`@maz-ui/node` powers the CLIs and build scripts inside the maz-ui ecosystem. It's intentionally tiny: an `exec` wrapper that returns a real `Promise`, a colourful logger built on [consola](https://github.com/unjs/consola), and a banner helper using [figlet](https://github.com/patorjk/figlet.js).
+
+## Installation
+
+::: code-group
+
+```bash [pnpm]
+pnpm add @maz-ui/node
+```
+
+```bash [npm]
+npm install @maz-ui/node
+```
+
+```bash [yarn]
+yarn add @maz-ui/node
+```
+
+:::
+
+## Basic usage
+
+```ts
+import { execPromise, logger, printBanner } from '@maz-ui/node'
+
+printBanner({ name: 'my-cli', version: '1.0.0' })
+
+logger.info('Running tests…')
+await execPromise('npm test', { packageName: 'tests' })
+logger.success('Done')
+```
+
+## What's inside
+
+- [`execPromise`](./exec-promise) — Promise-based `child_process.exec` with structured logging.
+- [`logger` / `createLogger`](./logger) — consola-backed logger with semantic log levels and helpers (`box`, `divider`, `brand`, …).
+- [`printBanner`](./print-banner) — ASCII-art banner printer (figlet) with versioning, dividers and clearing.
+
+## Requirements
+
+- Node.js >= 18.0.0
+- ESM only — published as `"type": "module"`.