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

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

@@ -126,11 +126,13 @@ export default defineNuxtConfig({
     theme: {
       preset: 'maz-ui', // 'maz-ui' | 'pristine' | 'ocean' | 'obsidian' | 'nova' | custom object
       strategy: 'runtime', // 'runtime' | 'buildtime'
-      darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
+      darkModeStrategy: 'class', // 'class' | 'media'
+      darkClass: 'dark', // class on <html> when colorMode === 'dark' (default: 'dark')
+      lightClass: 'light', // class on <html> when colorMode === 'light' (default: 'light')
       overrides: {
         colors: {
-          light: { primary: '220 100% 50%' },
-          dark: { primary: '220 100% 70%' }
+          light: { primary: 'oklch(0.65 0.19 254)' },
+          dark: { primary: 'oklch(0.72 0.18 254)' }
         }
       },
       mode: 'both', // 'light' | 'dark' | 'both'
@@ -150,6 +152,16 @@ export default defineNuxtConfig({
       autoImport: true, // All components globally available
     },
 
+    // Global component defaults (priority: instance prop > defaults[Component] > defaults.global > library default)
+    defaults: {
+      global: { roundedSize: 'lg' }, // cross-cutting (roundedSize, size)
+      MazBtn: { roundedSize: 'full' }, // per-component, wins over global
+      MazCard: { bordered: false, elevation: true },
+    },
+
+    // Country flags of MazSelectCountry and MazInputPhoneNumber: 'cdn' (default), 'local' (offline) or '/flags/{code}.svg'
+    flags: 'local',
+
     // Plugins (not enabled by default)
     plugins: {
       aos: true,
@@ -220,16 +232,16 @@ const theme = {
   overrides: {
     colors: {
       light: {
-        primary: '220 100% 50%',
-        secondary: '220 14% 96%',
-        surface: '0 0% 100%',
-        foreground: '222 84% 5%',
+        primary: 'oklch(0.6 0.18 254)',
+        secondary: 'oklch(0.96 0.01 254)',
+        surface: 'oklch(1 0 0)',
+        foreground: 'oklch(0.16 0.02 254)',
       },
       dark: {
-        primary: '220 100% 70%',
-        secondary: '220 14% 4%',
-        surface: '222 84% 5%',
-        foreground: '210 40% 98%',
+        primary: 'oklch(0.72 0.18 254)',
+        secondary: 'oklch(0.22 0.02 254)',
+        surface: 'oklch(0.16 0.02 254)',
+        foreground: 'oklch(0.96 0.005 254)',
       }
     },
     // Override other theme properties...
@@ -245,7 +257,14 @@ const theme = {
   strategy: 'runtime', // 'runtime' (recommended) | 'buildtime'
 
   // Dark mode handling
-  darkModeStrategy: 'class', // 'class' | 'media' | 'auto'
+  darkModeStrategy: 'class', // 'class' | 'media'
+
+  // Class added to <html> when colorMode === 'dark' (default: 'dark')
+  darkClass: 'dark',
+
+  // Class added to <html> when colorMode === 'light' (default: 'light')
+  // Mirror of darkClass — used to force `color-scheme: only light`.
+  lightClass: 'light',
 
   // Persist the active preset name in the `maz-preset` cookie so the
   // user's last-used theme is restored on reload. Default: true.
@@ -253,6 +272,43 @@ const theme = {
 }
 ```
 
+### Global Component Defaults
+
+Set default prop values once for every component. Resolution priority, per prop: instance prop > `defaults[Component]` > `defaults.global` > library default. A global default never overrides a prop set on the instance.
+
+```ts
+const defaults = {
+  // Cross-cutting tokens applied to every component that exposes them
+  global: {
+    roundedSize: 'lg', // 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
+    size: 'sm', // 'mini' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+  },
+  // Per-component defaults, strongly typed as Partial<ComponentNameProps>, win over `global`
+  MazBtn: { roundedSize: 'full' },
+  MazCard: { bordered: false, elevation: true },
+  MazContainer: { bordered: false },
+}
+```
+
+See the [Global component defaults guide](/guide/global-defaults) for the full list of globalizable props.
+
+### Country Flags
+
+Source of the flags of `MazSelectCountry` and `MazInputPhoneNumber`. A `flag-src` set on a component wins.
+
+```ts
+export default defineNuxtConfig({
+  mazUi: {
+    // 'cdn' (default): flagcdn.com
+    // 'local': flags of @maz-ui/icons, one chunk per flag loaded when visible, no request to a third party
+    // '/flags/{code}.svg': your own files ({CODE} for uppercase codes)
+    flags: 'local',
+  },
+})
+```
+
+Nothing is added to your build unless `flags` is `'local'`. See [MazSelectCountry](/components/maz-select-country#flags-source) for the details (Content Security Policy, PWA precache).
+
 ## Theme Strategies Explained
 
 ### Runtime (Recommended)
@@ -329,6 +385,7 @@ const composables = {
   useReadingTime: true, // Reading time calculation
   useDisplayNames: true, // Display localized names
   useSwipe: true, // Swipe gestures
+  usePullToRefresh: true, // Pull to refresh gesture
 
   // 🔧 Advanced
   useFreezeValue: true, // Freeze reactive values
@@ -379,41 +436,39 @@ import { definePreset } from '@maz-ui/themes'
 
 export const customTheme = definePreset({
   base: 'maz-ui',
-  name: 'custom',
-  foundation: {
-    'base-font-size': '14px',
-    'font-family': `Manrope, sans-serif, system-ui, -apple-system`,
-    'space': '0.25rem',
-    'border-width': '0.0625rem',
-  },
-  scales: {
-    rounded: { md: '0.7rem' },
-  },
-  colors: {
-    light: {
-      primary: '350 100% 50%', // Custom pink
-      secondary: '350 14% 96%',
-      surface: '0 0% 100%',
-      foreground: '222 84% 5%',
-      muted: '210 40% 96%',
-      accent: '210 40% 90%',
-      destructive: '0 84% 60%',
-      border: '214 32% 91%',
-      input: '214 32% 91%',
-      ring: '350 100% 50%',
+  overrides: {
+    name: 'custom',
+    foundation: {
+      'base-font-size': '14px',
+      'font-family': `Manrope, sans-serif, system-ui, -apple-system`,
+      'space': '0.25rem',
+      'border-width': '0.0625rem',
+    },
+    scales: {
+      rounded: { md: '0.7rem' },
+    },
+    colors: {
+      light: {
+        primary: 'oklch(0.65 0.27 5)', // Custom pink
+        secondary: 'oklch(0.96 0.01 5)',
+        surface: 'oklch(1 0 0)',
+        foreground: 'oklch(0.16 0.02 254)',
+        muted: 'oklch(0.6 0.01 254)',
+        accent: 'oklch(0.7 0.05 5)',
+        destructive: 'oklch(0.6 0.22 27)',
+        divider: 'oklch(0.92 0.005 254)',
+      },
+      dark: {
+        primary: 'oklch(0.75 0.22 5)',
+        secondary: 'oklch(0.24 0.02 5)',
+        surface: 'oklch(0.16 0.02 254)',
+        foreground: 'oklch(0.96 0.005 254)',
+        muted: 'oklch(0.6 0.01 254)',
+        accent: 'oklch(0.3 0.04 5)',
+        destructive: 'oklch(0.55 0.2 27)',
+        divider: 'oklch(0.3 0.01 254)',
+      }
     },
-    dark: {
-      primary: '350 100% 70%',
-      secondary: '350 14% 4%',
-      surface: '222 84% 5%',
-      foreground: '210 40% 98%',
-      muted: '217 33% 17%',
-      accent: '217 33% 17%',
-      destructive: '0 62% 30%',
-      border: '217 33% 17%',
-      input: '217 33% 17%',
-      ring: '350 100% 70%',
-    }
   },
 })
 
@@ -429,7 +484,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