@maz-ui/mcp 5.0.0-beta.11 → 5.0.0-beta.18

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

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

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/{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"`.

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

@@ -0,0 +1,146 @@
+---
+title: logger / createLogger
+description: Opinionated [consola](https://github.com/unjs/consola)-backed logger with semantic levels, status helpers (`success`, `ready`, `fail`), and formatting helpers (`box`, `divider`, `brand`).
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+The default `logger` is a singleton ready to use; `createLogger` builds a fresh instance with its own level and reporters.
+
+## Quick start
+
+```ts
+import { logger } from '@maz-ui/node'
+
+logger.info('Build started')
+logger.success('All checks passed')
+logger.warn('Deprecated flag used')
+logger.error('Build failed', errorObject)
+```
+
+## Default instance
+
+```ts
+import { logger } from '@maz-ui/node'
+```
+
+A pre-configured `Logger` with `level: 'default'` (numeric 3). Suitable for most scripts.
+
+## Custom instances
+
+```ts
+import { createLogger } from '@maz-ui/node'
+
+const dev = createLogger({ level: 4 }) // debug
+const ci = createLogger({ level: 2 }) // normal
+const silent = createLogger({ level: Number.NEGATIVE_INFINITY })
+```
+
+```ts
+function createLogger(options?: LoggerOptions): Logger
+
+type LoggerOptions = Partial<ConsolaOptions>
+```
+
+`LoggerOptions` is forwarded directly to [consola's `createConsola()`](https://github.com/unjs/consola#instance-options) — see consola docs for every accepted field (tag, reporters, formatOptions, …).
+
+## API
+
+```ts
+interface Logger {
+  // Core
+  log(message, ...args): void
+  info(message, ...args): void
+  warn(message, ...args): void
+  error(message, ...args): void
+  debug(message, ...args): void
+  trace(message, ...args): void
+  verbose(message, ...args): void
+  silent(message, ...args): void
+  fatal(message, ...args): void
+
+  // Status
+  start(message, ...args): void
+  ready(message, ...args): void
+  success(message, ...args): void
+  fail(message, ...args): void
+
+  // Formatting
+  box(message, ...args): void
+  brand(message: string): void
+  divider(character?: string): void
+  eot(): void
+  break(count?: number): void
+  clear(): void
+
+  // Reporters
+  addReporter(reporter: ConsolaReporter): void
+  removeReporter(reporter: ConsolaReporter): void
+
+  // Level control
+  setLevel(level: LogLevel): void
+  getLevel(): number
+}
+```
+
+### Log levels
+
+`setLevel()` accepts a semantic name. Anything below the active level is suppressed.
+
+| Level       | Numeric           | Description                  |
+| ----------- | ----------------- | ---------------------------- |
+| `'silent'`  | `-Infinity`       | No logs displayed            |
+| `'error'`   | `0`               | Fatal and error only         |
+| `'warning'` | `1`               | Warnings and above           |
+| `'normal'`  | `2`               | Normal logs and above        |
+| `'default'` | `3` (default)     | Informational logs           |
+| `'debug'`   | `4`               | Debug logs and above         |
+| `'trace'`   | `5`               | All logs including trace     |
+| `'verbose'` | `Infinity`        | Maximum verbosity            |
+
+```ts
+logger.setLevel('debug')
+logger.debug('Now visible')
+
+logger.setLevel('silent')
+logger.error('No longer printed')
+```
+
+### Formatting helpers
+
+| Method       | Output                                                              |
+| ------------ | ------------------------------------------------------------------- |
+| `box(msg)`   | Renders the message inside a bordered box.                          |
+| `brand(msg)` | Prints in bright blue — used by `printBanner`.                      |
+| `divider(c)` | Prints a separator line that adapts to the terminal width.          |
+| `eot()`      | Prints a blank line (end-of-transmission marker).                   |
+| `break(n)`   | Prints `n` blank lines (default: 1).                                |
+
+## Examples
+
+Build script with mixed levels:
+
+```ts
+import { createLogger, execPromise } from '@maz-ui/node'
+
+const log = createLogger({ level: 3 })
+
+log.box('🚀 Build starting')
+log.divider()
+
+await execPromise('npm install', { logger: log, packageName: 'setup' })
+log.ready('Dependencies installed')
+
+await execPromise('npm run build', { logger: log, packageName: 'build' })
+log.success('Build complete')
+```
+
+Switch verbosity from an env flag:
+
+```ts
+const log = createLogger({
+  level: process.env.CI ? 2 : 4,
+})
+```

package/docs/src/ecosystem/node/print-banner.md

@@ -0,0 +1,93 @@
+---
+title: printBanner
+description: Print an ASCII-art banner via figlet with optional version, dividers and clearing — handy for CLI entry points.
+---
+
+# {{ $frontmatter.title }}
+
+Print an ASCII-art banner (via [figlet](https://github.com/patorjk/figlet.js)) with optional version, dividers and clearing — handy for CLI entry points.
+
+## Usage
+
+```ts
+import { printBanner } from '@maz-ui/node'
+
+printBanner({
+  name: 'maz-cli',
+  version: 'v1.0.0',
+})
+```
+
+Renders:
+
+```text
+███╗   ███╗ █████╗ ███████╗     ██████╗██╗     ██╗
+████╗ ████║██╔══██╗╚══███╔╝    ██╔════╝██║     ██║
+██╔████╔██║███████║  ███╔╝     ██║     ██║     ██║
+██║╚██╔╝██║██╔══██║ ███╔╝      ██║     ██║     ██║
+██║ ╚═╝ ██║██║  ██║███████╗    ╚██████╗███████╗██║
+╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝     ╚═════╝╚══════╝╚═╝
+
+v1.0.0
+```
+
+## API
+
+```ts
+function printBanner(args: {
+  name: string
+  version?: string
+  options?: FigletOptions & {
+    clear?: boolean
+    divider?: boolean
+    breakBefore?: boolean
+    breakAfter?: boolean
+  }
+}): void
+```
+
+| Parameter | Type      | Description                                  |
+| --------- | --------- | -------------------------------------------- |
+| `name`    | `string`  | Text rendered as ASCII art (required).       |
+| `version` | `string`  | Optional version line printed under the banner. |
+| `options` | `object`  | Figlet options + extras (see below).         |
+
+### Options
+
+| Option             | Type      | Default        | Description                                                              |
+| ------------------ | --------- | -------------- | ------------------------------------------------------------------------ |
+| `clear`            | `boolean` | `true`         | Clear the terminal screen before printing.                               |
+| `divider`          | `boolean` | `false`        | Print a separator line after the banner.                                 |
+| `breakBefore`      | `boolean` | `true`         | Print a blank line before the banner.                                    |
+| `breakAfter`       | `boolean` | `true`         | Print a blank line after the banner.                                     |
+| `font`             | `string`  | `'ANSI Shadow'` | Any [figlet font name](https://github.com/patorjk/figlet.js#fonts).      |
+| `horizontalLayout` | `string`  | `'full'`       | Figlet horizontal layout: `'default'`, `'full'`, `'fitted'`, …            |
+
+All standard [`figlet` options](https://github.com/patorjk/figlet.js#api) are forwarded.
+
+## Examples
+
+Minimal banner:
+
+```ts
+printBanner({ name: 'maz-cli' })
+```
+
+Banner with divider, no screen clearing:
+
+```ts
+printBanner({
+  name: 'maz-cli',
+  version: 'v1.0.0',
+  options: { clear: false, divider: true },
+})
+```
+
+Custom font:
+
+```ts
+printBanner({
+  name: 'Hi!',
+  options: { font: 'Standard', horizontalLayout: 'fitted' },
+})
+```

package/docs/src/{guide → ecosystem}/nuxt.md

@@ -436,7 +436,7 @@ export default defineNuxtConfig({
 ```
 
 ::: tip Subtree Overrides with MazUiProvider
-You can use [`MazUiProvider`](./maz-ui-provider.md) within a Nuxt app to override theme or translations in a specific subtree, while the module handles global defaults.
+You can use [`MazUiProvider`](../guide/maz-ui-provider.md) within a Nuxt app to override theme or translations in a specific subtree, while the module handles global defaults.
 :::
 
 ## Troubleshooting

package/docs/src/{guide → ecosystem}/themes.md

@@ -1,11 +1,11 @@
 ---
 title: Theming
-description: Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
+description: Modern and performant theme system for Maz-UI built on native CSS features (light-dark(), color-scheme, color-mix(in oklch)) for v5.
 ---
 
 # {{ $frontmatter.title }}
 
-{{ $frontmatter.description }}
+Modern and performant theme system for Maz-UI built on native CSS features (`light-dark()`, `color-scheme`, `color-mix(in oklch)`) for v5.
 
 <NpmBadge package="@maz-ui/themes"></NpmBadge>
 
@@ -56,7 +56,7 @@ app.use(MazUi, {
 ```
 
 ::: tip Alternative: MazUiProvider
-You can also initialize the theme via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
+You can also initialize the theme via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped themes.
 :::
 
 ### 2. Setup your CSS to support theme foundation and dark mode
@@ -999,7 +999,7 @@ For deeper detail on the generated CSS contract, see the [`@maz-ui/themes` READM
 
 ## Usage with Nuxt
 
-For Nuxt users, check the [dedicated Nuxt documentation](/guide/nuxt) which covers installation and framework-specific configuration.
+For Nuxt users, check the [dedicated Nuxt documentation](/ecosystem/nuxt) which covers installation and framework-specific configuration.
 
 ## Migration from Legacy System
 

package/docs/src/{guide → ecosystem}/translations.md

@@ -73,7 +73,7 @@ app.use(MazUi, {
 ```
 
 ::: tip Alternative: MazUiProvider
-You can also provide translations via the [`MazUiProvider`](./maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
+You can also provide translations via the [`MazUiProvider`](../guide/maz-ui-provider.md) component for lazy-loaded pages or subtree-scoped configurations.
 :::
 
 ## How it works

package/docs/src/ecosystem/utils/camel-case.md

@@ -0,0 +1,31 @@
+---
+title: camelCase
+description: Convert a kebab-case string to camelCase by stripping dashes and uppercasing the following letter.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+## Usage
+
+```ts
+import { camelCase } from '@maz-ui/utils'
+
+camelCase('my-component-name') // → 'myComponentName'
+camelCase('hello-world') // → 'helloWorld'
+```
+
+## API
+
+```ts
+function camelCase(str: string): string
+```
+
+| Parameter | Type     | Description           |
+| --------- | -------- | --------------------- |
+| `str`     | `string` | The string to convert |
+
+## Notes
+
+`camelCase` is intentionally minimal — it only handles `kebab-case` input. For more general normalization (snake_case, spaces, PascalCase), use [`normalizeString`](./normalize-string) with the `case: 'camelCase'` option.

package/docs/src/ecosystem/utils/check-availability.md

@@ -0,0 +1,79 @@
+---
+title: checkAvailability
+description: Poll a getter until a value is available (or matches an expected value), then run a callback — with timeout and configurable retry interval.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+Useful for waiting on a third-party SDK to attach itself to `window`, on a Vue ref to be populated after mount, or on any asynchronously-available value.
+
+## Usage
+
+```ts
+import { checkAvailability } from '@maz-ui/utils'
+
+checkAvailability(
+  () => window.Stripe,
+  (Stripe) => {
+    const stripe = Stripe('pk_...')
+  },
+)
+```
+
+## API
+
+```ts
+function checkAvailability<T>(
+  getRef: () => T | null | undefined,
+  callback: (value: NonNullable<T>) => void,
+  options?: {
+    maxAttempts?: number
+    interval?: number
+    expectedValue?: T
+    errorMessage?: string
+    onError?: (error: Error) => void
+  },
+): void
+```
+
+| Option          | Type       | Default | Description                                                            |
+| --------------- | ---------- | ------- | ---------------------------------------------------------------------- |
+| `maxAttempts`   | `number`   | `20`    | Number of polls before giving up                                       |
+| `interval`      | `number`   | `100`   | Delay between polls, in milliseconds                                   |
+| `expectedValue` | `T`        | —       | When set, callback fires only when `getRef()` strictly equals this value |
+| `errorMessage`  | `string`   | —       | Custom error message when `maxAttempts` is exceeded                    |
+| `onError`       | `Function` | —       | Called with the timeout `Error` instead of throwing                    |
+
+With default options, the helper polls every 100 ms up to 20 times — a 2 second timeout in total.
+
+## Examples
+
+Wait for a global SDK with a custom timeout:
+
+```ts
+checkAvailability(
+  () => window.gtag,
+  (gtag) => {
+    gtag('event', 'page_view')
+  },
+  {
+    maxAttempts: 50,
+    interval: 200,
+    onError: (err) => {
+      console.warn('gtag never loaded', err)
+    },
+  },
+)
+```
+
+Wait for a specific value (e.g. SDK becomes ready):
+
+```ts
+checkAvailability(
+  () => window.__SDK_STATE__,
+  () => boot(),
+  { expectedValue: 'ready' },
+)
+```