@maz-ui/mcp 5.0.0-beta.17 → 5.0.0-beta.19

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

@@ -444,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' },
+)
+```

package/docs/src/ecosystem/utils/cookie.md

@@ -0,0 +1,80 @@
+---
+title: cookie
+description: Read, write and delete browser cookies with full attribute support — `path`, `domain`, `maxAge`, `expires`, `secure`, `sameSite`, `partitioned`.
+---
+
+# {{ $frontmatter.title }}
+
+{{ $frontmatter.description }}
+
+The module exports three functions: `getCookie`, `setCookie`, `deleteCookie`. Reads work both on the client (via `document.cookie`) and on the server (when you pass the raw `Cookie` header).
+
+## getCookie
+
+```ts
+import { getCookie } from '@maz-ui/utils'
+
+const theme = getCookie('theme') // 'dark' | null
+```
+
+```ts
+function getCookie(key: string, cookieHeader?: string): string | null
+```
+
+| Parameter      | Type     | Description                                                                                  |
+| -------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `key`          | `string` | Cookie name                                                                                  |
+| `cookieHeader` | `string` | (Optional) Raw `Cookie` request header — pass during SSR (e.g. from `useSSRContext()` in Nuxt) |
+
+Returns the URL-decoded value, or `null` when the cookie is absent.
+
+## setCookie
+
+```ts
+import { setCookie } from '@maz-ui/utils'
+
+setCookie('theme', 'dark')
+
+setCookie('session', token, {
+  maxAge: 60 * 60, // 1 hour
+  secure: true,
+  sameSite: 'Strict',
+})
+```
+
+```ts
+function setCookie(key: string, value: string, options?: CookieOptions): void
+```
+
+No-op on the server.
+
+### Options
+
+| Option        | Type      | Default          | Description                                                                       |
+| ------------- | --------- | ---------------- | --------------------------------------------------------------------------------- |
+| `path`        | `string`  | `'/'`            | Path attribute. Pass `null` to omit.                                              |
+| `domain`      | `string`  | —                | Domain attribute.                                                                 |
+| `maxAge`      | `number`  | `31_536_000` (1y) | Lifetime in seconds. Pass `null` for a session cookie.                            |
+| `expires`     | `Date`    | —                | Explicit expiration date. Takes precedence over `maxAge`.                         |
+| `secure`      | `boolean` | —                | Restrict to HTTPS.                                                                |
+| `sameSite`    | `'Lax' \| 'Strict' \| 'None'` | `'Lax'` | Same-site policy. Pass `null` to omit.                                            |
+| `partitioned` | `boolean` | —                | Mark the cookie as partitioned (CHIPS).                                           |
+
+::: warning `HttpOnly`
+`HttpOnly` cannot be set from `document.cookie` — browsers reject it. Use a server-set cookie for that.
+:::
+
+## deleteCookie
+
+```ts
+import { deleteCookie } from '@maz-ui/utils'
+
+deleteCookie('session')
+deleteCookie('analytics-id', { domain: '.example.com' })
+```
+
+```ts
+function deleteCookie(key: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void
+```
+
+For the deletion to take effect, `path` and `domain` must match the values used when the cookie was set.