eslint-plugin-code-style 1.2.0 → 1.2.7

package/AGENTS.md

@@ -4,9 +4,9 @@ Instructions for AI coding agents working with this codebase.
 
 ## Project Overview
 
-**eslint-plugin-code-style** is an ESLint plugin providing 56 custom auto-fixable formatting rules for React/JSX projects. It's designed for ESLint v9+ flat config system.
+**eslint-plugin-code-style** is an ESLint plugin providing 60 custom auto-fixable formatting rules for React/JSX projects. It's designed for ESLint v9+ flat config system.
 
-- **Main entry:** `index.js` - Contains all 56 rules in a single file
+- **Main entry:** `index.js` - Contains all 60 rules in a single file
 - **Type definitions:** `index.d.ts` - TypeScript declarations for IDE support
 - **Recommended configs:** `recommended-configs/` - Ready-to-use ESLint configurations
 - **Test apps:** `_tests_/` - Sample apps for testing rules
@@ -44,7 +44,7 @@ index.js
 ├── imports (fs, path, url)
 ├── Rule 1 definition (const ruleName = { create(), meta: {} })
 ├── Rule 2 definition
-├── ... (56 rules total)
+├── ... (60 rules total)
 └── export default { meta: {}, rules: {} }
 ```
 
@@ -209,7 +209,7 @@ Rules are organized in these categories (alphabetically sorted in index.js and R
 - **Function Rules:** `function-call-spacing`, `function-naming-convention`, `function-object-destructure`, `function-params-per-line`, `no-empty-lines-in-function-params`
 - **Hook Rules:** `hook-callback-format`, `hook-deps-per-line`
 - **Import/Export Rules:** `absolute-imports-only`, `export-format`, `import-format`, `import-source-spacing`, `index-export-style`, `module-index-exports`
-- **JSX Rules:** `jsx-children-on-new-line`, `jsx-closing-bracket-spacing`, `jsx-element-child-new-line`, `jsx-logical-expression-simplify`, `jsx-parentheses-position`, `jsx-prop-naming-convention`, `jsx-simple-element-one-line`, `jsx-string-value-trim`, `jsx-ternary-format`, `no-empty-lines-in-jsx`
+- **JSX Rules:** `classname-dynamic-at-end`, `classname-multiline`, `classname-no-extra-spaces`, `classname-order`, `jsx-children-on-new-line`, `jsx-closing-bracket-spacing`, `jsx-element-child-new-line`, `jsx-logical-expression-simplify`, `jsx-parentheses-position`, `jsx-prop-naming-convention`, `jsx-simple-element-one-line`, `jsx-string-value-trim`, `jsx-ternary-format`, `no-empty-lines-in-jsx`
 - **Object Rules:** `no-empty-lines-in-objects`, `object-property-per-line`, `object-property-value-brace`, `object-property-value-format`, `string-property-spacing`
 - **React Rules:** `react-code-order`
 - **Spacing Rules:** `assignment-value-same-line`, `member-expression-bracket-spacing`
@@ -230,7 +230,7 @@ Rules are organized in these categories (alphabetically sorted in index.js and R
 
 ## Documentation Files
 
-- `README.md` - Main documentation with all 56 rules
+- `README.md` - Main documentation with all 60 rules
 - `recommended-configs/<config-name>/README.md` - Config-specific documentation (references main README for rule details)
 - `index.d.ts` - TypeScript types for IDE autocomplete
 

package/README.md

@@ -7,9 +7,10 @@
 [![License](https://img.shields.io/npm/l/eslint-plugin-code-style?style=for-the-badge&color=blue)](https://github.com/Mohamed-Elhawary/eslint-plugin-code-style/blob/main/LICENSE)
 
 [![ESLint](https://img.shields.io/badge/ESLint-%3E%3D9.0.0-4B32C3?style=for-the-badge&logo=eslint&logoColor=white)](https://eslint.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![React](https://img.shields.io/badge/React-JSX%20Support-61DAFB?style=for-the-badge&logo=react&logoColor=black)](https://react.dev/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Supported-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-%3E%3D5.0.0-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Tailwind CSS](https://img.shields.io/badge/Tailwind%20CSS-%3E%3D4.0.0-06B6D4?style=for-the-badge&logo=tailwindcss&logoColor=white)](https://tailwindcss.com/)
 
 [![GitHub stars](https://img.shields.io/github/stars/Mohamed-Elhawary/eslint-plugin-code-style?style=for-the-badge&logo=github&color=yellow)](https://github.com/Mohamed-Elhawary/eslint-plugin-code-style/stargazers)
 [![GitHub issues](https://img.shields.io/github/issues/Mohamed-Elhawary/eslint-plugin-code-style?style=for-the-badge&logo=github)](https://github.com/Mohamed-Elhawary/eslint-plugin-code-style/issues)
@@ -18,7 +19,7 @@
 
 **A powerful ESLint plugin for enforcing consistent code formatting and style rules in React/JSX projects.**
 
-*56 auto-fixable rules to keep your codebase clean and consistent*
+*60 auto-fixable rules to keep your codebase clean and consistent*
 
 </div>
 
@@ -26,7 +27,7 @@
 
 ## 🎯 Why This Plugin?
 
-This plugin provides **56 custom auto-fixable rules** for code formatting. Built for **ESLint v9 flat configs**.
+This plugin provides **60 custom auto-fixable rules** for code formatting. Built for **ESLint v9 flat configs**.
 
 > **Note:** ESLint [deprecated 79 formatting rules](https://eslint.org/blog/2023/10/deprecating-formatting-rules/) in v8.53.0. Our recommended configs use `@stylistic/eslint-plugin` as the replacement for these deprecated rules.
 
@@ -35,7 +36,7 @@ This plugin provides **56 custom auto-fixable rules** for code formatting. Built
 - **Works alongside existing tools** — Complements ESLint's built-in rules and packages like eslint-plugin-react, eslint-plugin-import, etc
 - **Self-sufficient rules** — Each rule handles complete formatting independently
 - **Consistency at scale** — Reduces code-style differences between team members by enforcing uniform formatting across your projects
-- **Fully automated** — All 56 rules support auto-fix, eliminating manual style reviews
+- **Fully automated** — All 60 rules support auto-fix, eliminating manual style reviews
 
 When combined with ESLint's native rules and other popular plugins, this package helps create a complete code style solution that keeps your codebase clean and consistent.
 
@@ -59,7 +60,7 @@ We provide **ready-to-use ESLint flat configuration files** that combine `eslint
 
 ### 💡 Why Use These Configs?
 
-- **Complete Coverage** — Combines ESLint built-in rules, third-party plugins, and all 56 code-style rules
+- **Complete Coverage** — Combines ESLint built-in rules, third-party plugins, and all 60 code-style rules
 - **Ready-to-Use** — Copy the config file and start linting immediately
 - **Battle-Tested** — These configurations have been refined through real-world usage
 - **Fully Documented** — Each config includes detailed instructions and explanations
@@ -96,7 +97,7 @@ We provide **ready-to-use ESLint flat configuration files** that combine `eslint
 <td width="50%">
 
 ### 🔧 Auto-Fixable Rules
-All **56 rules** support automatic fixing with `eslint --fix`. No manual code changes needed.
+All **60 rules** support automatic fixing with `eslint --fix`. No manual code changes needed.
 
 </td>
 <td width="50%">
@@ -142,7 +143,7 @@ yarn add eslint-plugin-code-style -D
 | Dependency | Version |
 |------------|---------|
 | **ESLint** | `>= 9.0.0` |
-| **Node.js** | `>= 18.0.0` |
+| **Node.js** | `>= 20.0.0` |
 
 <br />
 
@@ -180,18 +181,24 @@ eslint src/ --fix
 
 ```javascript
 rules: {
+    "code-style/absolute-imports-only": "error",
     "code-style/array-items-per-line": "error",
     "code-style/array-objects-on-new-lines": "error",
     "code-style/arrow-function-block-body": "error",
     "code-style/arrow-function-simple-jsx": "error",
     "code-style/arrow-function-simplify": "error",
-    "code-style/curried-arrow-same-line": "error",
     "code-style/assignment-value-same-line": "error",
     "code-style/block-statement-newlines": "error",
+    "code-style/classname-dynamic-at-end": "error",
+    "code-style/classname-multiline": "error",
+    "code-style/classname-no-extra-spaces": "error",
     "code-style/comment-format": "error",
     "code-style/component-props-destructure": "error",
-    "code-style/react-code-order": "error",
     "code-style/component-props-inline-type": "error",
+    "code-style/curried-arrow-same-line": "error",
+    "code-style/enum-format": "error",
+    "code-style/export-format": "error",
+    "code-style/function-arguments-format": "error",
     "code-style/function-call-spacing": "error",
     "code-style/function-naming-convention": "error",
     "code-style/function-object-destructure": "error",
@@ -199,13 +206,10 @@ rules: {
     "code-style/hook-callback-format": "error",
     "code-style/hook-deps-per-line": "error",
     "code-style/if-statement-format": "error",
-    "code-style/multiline-if-conditions": "error",
-    "code-style/absolute-imports-only": "error",
-    "code-style/export-format": "error",
     "code-style/import-format": "error",
     "code-style/import-source-spacing": "error",
     "code-style/index-export-style": "error",
-    "code-style/module-index-exports": "error",
+    "code-style/interface-format": "error",
     "code-style/jsx-children-on-new-line": "error",
     "code-style/jsx-closing-bracket-spacing": "error",
     "code-style/jsx-element-child-new-line": "error",
@@ -216,7 +220,8 @@ rules: {
     "code-style/jsx-string-value-trim": "error",
     "code-style/jsx-ternary-format": "error",
     "code-style/member-expression-bracket-spacing": "error",
-    "code-style/function-arguments-format": "error",
+    "code-style/module-index-exports": "error",
+    "code-style/multiline-if-conditions": "error",
     "code-style/nested-call-closing-brackets": "error",
     "code-style/no-empty-lines-in-function-calls": "error",
     "code-style/no-empty-lines-in-function-params": "error",
@@ -227,15 +232,14 @@ rules: {
     "code-style/object-property-value-brace": "error",
     "code-style/object-property-value-format": "error",
     "code-style/opening-brackets-same-line": "error",
+    "code-style/react-code-order": "error",
     "code-style/simple-call-single-line": "error",
     "code-style/single-argument-on-one-line": "error",
     "code-style/string-property-spacing": "error",
-    "code-style/variable-naming-convention": "error",
-    "code-style/enum-format": "error",
-    "code-style/interface-format": "error",
     "code-style/type-annotation-spacing": "error",
     "code-style/type-format": "error",
     "code-style/typescript-definition-location": "error",
+    "code-style/variable-naming-convention": "error",
 }
 ```
 
@@ -245,7 +249,7 @@ rules: {
 
 ## 📖 Rules Summary
 
-> All **56 rules** are auto-fixable. See detailed examples for each rule in the [Rules Reference](#-rules-reference) section below.
+> All **60 rules** are auto-fixable. See detailed examples for each rule in the [Rules Reference](#-rules-reference) section below.
 >
 > Rules marked with ⚙️ support customization options (e.g., extending default folder lists).
 
@@ -264,7 +268,7 @@ rules: {
 | `nested-call-closing-brackets` | Chain closing brackets on same line: `}));` not scattered across lines |
 | `no-empty-lines-in-function-calls` | No empty lines between arguments or after `(`/before `)` |
 | `opening-brackets-same-line` | Opening `{`, `[`, or `(` on same line as function call, not on new line |
-| `simple-call-single-line` | Collapse simple `fn(() => call())` patterns to single line |
+| `simple-call-single-line` | Collapse simple arrow function calls to single line (including callbacks with params and optional chaining) |
 | `single-argument-on-one-line` | Single simple argument stays on one line: `fn(x)` not expanded |
 | **Comment Rules** | |
 | `comment-format` | Space after `//`, space inside `/* */`, convert single-line blocks to `//`, no blank lines between file-top comments |
@@ -293,6 +297,9 @@ rules: {
 | `index-export-style` | Index files: no blank lines, enforce shorthand or import-export style; Regular files: require blank lines between exports (default: shorthand) ⚙️ |
 | `module-index-exports` | Index files must export all folder contents (files and subfolders) ⚙️ |
 | **JSX Rules** | |
+| `classname-dynamic-at-end` | Dynamic expressions (`${className}`) must be at the end of class strings (JSX and variables) |
+| `classname-multiline` | Long className strings broken into multiple lines, one class per line; uses `"..."` in JSX (no expressions) or `` `...` `` (with expressions/variables) ⚙️ |
+| `classname-no-extra-spaces` | No extra/leading/trailing spaces in class strings (JSX, variables, and objects) |
 | `jsx-children-on-new-line` | Multiple JSX children: each on own line with proper indentation |
 | `jsx-closing-bracket-spacing` | No space before `>` or `/>` in JSX tags |
 | `jsx-element-child-new-line` | Nested JSX elements on new lines; text/expression children can stay inline |
@@ -321,7 +328,7 @@ rules: {
 | **React Rules** | |
 | `react-code-order` | Enforce consistent ordering in components and hooks: props destructure → refs → state → redux → router → context → custom hooks → derived → memo → callback → handlers → effects → return |
 | **Variable Rules** | |
-| `variable-naming-convention` | camelCase for variables, UPPER_CASE for constants, PascalCase for components, `use` prefix for hooks |
+| `variable-naming-convention` | camelCase for all variables and constants, PascalCase for components, `use` prefix for hooks |
 
 <br />
 
@@ -721,17 +728,18 @@ items.map(
 
 ### `simple-call-single-line`
 
-**What it does:** Collapses simple function calls with an arrow function containing a single call expression onto one line.
+**What it does:** Collapses simple function calls with an arrow function onto one line when the result fits within 120 characters. Handles:
+- Zero-param callbacks: `lazy(() => import("./Page"))`
+- Callbacks with params and simple expression bodies: `.find((f) => f.code === x)`
+- Optional chaining: `.find(...)?.symbol`
 
-**Why use it:** Common patterns like `lazy(() => import(...))` don't need multiline formatting. Single line is cleaner.
+**Why use it:** Common patterns like `lazy(() => import(...))` and `.find((item) => item.id === id)` don't need multiline formatting. Single line is cleaner.
 
 ```javascript
 // ✅ Good — simple patterns on one line
 const Page = lazy(() => import("./Page"));
-const Modal = lazy(() => import("./Modal"));
 setTimeout(() => callback(), 100);
-requestAnimationFrame(() => render());
-items.filter(() => isValid(item));
+const symbol = items.find(({ code }) => code === currency)?.symbol;
 
 // ✅ Good — complex callbacks stay multiline
 const Page = lazy(() => {
@@ -744,10 +752,11 @@ const Page = lazy(
     () => import("./Page"),
 );
 
-setTimeout(
-    () => callback(),
-    100,
-);
+const symbol = items.find(({ code }) =>
+    code === currency)?.symbol;
+
+const symbol = items.find(({ code }) => code === currency)?.
+    symbol;
 ```
 
 ---
@@ -1637,6 +1646,132 @@ import { Button } from "@/components/Button/Button"; // Avoid this!
 
 ## ⚛️ JSX Rules
 
+### `classname-dynamic-at-end`
+
+**What it does:** Enforces that dynamic expressions in className template literals are placed at the end, after all static class names. Also applies to variables with names containing "class" or "Class".
+
+**Why use it:** When using Tailwind CSS with `tailwindcss/classnames-order`, static classes are automatically sorted. However, dynamic expressions like `${className}` or `${styles.button}` can break the visual order if placed in the middle. This rule ensures dynamic parts come last for consistent, readable class strings.
+
+```javascript
+// ✅ Good — dynamic expressions at the end (JSX)
+<div className={`flex items-center gap-4 ${className}`} />
+
+// ✅ Good — dynamic expressions at the end (variable)
+const buttonClasses = `flex items-center ${className} ${styles.button}`;
+
+// ❌ Bad — dynamic expression at the beginning
+<div className={`${className} flex items-center gap-4`} />
+
+// ❌ Bad — dynamic expression in the middle (variable)
+const buttonClasses = `flex ${className} items-center gap-4`;
+```
+
+---
+
+### `classname-multiline`
+
+**What it does:** Enforces that long className strings are broken into multiple lines, with each class on its own line. Triggers when either the class count exceeds `maxClassCount` (default: 3) or the string length exceeds `maxLength` (default: 80). Also enforces:
+- JSX `className` with no dynamic expressions uses `"..."` string literal format
+- JSX `className` with dynamic expressions uses `` {`...`} `` template literal format
+- Variables/object properties use `` `...` `` template literal for multiline (JS requires it)
+- No empty lines between classes or before/after the quotes
+- Under-threshold multiline classes are collapsed back to a single line
+
+Applies to JSX `className` attributes, variables with class-related names, and object properties within class-related objects.
+
+**Why use it:** Long single-line class strings are hard to read and review. Breaking them into one class per line makes diffs cleaner and classes easier to scan. Using string literals when no expressions are needed keeps the code simpler.
+
+```javascript
+// ✅ Good — JSX with no expressions uses "..." format
+<div
+    className="
+        flex
+        items-center
+        justify-center
+        rounded-lg
+        p-4
+    "
+/>
+
+// ✅ Good — JSX with expressions uses {`...`} format
+<div
+    className={`
+        flex
+        items-center
+        justify-center
+        ${className}
+    `}
+/>
+
+// ✅ Good — variable multiline uses template literal
+const buttonClasses = `
+    flex
+    items-center
+    justify-center
+    ${className}
+`;
+
+// ✅ Good — object property multiline uses template literal
+const variantClasses = {
+    danger: `
+        flex
+        items-center
+        justify-center
+        bg-red-500
+    `,
+};
+
+// ✅ Good — short class strings stay on one line
+<div className="flex items-center" />
+
+// ❌ Bad — too many classes on one line
+<div className="flex items-center justify-center rounded-lg p-4 font-bold" />
+
+// ❌ Bad — using template literal in JSX when no expressions
+<div className={`
+    flex
+    items-center
+    justify-center
+    rounded-lg
+`} />
+
+// ❌ Bad — empty lines between classes
+<div className="
+    flex
+
+    items-center
+    justify-center
+" />
+```
+
+---
+
+### `classname-no-extra-spaces`
+
+**What it does:** Removes multiple consecutive spaces and leading/trailing spaces inside className values. Applies to:
+- JSX `className` attributes (string literals and template literals)
+- Variables with names containing "class" (e.g., `buttonClasses`, `variantClasses`)
+- Object properties within class-related objects
+
+**Why use it:** Extra spaces between class names are usually unintentional and can cause issues. This rule normalizes spacing and removes unnecessary whitespace.
+
+```javascript
+// ✅ Good — single space between classes
+<div className="flex items-center gap-4 rounded-lg" />
+const buttonClasses = `flex items-center ${className}`;
+const variantClasses = { primary: "bg-blue-500 text-white" };
+
+// ❌ Bad — multiple consecutive spaces
+<div className="flex  items-center   gap-4" />
+const buttonClasses = `flex  items-center`;
+const variantClasses = { primary: "bg-blue-500  text-white" };
+
+// ❌ Bad — leading/trailing spaces in template literal
+const buttonClasses = ` flex items-center ${className} `;
+```
+
+---
+
 ### `jsx-children-on-new-line`
 
 **What it does:** When a JSX element has multiple children, ensures each child is on its own line with proper indentation.
@@ -2782,8 +2917,7 @@ const YetAnotherBad = ({ title }) => {
 ### `variable-naming-convention`
 
 **What it does:** Enforces naming conventions for variables:
-- **camelCase** for regular variables and functions
-- **UPPER_CASE** for constants (primitive values)
+- **camelCase** for all variables and constants
 - **PascalCase** for React components and classes
 - **camelCase with `use` prefix** for hooks
 
@@ -2793,14 +2927,14 @@ const YetAnotherBad = ({ title }) => {
 // ✅ Good — correct conventions
 const userName = "John";           // camelCase for variables
 const itemCount = 42;              // camelCase for variables
-const MAX_RETRIES = 3;             // UPPER_CASE for constants
-const API_BASE_URL = "/api";       // UPPER_CASE for constants
+const maxRetries = 3;              // camelCase for constants
+const apiBaseUrl = "/api";         // camelCase for constants
 const UserProfile = () => <div />; // PascalCase for components
 const useAuth = () => {};          // camelCase with use prefix for hooks
 
 // ❌ Bad — wrong conventions
 const user_name = "John";          // snake_case
-const maxretries = 3;              // should be UPPER_CASE
+const MAX_RETRIES = 3;             // should be camelCase
 const userProfile = () => <div />; // should be PascalCase
 const UseAuth = () => {};          // hooks should be camelCase
 ```

package/index.d.ts

@@ -29,6 +29,10 @@ export type RuleNames =
     | "code-style/import-format"
     | "code-style/import-source-spacing"
     | "code-style/index-export-style"
+    | "code-style/classname-dynamic-at-end"
+    | "code-style/classname-multiline"
+    | "code-style/classname-no-extra-spaces"
+    | "code-style/classname-order"
     | "code-style/jsx-children-on-new-line"
     | "code-style/jsx-closing-bracket-spacing"
     | "code-style/jsx-element-child-new-line"
@@ -106,6 +110,10 @@ interface PluginRules {
     "import-format": Rule.RuleModule;
     "import-source-spacing": Rule.RuleModule;
     "index-export-style": Rule.RuleModule;
+    "classname-dynamic-at-end": Rule.RuleModule;
+    "classname-multiline": Rule.RuleModule;
+    "classname-no-extra-spaces": Rule.RuleModule;
+    "classname-order": Rule.RuleModule;
     "jsx-children-on-new-line": Rule.RuleModule;
     "jsx-closing-bracket-spacing": Rule.RuleModule;
     "jsx-element-child-new-line": Rule.RuleModule;