@maz-ui/eslint-config 5.0.0-beta.5 → 5.0.0-beta.6

package/README.md

@@ -7,6 +7,7 @@ Reusable ESLint configuration for JavaScript/TypeScript projects, built on top o
 - 🚀 **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`
@@ -96,6 +97,8 @@ defineConfig({
     // Tailwind v3 instead:
     // tailwindConfig: 'tailwind.config.ts',
     detectComponentClasses: true,
+    // Custom `maz/tailwind-no-arbitrary-px` rule — see "Custom rules" below.
+    noArbitraryPx: true,
   },
 })
 ```
@@ -103,6 +106,82 @@ defineConfig({
 > [!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.
 
+## Custom rules
+
+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.
+
+### `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 the configured root font-size. Whitespace inside brackets (e.g. `[up to 100px]`) is left alone so plain prose is never rewritten.
+
+> [!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)).
+
+When `tailwindcss` is on, the rule is enabled with defaults. You can tune it either way:
+
+**Standard ESLint override** _(idiomatic, max control)_
+
+```js
+defineConfig({
+  tailwindcss: 'recommended',
+  rules: {
+    'maz/tailwind-no-arbitrary-px': ['error', { baseFontSize: 10, unit: 'em' }],
+  },
+})
+```
+
+User `rules` overrides are applied in a _trailing_ block, so they win over the rule's defaults wired in by `tailwindcssConfigs`.
+
+**Ergonomic shortcut** _(set the defaults via `tailwindcss.noArbitraryPx`)_
+
+```js
+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'
+    },
+  },
+})
+```
+
+| `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
+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 }],
+  },
+}]
+```
+
 ## Advanced
 
 ### Compose your own config
@@ -110,6 +189,7 @@ defineConfig({
 ```js
 import {
   baseRules,
+  mazPlugin,
   sonarjsRules,
   tailwindcssConfigs,
   vueRules,
@@ -117,13 +197,18 @@ import {
 
 export default [
   {
+    plugins: { maz: mazPlugin },
     rules: {
       ...baseRules(true), // production = true
       ...sonarjsRules,
       ...vueRules,
+      'maz/tailwind-no-arbitrary-px': 'error',
     },
   },
-  ...tailwindcssConfigs('stylistic', { entryPoint: 'src/main.css' }),
+  ...tailwindcssConfigs('stylistic', {
+    entryPoint: 'src/main.css',
+    noArbitraryPx: { unit: 'em' },
+  }),
 ]
 ```
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 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
@@ -53,6 +53,35 @@ interface MazTailwindcssOptions {
      * 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 {
     /**
@@ -147,9 +176,11 @@ declare const sonarjsTestRules: {
 declare const TAILWINDCSS_DEFAULT_FILES: string[];
 /**
  * Build the flat-config block(s) that wire up
- * `eslint-plugin-better-tailwindcss`. The plugin already ships preset
+ * `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.
+ * `settings['better-tailwindcss']` so the user's options reach the
+ * plugin.
  */
 declare function tailwindcssConfigs(preset: TailwindcssPreset, settings: MazTailwindcssOptions): Linter.Config[];
 
@@ -160,6 +191,32 @@ 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
  *
@@ -180,5 +237,5 @@ declare const vueSfcOnlyRules: {
  */
 declare function defineConfig(options?: MazESLintOptions, ...userConfigs: MazESLintUserConfig[]): MazESLintConfig;
 
-export { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };
+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,5 +1,5 @@
 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
@@ -53,6 +53,35 @@ interface MazTailwindcssOptions {
      * 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 {
     /**
@@ -147,9 +176,11 @@ declare const sonarjsTestRules: {
 declare const TAILWINDCSS_DEFAULT_FILES: string[];
 /**
  * Build the flat-config block(s) that wire up
- * `eslint-plugin-better-tailwindcss`. The plugin already ships preset
+ * `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.
+ * `settings['better-tailwindcss']` so the user's options reach the
+ * plugin.
  */
 declare function tailwindcssConfigs(preset: TailwindcssPreset, settings: MazTailwindcssOptions): Linter.Config[];
 
@@ -160,6 +191,32 @@ 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
  *
@@ -180,5 +237,5 @@ declare const vueSfcOnlyRules: {
  */
 declare function defineConfig(options?: MazESLintOptions, ...userConfigs: MazESLintUserConfig[]): MazESLintConfig;
 
-export { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };
+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

@@ -127,8 +127,134 @@ const sonarjsTestRules = {
   "sonarjs/no-duplicate-string": "off"
 };
 
+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 = {};
@@ -142,16 +268,22 @@ function tailwindcssConfigs(preset, settings) {
     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"
+      "better-tailwindcss/enforce-consistent-line-wrapping": "off",
+      "maz/tailwind-no-arbitrary-px": [noArbitraryPx.severity, noArbitraryPx.options]
     }
   }];
 }
@@ -327,17 +459,15 @@ function defineConfig(options = {}, ...userConfigs) {
     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 { TAILWINDCSS_DEFAULT_FILES, baseRules, defineConfig, sonarjsRules, sonarjsTestRules, tailwindcssConfigs, vueRules, vueSfcOnlyRules };
+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.5",
+  "version": "5.0.0-beta.6",
   "description": "ESLint configuration for JavaScript/TypeScript projects",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",
@@ -64,6 +64,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"
   }
 }