@maz-ui/mcp 5.0.0-beta.2 → 5.0.0-beta.24

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

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