@maz-ui/eslint-config 5.0.0-beta.0 → 5.0.0-beta.11

package/README.md

@@ -1,15 +1,17 @@
 # @maz-ui/eslint-config
 
-Reusable ESLint configuration for JavaScript/TypeScript projects.
+Reusable ESLint configuration for JavaScript/TypeScript projects, built on top of [`@antfu/eslint-config`](https://github.com/antfu/eslint-config).
 
 ## Features
 
-- 🚀 **Based on @antfu/eslint-config** - Modern and performant configuration
-- 🛡️ **Strict TypeScript** - Full TypeScript support
-- 🎨 **Tailwind CSS** - Rules for Tailwind CSS (with Tailwind CSS plugin)
-- 🔍 **SonarJS** - Code quality with SonarJS (with SonarJS plugin)
-- ⚙️ **Configurable** - Flexible and extensible options
-- 📦 **Production ready** - Optimized for production environments
+- 🚀 **Based on @antfu/eslint-config** — modern, performant, flat-config first
+- 🛡️ **TypeScript-first** — strict mode, sensible defaults
+- 🎨 **Tailwind CSS v3 + v4** — via [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss) (compat ESLint 7→10, both Tailwind versions)
+- 🧩 **Custom `maz/` rules** — ships its own ESLint plugin namespaced `maz/*` (see [Custom rules](#custom-rules))
+- 🔍 **SonarJS** — code quality / cognitive complexity
+- ♿ **Vue accessibility** — opt-in `eslint-plugin-vuejs-accessibility`
+- 📐 **Formatters** — Prettier-style formatting via `eslint-plugin-format`
+- ⚙️ **Configurable** — pick presets, add per-file rules, custom ignore globs
 
 ## Installation
 
@@ -26,139 +28,203 @@ import { defineConfig } from '@maz-ui/eslint-config'
 export default defineConfig()
 ```
 
-## Custom configuration
+Vue / Nuxt are auto-detected from your `package.json`.
+
+## Configuration
 
 ```js
 // eslint.config.js
 import { defineConfig } from '@maz-ui/eslint-config'
 
 export default defineConfig({
-  // Environment (affects console rules)
-  env: 'production', // 'development' | 'production'
+  env: 'production', // 'development' | 'production' — affects no-console / no-debugger severity
 
-  // Enable/disable plugins
+  // Antfu options (forwarded as-is)
   typescript: true,
-  tailwindcss: true,
-  sonarjs: true,
   formatters: true,
+  unicorn: true,
+
+  // Maz-UI options
+  sonarjs: true,
+  vueAccessibility: false,
+  tailwindcss: 'recommended', // see "Tailwind support" below
 
-  // Files to ignore
+  // Extra ignore globs (merged with defaults)
   ignores: ['custom-dist/**'],
 
   // Custom rules
   rules: {
     'no-console': 'error',
-    'prefer-const': 'warn'
-  }
+  },
+
+  // 'silent' | 'default' | 'debug' | 'verbose' — see "Logging" below.
+  logLevel: 'default',
 })
 ```
 
-## Available options
-
-```typescript
-interface MazESLintOptions {
-  typescript?: boolean // TypeScript support (default: true)
-  tailwindcss?: boolean // Tailwind CSS rules (default: true)
-  sonarjs?: boolean // SonarJS rules (default: true)
-  formatters?: boolean // Formatters support (default: true)
-  env?: 'development' | 'production' // Environment (default: 'development')
-  ignores?: string[] // Files to ignore
-  rules?: Record<string, any> // Custom ESLint rules
-}
-```
+## Logging
 
-## Advanced usage
+The preset prints a titled box summarizing what it resolved (typescript, vue, tailwindcss preset, sonarjs, …). Powered by `@maz-ui/node`'s consola-based logger.
 
-### Selective rule imports
+| Value                       | What you see                                       |
+| --------------------------- | -------------------------------------------------- |
+| `'silent'`                  | Nothing.                                           |
+| `'default'` _(TTY default)_ | Titled box of resolved feature toggles.            |
+| `'debug'`                   | Above + each plugin / preset / overrides addition. |
+| `'verbose'`                 | Above + final block count and ignore-glob count.   |
 
-```js
-import { baseRules, sonarjsRules, tailwindcssRules } from '@maz-ui/eslint-config'
+The default is **`'default'` in interactive terminals, `'silent'` otherwise** (CI, pipes, JSON / SARIF formatters). This avoids polluting machine-readable ESLint output. Override by passing `logLevel` explicitly.
 
-export default [
-  {
-    rules: {
-      ...baseRules,
-      ...sonarjsRules,
-      // Your custom rules
-    }
-  }
-]
-```
+## Tailwind support
 
-### Example for Vue project
+Powered by [`eslint-plugin-better-tailwindcss`](https://github.com/schoero/eslint-plugin-better-tailwindcss) — compatible with ESLint 7→10 and Tailwind v3 + v4.
 
-```js
-// eslint.config.js
-import { defineConfig } from '@maz-ui/eslint-config'
+| Value                   | Behavior                                                                |
+| ----------------------- | ----------------------------------------------------------------------- |
+| `false` _(default)_     | Disabled.                                                               |
+| `true`                  | Same as `'recommended'` with default settings.                          |
+| `'recommended'`         | Stylistic + correctness rules.                                          |
+| `'stylistic'`           | Formatting rules only (class order, line wrapping, …).                  |
+| `'correctness'`         | Validation rules only (`no-unknown-classes`, `no-conflicting-classes`). |
+| `MazTailwindcssOptions` | Pick a preset and pass plugin settings.                                 |
 
-export default defineConfig({
-  env: 'production',
-  rules: {
-    'vue/custom-event-name-casing': ['error', 'kebab-case'],
-    'vue/no-undef-components': ['error', {
-      ignorePatterns: ['RouterView', 'RouterLink']
-    }]
-  }
+```js
+defineConfig({
+  tailwindcss: {
+    preset: 'recommended',
+    // Tailwind v4: path to the CSS that does `@import "tailwindcss" prefix(maz)`
+    entryPoint: 'src/main.css',
+    // Tailwind v3 instead:
+    // tailwindConfig: 'tailwind.config.ts',
+    detectComponentClasses: true,
+    // Custom `maz/tailwind-no-arbitrary-px` rule — see "Custom rules" below.
+    noArbitraryPx: true,
+  },
 })
 ```
 
-## Included rules
+> [!IMPORTANT]
+> The plugin's `no-unknown-classes` rule needs to know about your Tailwind setup (prefix, custom utilities, theme tokens). Without `entryPoint` (v4) or `tailwindConfig` (v3), it falls back to the default Tailwind config and will flood with false positives in projects that customize either. **Pass the path explicitly** if your Tailwind setup is non-standard.
 
-### Base (JavaScript/TypeScript)
+## Custom rules
 
-- Console management by environment
-- Code quality rules
-- Optimized TypeScript support
+This preset ships its own ESLint plugin under the `maz/*` namespace. Rules are organized by category — `maz/tailwind-*` for Tailwind-specific rules, ready for `maz/js-*` and others as they get added.
 
-### SonarJS
+### `maz/tailwind-no-arbitrary-px`
 
-- Limited cognitive complexity
-- Duplicate code detection
-- Security best practices
+Forbids `px` units inside Tailwind arbitrary value classes (`w-[16px]`, `m-[-16px]`, `[gap:24px]`, …) and **autofixes** them to `rem` (or `em`) using the configured root font-size. Whitespace inside brackets (e.g. `[up to 100px]`) is left alone so plain prose is never rewritten.
 
-### Tailwind CSS
+> [!NOTE]
+> The rule and the `maz` plugin are only registered when `tailwindcss` is enabled (any value other than `false`). With `tailwindcss: false` _(default)_ neither the plugin nor the rule appear in the final flat-config. To use the rule in a project that doesn't opt into the full Tailwind preset, register it manually (see [Use the plugin directly](#use-the-plugin-directly)).
 
-- Consistent class ordering
-- Contradictory class detection
-- Valid Tailwind syntax
+When `tailwindcss` is on, the rule is enabled with defaults. You can tune it either way:
 
-## Compatibility
+**Standard ESLint override** _(idiomatic, max control)_
 
-- **ESLint** ^9.0.0
-- **Node.js** >=18.0.0
-- **TypeScript** ^5.0.0
+```js
+defineConfig({
+  tailwindcss: 'recommended',
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 10, unit: 'em' }],
+  },
+})
+```
 
-## Usage examples
+User `rules` overrides are applied in a _trailing_ block, so they win over the rule's defaults wired in by `tailwindcssConfigs`.
 
-### Simple JavaScript project
+**Ergonomic shortcut** _(set the defaults via `tailwindcss.noArbitraryPx`)_
 
 ```js
-export default defineConfig({
-  typescript: false,
-  tailwindcss: false
+defineConfig({
+  tailwindcss: {
+    preset: 'recommended',
+    noArbitraryPx: {
+      baseFontSize: 16, // default — convert px / 16 → rem
+      unit: 'rem', // default — target unit ('rem' | 'em')
+      severity: 'error', // default — 'off' | 'warn' | 'error'
+    },
+  },
 })
 ```
 
-### Project with Tailwind
+| `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 (last block applied).
+
+Examples after autofix (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)]`   |
+
+### 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`:
 
 ```js
-export default defineConfig({
-  tailwindcss: true,
+import { mazPlugin } from '@maz-ui/eslint-config'
+
+export default [{
+  files: ['**/*.{ts,tsx,vue}'],
+  plugins: { maz: mazPlugin },
   rules: {
-    'tailwindcss/classnames-order': 'error'
-  }
-})
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 16 }],
+  },
+}]
 ```
 
-### Production project
+## Advanced
+
+### Compose your own config
 
 ```js
-export default defineConfig({
-  env: 'production',
-  sonarjs: true,
+import {
+  baseRules,
+  mazPlugin,
+  sonarjsRules,
+  tailwindcssConfigs,
+  vueRules,
+} from '@maz-ui/eslint-config'
+
+export default [
+  {
+    plugins: { maz: mazPlugin },
+    rules: {
+      ...baseRules(true), // production = true
+      ...sonarjsRules,
+      ...vueRules,
+      'maz/tailwind-no-arbitrary-px': 'error',
+    },
+  },
+  ...tailwindcssConfigs('stylistic', {
+    entryPoint: 'src/main.css',
+    noArbitraryPx: { unit: 'em' },
+  }),
+]
+```
+
+### Vue project
+
+```js
+defineConfig({
+  vue: true, // auto-detected if `vue` / `nuxt` is in deps
+  tailwindcss: 'recommended',
   rules: {
-    'no-console': 'error',
-    'no-debugger': 'error'
-  }
+    'vue/custom-event-name-casing': ['error', 'kebab-case'],
+  },
 })
 ```
+
+## Compatibility
+
+- **ESLint** `^9.0.0 || ^10.0.0`
+- **Node.js** `>=20.19.0`

package/dist/index.d.mts

@@ -1,13 +1,102 @@
 import { antfu, OptionsConfig, Rules, TypedFlatConfigItem } from '@antfu/eslint-config';
-import { Linter } from 'eslint';
+import { Linter, ESLint, Rule } from 'eslint';
+
+/**
+ * Mirror of `@maz-ui/node`'s LogLevel — kept inline here to avoid making this
+ * preset depend on `@maz-ui/node`, which would create a build cycle (the
+ * `eslint.config.ts` of `@maz-ui/node` imports `@maz-ui/eslint-config`, which
+ * itself would depend on `@maz-ui/node` for the same logger). Direct usage of
+ * `consola` keeps the dependency graph acyclic.
+ */
+type LogLevel = 'silent' | 'error' | 'warning' | 'normal' | 'default' | 'debug' | 'trace' | 'verbose';
 
 type MazESLintUserConfig = TypedFlatConfigItem | TypedFlatConfigItem[] | Linter.Config | Linter.Config[];
+type TailwindcssPreset = 'recommended' | 'stylistic' | 'correctness';
+/**
+ * Settings forwarded to `eslint-plugin-better-tailwindcss` under
+ * `settings['better-tailwindcss']`. See the plugin docs for the canonical
+ * meaning of each field.
+ */
+interface MazTailwindcssOptions {
+    /**
+     * Which preset to load. Each one comes in `*-warn` and `*-error` flavors
+     * (defaults match the plugin's defaults: stylistic→warn, correctness→error).
+     *
+     * @default 'recommended'
+     */
+    preset?: TailwindcssPreset;
+    /**
+     * Tailwind v4: path to the CSS entry file (the one that does
+     * `@import "tailwindcss"`, possibly with `prefix(...)`). Required for the
+     * plugin to know about your prefix and `@theme` tokens.
+     */
+    entryPoint?: string;
+    /**
+     * Tailwind v3: path to `tailwind.config.{js,ts,cjs,mjs}`. Use `entryPoint`
+     * for v4 instead.
+     */
+    tailwindConfig?: string;
+    /**
+     * Tailwind v4: enable detection of custom component classes (`@layer
+     * components { … }`) so they are not reported as unknown.
+     *
+     * @default false
+     */
+    detectComponentClasses?: boolean;
+    /**
+     * Working directory used to resolve `tailwindcss` and the config files
+     * above. Useful in monorepos when ESLint runs from the repo root.
+     */
+    cwd?: string;
+    /**
+     * Path to a `tsconfig.json` used to resolve `paths` aliases inside the
+     * Tailwind config.
+     */
+    tsconfig?: string;
+    /**
+     * Configure the `maz/tailwind-no-arbitrary-px` rule (forbids `px`
+     * values inside Tailwind arbitrary value classes such as `w-[16px]`).
+     *
+     * - `false`: disable the rule.
+     * - `true` *(default)*: enable with defaults (`baseFontSize: 16`,
+     *   `unit: 'rem'`).
+     * - Object: enable with custom options.
+     */
+    noArbitraryPx?: boolean | {
+        /**
+         * Root font size, in pixels, used to convert `Npx` to `rem`/`em`.
+         *
+         * @default 16
+         */
+        baseFontSize?: number;
+        /**
+         * Output unit for the autofix.
+         *
+         * @default 'rem'
+         */
+        unit?: 'rem' | 'em';
+        /**
+         * ESLint severity for the rule.
+         *
+         * @default 'error'
+         */
+        severity?: 'off' | 'warn' | 'error';
+    };
+}
 interface MazESLintOptions extends OptionsConfig {
     /**
-     * Enable Tailwind CSS support
+     * Tailwind CSS support — wires `eslint-plugin-better-tailwindcss`.
+     *
+     * - `false` *(default)*: disabled.
+     * - `true`: load the `'recommended'` preset with default settings.
+     * - `'recommended' | 'stylistic' | 'correctness'`: pick a preset, default
+     *   settings.
+     * - `MazTailwindcssOptions`: pick a preset and pass settings (e.g.
+     *   `entryPoint` so the plugin learns your v4 prefix).
+     *
      * @default false
      */
-    tailwindcss?: boolean;
+    tailwindcss?: boolean | TailwindcssPreset | MazTailwindcssOptions;
     /**
      * Enable SonarJS rules for code quality
      * @default true
@@ -32,6 +121,19 @@ interface MazESLintOptions extends OptionsConfig {
      * Additional rules to merge
      */
     rules?: Partial<Rules>;
+    /**
+     * Verbosity of the logs emitted while resolving the config. Defaults to
+     * `'default'` so the resolved-configuration box is shown when the preset
+     * loads. Set to `'silent'` to hide it, or `'debug'` / `'verbose'` to dig
+     * deeper.
+     *
+     * - `'silent'`: nothing is printed.
+     * - `'default'` *(default)*: a titled box summarizing the resolved feature
+     *   toggles.
+     * - `'debug'`: also logs each plugin / preset / overrides addition.
+     * - `'verbose'`: also logs the final shape (config block count, etc.).
+     */
+    logLevel?: LogLevel;
 }
 type MazESLintConfig = ReturnType<typeof antfu>;
 
@@ -68,24 +170,52 @@ declare const sonarjsTestRules: {
 };
 
 /**
- * Tailwind CSS ESLint rules configuration.
- *
- * These rules only activate when the user opts in via
- * `defineMazEslintConfig({ tailwindcss: true })` AND is on ESLint 9 +
- * Tailwind v3. The plugin itself does not yet support ESLint 10+ or
- * Tailwind v4 (upstream — uses the removed context.getSourceCode API).
+ * Files where Tailwind classes commonly live. Exposed for users who want to
+ * compose their own config.
  */
-declare const tailwindcssRules: {
-    readonly 'tailwindcss/no-custom-classname': "off";
-    readonly 'tailwindcss/classnames-order': "warn";
-    readonly 'tailwindcss/no-contradicting-classname': "error";
-    readonly 'tailwindcss/enforces-negative-arbitrary-values': "error";
-    readonly 'tailwindcss/enforces-shorthand': "warn";
-};
+declare const TAILWINDCSS_DEFAULT_FILES: string[];
+/**
+ * Build the flat-config block(s) that wire up
+ * `eslint-plugin-better-tailwindcss` AND the custom `maz/tailwind-*`
+ * rules shipped by this package. The plugin already ships preset
+ * objects with `plugins` + `rules`; we spread them and add `files` plus
+ * `settings['better-tailwindcss']` so the user's options reach the
+ * plugin.
+ */
+declare function tailwindcssConfigs(preset: TailwindcssPreset, settings: MazTailwindcssOptions): Linter.Config[];
 
 declare const vueRules: {
     'vue/custom-event-name-casing': ["error", "kebab-case"];
 };
+declare const vueSfcOnlyRules: {
+    'no-useless-assignment': "off";
+};
+
+/**
+ * The `maz` ESLint plugin bundling all custom rules shipped by
+ * `@maz-ui/eslint-config`. Rules are namespaced by category:
+ *
+ *   - `maz/tailwind-*` — Tailwind-specific rules
+ *   - `maz/js-*` — general JS/TS rules (when added)
+ *   - …
+ *
+ * The plugin is auto-wired by the relevant config block in
+ * `src/configs/*.ts`, but it is also exported so users can compose
+ * their own flat-config setup.
+ */
+declare const mazPlugin: ESLint.Plugin;
+
+/**
+ * Registry of all custom rules shipped by `@maz-ui/eslint-config`.
+ *
+ * Keys here are the final rule names exposed by the `maz` plugin, so a
+ * file in `src/rules/tailwind/no-arbitrary-px.ts` becomes
+ * `maz/tailwind-no-arbitrary-px` when wired through the plugin.
+ *
+ * Add new rules by dropping a file in the matching category folder
+ * (`tailwind/`, `js/`, …) and registering it below.
+ */
+declare const rules: Record<string, Rule.RuleModule>;
 
 /**
  * Create ESLint configuration for Maz-UI and JavaScript/TypeScript projects
@@ -107,5 +237,5 @@ declare const vueRules: {
  */
 declare function defineConfig(options?: MazESLintOptions, ...userConfigs: MazESLintUserConfig[]): MazESLintConfig;
 
-export { baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssRules, vueRules };
-export type { MazESLintConfig, MazESLintOptions };
+export { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, mazPlugin, rules as mazRules, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };
+export type { MazESLintConfig, MazESLintOptions, MazTailwindcssOptions, TailwindcssPreset };

package/dist/index.d.ts

@@ -1,13 +1,102 @@
 import { antfu, OptionsConfig, Rules, TypedFlatConfigItem } from '@antfu/eslint-config';
-import { Linter } from 'eslint';
+import { Linter, ESLint, Rule } from 'eslint';
+
+/**
+ * Mirror of `@maz-ui/node`'s LogLevel — kept inline here to avoid making this
+ * preset depend on `@maz-ui/node`, which would create a build cycle (the
+ * `eslint.config.ts` of `@maz-ui/node` imports `@maz-ui/eslint-config`, which
+ * itself would depend on `@maz-ui/node` for the same logger). Direct usage of
+ * `consola` keeps the dependency graph acyclic.
+ */
+type LogLevel = 'silent' | 'error' | 'warning' | 'normal' | 'default' | 'debug' | 'trace' | 'verbose';
 
 type MazESLintUserConfig = TypedFlatConfigItem | TypedFlatConfigItem[] | Linter.Config | Linter.Config[];
+type TailwindcssPreset = 'recommended' | 'stylistic' | 'correctness';
+/**
+ * Settings forwarded to `eslint-plugin-better-tailwindcss` under
+ * `settings['better-tailwindcss']`. See the plugin docs for the canonical
+ * meaning of each field.
+ */
+interface MazTailwindcssOptions {
+    /**
+     * Which preset to load. Each one comes in `*-warn` and `*-error` flavors
+     * (defaults match the plugin's defaults: stylistic→warn, correctness→error).
+     *
+     * @default 'recommended'
+     */
+    preset?: TailwindcssPreset;
+    /**
+     * Tailwind v4: path to the CSS entry file (the one that does
+     * `@import "tailwindcss"`, possibly with `prefix(...)`). Required for the
+     * plugin to know about your prefix and `@theme` tokens.
+     */
+    entryPoint?: string;
+    /**
+     * Tailwind v3: path to `tailwind.config.{js,ts,cjs,mjs}`. Use `entryPoint`
+     * for v4 instead.
+     */
+    tailwindConfig?: string;
+    /**
+     * Tailwind v4: enable detection of custom component classes (`@layer
+     * components { … }`) so they are not reported as unknown.
+     *
+     * @default false
+     */
+    detectComponentClasses?: boolean;
+    /**
+     * Working directory used to resolve `tailwindcss` and the config files
+     * above. Useful in monorepos when ESLint runs from the repo root.
+     */
+    cwd?: string;
+    /**
+     * Path to a `tsconfig.json` used to resolve `paths` aliases inside the
+     * Tailwind config.
+     */
+    tsconfig?: string;
+    /**
+     * Configure the `maz/tailwind-no-arbitrary-px` rule (forbids `px`
+     * values inside Tailwind arbitrary value classes such as `w-[16px]`).
+     *
+     * - `false`: disable the rule.
+     * - `true` *(default)*: enable with defaults (`baseFontSize: 16`,
+     *   `unit: 'rem'`).
+     * - Object: enable with custom options.
+     */
+    noArbitraryPx?: boolean | {
+        /**
+         * Root font size, in pixels, used to convert `Npx` to `rem`/`em`.
+         *
+         * @default 16
+         */
+        baseFontSize?: number;
+        /**
+         * Output unit for the autofix.
+         *
+         * @default 'rem'
+         */
+        unit?: 'rem' | 'em';
+        /**
+         * ESLint severity for the rule.
+         *
+         * @default 'error'
+         */
+        severity?: 'off' | 'warn' | 'error';
+    };
+}
 interface MazESLintOptions extends OptionsConfig {
     /**
-     * Enable Tailwind CSS support
+     * Tailwind CSS support — wires `eslint-plugin-better-tailwindcss`.
+     *
+     * - `false` *(default)*: disabled.
+     * - `true`: load the `'recommended'` preset with default settings.
+     * - `'recommended' | 'stylistic' | 'correctness'`: pick a preset, default
+     *   settings.
+     * - `MazTailwindcssOptions`: pick a preset and pass settings (e.g.
+     *   `entryPoint` so the plugin learns your v4 prefix).
+     *
      * @default false
      */
-    tailwindcss?: boolean;
+    tailwindcss?: boolean | TailwindcssPreset | MazTailwindcssOptions;
     /**
      * Enable SonarJS rules for code quality
      * @default true
@@ -32,6 +121,19 @@ interface MazESLintOptions extends OptionsConfig {
      * Additional rules to merge
      */
     rules?: Partial<Rules>;
+    /**
+     * Verbosity of the logs emitted while resolving the config. Defaults to
+     * `'default'` so the resolved-configuration box is shown when the preset
+     * loads. Set to `'silent'` to hide it, or `'debug'` / `'verbose'` to dig
+     * deeper.
+     *
+     * - `'silent'`: nothing is printed.
+     * - `'default'` *(default)*: a titled box summarizing the resolved feature
+     *   toggles.
+     * - `'debug'`: also logs each plugin / preset / overrides addition.
+     * - `'verbose'`: also logs the final shape (config block count, etc.).
+     */
+    logLevel?: LogLevel;
 }
 type MazESLintConfig = ReturnType<typeof antfu>;
 
@@ -68,24 +170,52 @@ declare const sonarjsTestRules: {
 };
 
 /**
- * Tailwind CSS ESLint rules configuration.
- *
- * These rules only activate when the user opts in via
- * `defineMazEslintConfig({ tailwindcss: true })` AND is on ESLint 9 +
- * Tailwind v3. The plugin itself does not yet support ESLint 10+ or
- * Tailwind v4 (upstream — uses the removed context.getSourceCode API).
+ * Files where Tailwind classes commonly live. Exposed for users who want to
+ * compose their own config.
  */
-declare const tailwindcssRules: {
-    readonly 'tailwindcss/no-custom-classname': "off";
-    readonly 'tailwindcss/classnames-order': "warn";
-    readonly 'tailwindcss/no-contradicting-classname': "error";
-    readonly 'tailwindcss/enforces-negative-arbitrary-values': "error";
-    readonly 'tailwindcss/enforces-shorthand': "warn";
-};
+declare const TAILWINDCSS_DEFAULT_FILES: string[];
+/**
+ * Build the flat-config block(s) that wire up
+ * `eslint-plugin-better-tailwindcss` AND the custom `maz/tailwind-*`
+ * rules shipped by this package. The plugin already ships preset
+ * objects with `plugins` + `rules`; we spread them and add `files` plus
+ * `settings['better-tailwindcss']` so the user's options reach the
+ * plugin.
+ */
+declare function tailwindcssConfigs(preset: TailwindcssPreset, settings: MazTailwindcssOptions): Linter.Config[];
 
 declare const vueRules: {
     'vue/custom-event-name-casing': ["error", "kebab-case"];
 };
+declare const vueSfcOnlyRules: {
+    'no-useless-assignment': "off";
+};
+
+/**
+ * The `maz` ESLint plugin bundling all custom rules shipped by
+ * `@maz-ui/eslint-config`. Rules are namespaced by category:
+ *
+ *   - `maz/tailwind-*` — Tailwind-specific rules
+ *   - `maz/js-*` — general JS/TS rules (when added)
+ *   - …
+ *
+ * The plugin is auto-wired by the relevant config block in
+ * `src/configs/*.ts`, but it is also exported so users can compose
+ * their own flat-config setup.
+ */
+declare const mazPlugin: ESLint.Plugin;
+
+/**
+ * Registry of all custom rules shipped by `@maz-ui/eslint-config`.
+ *
+ * Keys here are the final rule names exposed by the `maz` plugin, so a
+ * file in `src/rules/tailwind/no-arbitrary-px.ts` becomes
+ * `maz/tailwind-no-arbitrary-px` when wired through the plugin.
+ *
+ * Add new rules by dropping a file in the matching category folder
+ * (`tailwind/`, `js/`, …) and registering it below.
+ */
+declare const rules: Record<string, Rule.RuleModule>;
 
 /**
  * Create ESLint configuration for Maz-UI and JavaScript/TypeScript projects
@@ -107,5 +237,5 @@ declare const vueRules: {
  */
 declare function defineConfig(options?: MazESLintOptions, ...userConfigs: MazESLintUserConfig[]): MazESLintConfig;
 
-export { baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssRules, vueRules };
-export type { MazESLintConfig, MazESLintOptions };
+export { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, mazPlugin, rules as mazRules, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };
+export type { MazESLintConfig, MazESLintOptions, MazTailwindcssOptions, TailwindcssPreset };

package/dist/index.mjs

@@ -1,9 +1,10 @@
 import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import antfu from '@antfu/eslint-config';
 import { configs } from 'eslint-plugin-sonarjs';
 import vueA11y from 'eslint-plugin-vuejs-accessibility';
+import { createConsola } from 'consola';
+import betterTailwindcss from 'eslint-plugin-better-tailwindcss';
 
 function baseRules(isProduction) {
   return {
@@ -71,6 +72,29 @@ const GLOBAL_IGNORES = [
   "**/components.d.ts"
 ];
 
+const LEVELS = {
+  silent: Number.NEGATIVE_INFINITY,
+  error: 0,
+  warning: 1,
+  normal: 2,
+  default: 3,
+  debug: 4,
+  trace: 5,
+  verbose: Number.POSITIVE_INFINITY
+};
+function createLogger() {
+  const consola = createConsola();
+  return {
+    setLevel: (level) => {
+      consola.level = LEVELS[level];
+    },
+    info: (msg) => consola.info(msg),
+    debug: (msg) => consola.debug(msg),
+    verbose: (msg) => consola.verbose(msg),
+    box: (opts) => consola.box(opts)
+  };
+}
+
 const markdown = {
   files: ["**/*.md/**"],
   rules: {
@@ -103,18 +127,167 @@ const sonarjsTestRules = {
   "sonarjs/no-duplicate-string": "off"
 };
 
-const tailwindcssRules = {
-  // Allow custom class names (useful for component libraries)
-  "tailwindcss/no-custom-classname": "off",
-  // Enforce consistent class ordering
-  "tailwindcss/classnames-order": "warn",
-  // Prevent contradicting classes
-  "tailwindcss/no-contradicting-classname": "error",
-  // Enforce valid Tailwind syntax
-  "tailwindcss/enforces-negative-arbitrary-values": "error",
-  "tailwindcss/enforces-shorthand": "warn"
+const DEFAULT_BASE_FONT_SIZE = 16;
+const DEFAULT_UNIT = "rem";
+const ARBITRARY_BRACKET = /\[([^\s\]]+)\]/g;
+const HAS_PX_VALUE = /\dpx/i;
+const PX_VALUE = /(-?(?:\d+(?:\.\d+)?|\.\d+))px/gi;
+function convertPx(pxStr, base, unit) {
+  const px = Number.parseFloat(pxStr);
+  const value = px / base;
+  const formatted = Number.parseFloat(value.toFixed(6)).toString();
+  return `${formatted}${unit}`;
+}
+function findReplacements(input, base, unit) {
+  const out = [];
+  for (const match of input.matchAll(ARBITRARY_BRACKET)) {
+    const full = match[0];
+    const inner = match[1];
+    if (!HAS_PX_VALUE.test(inner))
+      continue;
+    const fixedInner = inner.replace(PX_VALUE, (_m, num) => convertPx(num, base, unit));
+    out.push({
+      original: full,
+      fixed: `[${fixedInner}]`,
+      index: match.index,
+      length: full.length
+    });
+  }
+  return out;
+}
+function applyReplacements(input, replacements) {
+  let output = "";
+  let cursor = 0;
+  for (const r of replacements) {
+    output += input.slice(cursor, r.index) + r.fixed;
+    cursor = r.index + r.length;
+  }
+  output += input.slice(cursor);
+  return output;
+}
+const rule = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "Disallow `px` units inside Tailwind arbitrary value classes; prefer `rem` (or `em`).",
+      recommended: false
+    },
+    fixable: "code",
+    schema: [
+      {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          baseFontSize: { type: "number", minimum: 1 },
+          unit: { type: "string", enum: ["rem", "em"] }
+        }
+      }
+    ],
+    messages: {
+      preferRelativeUnit: "Tailwind class uses px; replace `{{original}}` with `{{fixed}}`."
+    }
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const base = options.baseFontSize ?? DEFAULT_BASE_FONT_SIZE;
+    const unit = options.unit ?? DEFAULT_UNIT;
+    const { sourceCode } = context;
+    function check(node) {
+      const raw = sourceCode.getText(node);
+      const replacements = findReplacements(raw, base, unit);
+      if (replacements.length === 0)
+        return;
+      const fixedRaw = applyReplacements(raw, replacements);
+      for (const r of replacements) {
+        context.report({
+          node,
+          messageId: "preferRelativeUnit",
+          data: { original: r.original, fixed: r.fixed },
+          fix: (fixer) => fixer.replaceText(node, fixedRaw)
+        });
+      }
+    }
+    const jsVisitor = {
+      Literal(node) {
+        if (typeof node.value !== "string")
+          return;
+        check(node);
+      },
+      TemplateElement(node) {
+        check(node);
+      }
+    };
+    const parserServices = context.sourceCode.parserServices;
+    if (parserServices.defineTemplateBodyVisitor) {
+      return parserServices.defineTemplateBodyVisitor(
+        { VLiteral: (node) => check(node) },
+        jsVisitor
+      );
+    }
+    return jsVisitor;
+  }
+};
+
+const rules = {
+  "tailwind-no-arbitrary-px": rule
+};
+
+const mazPlugin = {
+  meta: {
+    name: "maz"
+  },
+  rules
 };
 
+const TAILWINDCSS_FILES = ["**/*.{js,jsx,cjs,mjs,ts,mts,cts,tsx,vue,html,svelte,astro,astrojs,css,scss}"];
+const TAILWINDCSS_DEFAULT_FILES = TAILWINDCSS_FILES;
+function resolveNoArbitraryPx(setting) {
+  if (setting === false)
+    return { severity: "off", options: { baseFontSize: 16, unit: "rem" } };
+  if (setting === void 0 || setting === true) {
+    return { severity: "error", options: { baseFontSize: 16, unit: "rem" } };
+  }
+  return {
+    severity: setting.severity ?? "error",
+    options: {
+      baseFontSize: setting.baseFontSize ?? 16,
+      unit: setting.unit ?? "rem"
+    }
+  };
+}
+function tailwindcssConfigs(preset, settings) {
+  const presetConfig = betterTailwindcss.configs[preset];
+  const tailwindSettings = {};
+  if (settings.entryPoint)
+    tailwindSettings.entryPoint = settings.entryPoint;
+  if (settings.tailwindConfig)
+    tailwindSettings.tailwindConfig = settings.tailwindConfig;
+  if (settings.detectComponentClasses !== void 0)
+    tailwindSettings.detectComponentClasses = settings.detectComponentClasses;
+  if (settings.cwd)
+    tailwindSettings.cwd = settings.cwd;
+  if (settings.tsconfig)
+    tailwindSettings.tsconfig = settings.tsconfig;
+  const noArbitraryPx = resolveNoArbitraryPx(settings.noArbitraryPx);
+  return [{
+    ...presetConfig,
+    files: TAILWINDCSS_FILES,
+    plugins: {
+      ...presetConfig.plugins,
+      maz: mazPlugin
+    },
+    settings: {
+      "better-tailwindcss": tailwindSettings
+    },
+    rules: {
+      ...presetConfig.rules,
+      "better-tailwindcss/no-unknown-classes": "off",
+      "better-tailwindcss/enforce-consistent-line-wrapping": "off",
+      "maz/tailwind-no-arbitrary-px": [noArbitraryPx.severity, noArbitraryPx.options]
+    }
+  }];
+}
+
 const testRules = {
   "max-nested-callbacks": "off"
 };
@@ -122,7 +295,11 @@ const testRules = {
 const vueRules = {
   "vue/custom-event-name-casing": ["error", "kebab-case"]
 };
+const vueSfcOnlyRules = {
+  "no-useless-assignment": "off"
+};
 
+const TAG = "[@maz-ui/eslint-config]";
 const defaultOptions = {
   formatters: true,
   typescript: true,
@@ -139,39 +316,93 @@ function getPackageJson() {
     return void 0;
   }
 }
-function getEslintMajorVersion() {
-  try {
-    const _require = createRequire(import.meta.url);
-    const eslintPkg = _require("eslint/package.json");
-    return Number(eslintPkg.version.split(".")[0]);
-  } catch {
-    return 0;
-  }
+function hasDependency(pkg, ...names) {
+  if (!pkg)
+    return false;
+  const buckets = [pkg.dependencies, pkg.devDependencies, pkg.peerDependencies];
+  return names.some((name) => buckets.some((bucket) => bucket && name in bucket));
 }
-function tryLoadTailwindPlugin() {
-  try {
-    const _require = createRequire(import.meta.url);
-    const mod = _require("eslint-plugin-tailwindcss");
-    return mod?.default ?? mod;
-  } catch {
-    return null;
-  }
+function resolveVue(option) {
+  if (option === true)
+    return { value: true, source: "explicit" };
+  if (option === false)
+    return { value: false, source: "explicit" };
+  return { value: hasDependency(getPackageJson(), "vue", "nuxt"), source: "auto-detected" };
+}
+function resolveTailwindcss(option) {
+  if (option === void 0)
+    return { value: false, source: "default" };
+  if (option === false)
+    return { value: false, source: "explicit" };
+  if (option === true)
+    return { value: { preset: "recommended", settings: {} }, source: "explicit" };
+  if (typeof option === "string")
+    return { value: { preset: option, settings: {} }, source: "explicit" };
+  return { value: { preset: option.preset ?? "recommended", settings: option }, source: "explicit" };
 }
-function isVueOrNuxtProject() {
-  const packageJson = getPackageJson();
-  return packageJson?.dependencies?.vue || packageJson?.devDependencies?.vue || packageJson?.peerDependencies?.vue || packageJson?.dependencies?.nuxt || packageJson?.devDependencies?.nuxt || packageJson?.peerDependencies?.nuxt;
+function resolveOptions(opts, env) {
+  const vue = resolveVue(opts.vue);
+  const tailwind = resolveTailwindcss(opts.tailwindcss);
+  return {
+    typescript: opts.typescript !== false,
+    formatters: opts.formatters !== false,
+    unicorn: opts.unicorn !== false,
+    sonarjs: opts.sonarjs !== false,
+    vue: vue.value,
+    vueSource: vue.source,
+    vueAccessibility: opts.vueAccessibility === true,
+    tailwindcss: tailwind.value,
+    tailwindcssSource: tailwind.source,
+    env
+  };
+}
+function formatSourceTag(source) {
+  if (source === "auto-detected")
+    return " (auto-detected)";
+  if (source === "default")
+    return " (default)";
+  return "";
+}
+function formatResolutionBox(r) {
+  const tailwindLabel = r.tailwindcss === false ? "off" : r.tailwindcss.preset;
+  const rows = [
+    ["typescript", String(r.typescript)],
+    ["vue", `${r.vue}${formatSourceTag(r.vueSource)}`],
+    ["vueAccessibility", String(r.vueAccessibility)],
+    ["sonarjs", String(r.sonarjs)],
+    ["tailwindcss", `${tailwindLabel}${formatSourceTag(r.tailwindcssSource)}`],
+    ["formatters", String(r.formatters)],
+    ["unicorn", String(r.unicorn)],
+    ["env", r.env]
+  ];
+  const labelWidth = Math.max(...rows.map(([k]) => k.length));
+  return rows.map(([k, v]) => `${k.padEnd(labelWidth)}  ${v}`).join("\n");
 }
 function defineConfig(options = {}, ...userConfigs) {
+  const log = createLogger();
+  const defaultLogLevel = process.stdout.isTTY ? "default" : "silent";
+  log.setLevel(options.logLevel ?? defaultLogLevel);
   const opts = { ...defaultOptions, ...options, ignores: [...GLOBAL_IGNORES, ...options.ignores || []] };
   const env = opts.env || process.env.NODE_ENV || "production";
+  const resolved = resolveOptions(opts, env);
+  log.box({
+    title: "@maz-ui/eslint-config",
+    message: formatResolutionBox(resolved),
+    style: { borderColor: "cyan", padding: 1 }
+  });
   const additionalConfigs = [];
-  if (opts.vue || isVueOrNuxtProject()) {
+  if (resolved.vue) {
     additionalConfigs.push({
       files: ["**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"],
       rules: vueRules
     });
+    additionalConfigs.push({
+      files: ["**/*.vue"],
+      rules: vueSfcOnlyRules
+    });
+    log.debug(`${TAG} Vue: applied vueRules to JS/TS/Vue files + SFC-only overrides to *.vue`);
   }
-  if (opts.sonarjs) {
+  if (resolved.sonarjs) {
     const sonarjsFiles = ["**/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}"];
     additionalConfigs.push({
       ...configs.recommended,
@@ -185,8 +416,9 @@ function defineConfig(options = {}, ...userConfigs) {
       files: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.js", "**/*.test.js"],
       rules: sonarjsTestRules
     });
+    log.debug(`${TAG} SonarJS: applied recommended preset + ${Object.keys(sonarjsRules).length} extra rules + test-file relaxations`);
   }
-  if (opts.vueAccessibility) {
+  if (resolved.vueAccessibility) {
     const vueA11yConfigs = vueA11y.configs["flat/recommended"];
     const configsArray = Array.isArray(vueA11yConfigs) ? vueA11yConfigs : [vueA11yConfigs];
     const fixedConfigs = configsArray.map((config) => {
@@ -207,39 +439,35 @@ function defineConfig(options = {}, ...userConfigs) {
       return config;
     });
     additionalConfigs.push(...fixedConfigs);
+    log.debug(`${TAG} Vue a11y: applied ${fixedConfigs.length} flat-config block(s) from eslint-plugin-vuejs-accessibility`);
   }
-  if (opts.tailwindcss) {
-    const eslintMajor = getEslintMajorVersion();
-    if (eslintMajor >= 10) {
-      console.warn("[maz-eslint-config] eslint-plugin-tailwindcss is not compatible with ESLint 10+ (uses removed context.getSourceCode API). Tailwind CSS rules are disabled.");
-    } else {
-      const tailwindPlugin = tryLoadTailwindPlugin();
-      if (!tailwindPlugin) {
-        console.warn("[maz-eslint-config] opts.tailwindcss is true but eslint-plugin-tailwindcss is not installed. Add it to your devDependencies to enable the Tailwind CSS lint rules.");
-      } else {
-        const tailwindConfigs = tailwindPlugin.configs?.["flat/recommended"];
-        if (Array.isArray(tailwindConfigs)) {
-          additionalConfigs.push(...tailwindConfigs);
-        }
-        additionalConfigs.push({ rules: tailwindcssRules });
-      }
-    }
+  if (resolved.tailwindcss) {
+    const blocks = tailwindcssConfigs(resolved.tailwindcss.preset, resolved.tailwindcss.settings);
+    additionalConfigs.push(...blocks);
+    const settingKeys = Object.keys(resolved.tailwindcss.settings).filter((k) => k !== "preset");
+    const settingsHint = settingKeys.length > 0 ? ` with settings (${settingKeys.join(", ")})` : "";
+    log.debug(`${TAG} Tailwind: loaded "${resolved.tailwindcss.preset}" preset${settingsHint}`);
   }
   additionalConfigs.push({
     files: ["**/*.spec.ts", "**/*.test.ts", "**/*.spec.js", "**/*.test.js"],
     rules: testRules
   });
+  log.debug(`${TAG} Tests: relaxed rules applied to *.spec.{ts,js} / *.test.{ts,js}`);
+  if (options.rules && Object.keys(options.rules).length > 0)
+    log.debug(`${TAG} User: merged ${Object.keys(options.rules).length} rule override(s)`);
+  if (userConfigs.length > 0)
+    log.debug(`${TAG} User: appended ${userConfigs.length} flat-config argument(s)`);
+  log.verbose(`${TAG} Final config block count: ${additionalConfigs.length + userConfigs.length + 1} (additional: ${additionalConfigs.length}, user: ${userConfigs.length}, +markdown)`);
+  log.verbose(`${TAG} Ignore globs: ${opts.ignores.length}`);
+  const userRulesBlock = opts.rules && Object.keys(opts.rules).length > 0 ? { rules: opts.rules } : void 0;
   return antfu({
     formatters: opts.formatters,
     ...opts,
-    rules: {
-      ...baseRules(env === "production"),
-      ...opts.rules
-    },
+    rules: baseRules(env === "production"),
     ignores: (() => {
       return opts.ignores;
     })
-  }, ...additionalConfigs, ...userConfigs, markdown);
+  }, ...additionalConfigs, ...userConfigs, ...userRulesBlock ? [userRulesBlock] : [], markdown);
 }
 
-export { baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssRules, vueRules };
+export { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, mazPlugin, rules as mazRules, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/eslint-config",
   "type": "module",
-  "version": "5.0.0-beta.0",
+  "version": "5.0.0-beta.11",
   "description": "ESLint configuration for JavaScript/TypeScript projects",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -25,7 +25,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -39,24 +40,18 @@
     "node": ">=20.19.0"
   },
   "peerDependencies": {
-    "eslint": ">=9.0.0 <11.0.0",
-    "eslint-plugin-tailwindcss": "^3.18.0"
-  },
-  "peerDependenciesMeta": {
-    "eslint-plugin-tailwindcss": {
-      "optional": true
-    }
+    "eslint": ">=9.0.0 <11.0.0"
   },
   "dependencies": {
     "@antfu/eslint-config": "^8.2.0",
+    "consola": "^3.4.2",
+    "eslint-plugin-better-tailwindcss": "^4.5.0",
     "eslint-plugin-format": "^2.0.1",
     "eslint-plugin-sonarjs": "^4.0.3",
     "eslint-plugin-vuejs-accessibility": "^2.5.0"
   },
   "devDependencies": {
-    "@types/eslint-plugin-tailwindcss": "^3.17.0",
     "eslint": "^10.3.0",
-    "eslint-plugin-tailwindcss": "^3.18.3",
     "unbuild": "^3.6.1"
   },
   "lint-staged": {
@@ -70,6 +65,9 @@
     "dev": "unbuild --stub",
     "typecheck": "tsc --noEmit --skipLibCheck",
     "lint": "cross-env NODE_ENV=production eslint .",
-    "lint:fix": "pnpm lint --fix"
+    "lint:fix": "pnpm lint --fix",
+    "test:unit": "vitest run",
+    "test:unit:coverage": "vitest run --coverage",
+    "test:unit:watch": "vitest watch"
   }
 }