diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..9e26dfe --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1 @@ +{} \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index e282472..dce35d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [1.11.1] - 2025-10-15 + +- Improve README structure and clarity + - Add "Important: Only Enable One Ordering Rule at a Time" section after configuration options + - Clarify that both `extends` and `plugins` approaches support rule customization + - Update "Recommended Configuration" section to list all 6 available rules (4 enabled by default, 2 alternatives) + - Add clear examples for switching between ordering rules +- Add warning about conflicting auto-fixes when multiple ordering rules are enabled simultaneously +- Clarify that users must explicitly disable the default ordering rule when switching to a different one + ## [1.11.0] - 2025-06-25 - add reference tracking for wrapper functions in vanilla-extract style objects diff --git a/README.md b/README.md index a024011..4dee8b8 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ There are two main ways to configure this plugin in your ESLint flat config: ### Option 1: Using extends (recommended, available from v1.10.0) -The simplest way to apply the recommended ruleset: +The simplest and most concise way to apply the recommended ruleset: ```typescript import { defineConfig } from 'eslint/config'; @@ -88,13 +88,18 @@ export default defineConfig([ files: ['**/*.css.ts'], ignores: ['src/**/theme-contract.css.ts'], extends: [vanillaExtract.configs.recommended], + // You can still override rules when using extends + // rules: { + // 'vanilla-extract/concentric-order': 'off', + // 'vanilla-extract/alphabetical-order': 'error', + // }, }, ]; ``` -### Option 2: Using plugins with explicit rule configuration +### Option 2: Using plugins with explicit rule spreading -This approach gives you more control over individual rules: +This approach is more explicit - you manually register the plugin and spread the recommended rules: ```typescript import { defineConfig } from 'eslint/config'; @@ -116,13 +121,64 @@ export default defineConfig([ // 'vanilla-extract/no-empty-style-blocks': 'off', // Disable a recommended rule // 'vanilla-extract/no-zero-unit': 'warn', // Change severity from error to warn - // Add additional rules not in recommended config - // 'vanilla-extract/alphabetical-order': 'error', // Override concentric-order rule + // Switch to a different ordering rule (see "Important" section below) + // 'vanilla-extract/concentric-order': 'off', + // 'vanilla-extract/alphabetical-order': 'error', }, }, ]; ``` +#### Important: Only Enable One Ordering Rule at a Time + +The plugin includes three CSS property ordering rules: `alphabetical-order`, `concentric-order`, and `custom-order`. **Only one ordering rule should be enabled at a time** to avoid conflicting auto-fixes. + +If you want to use a different ordering rule than the one in the recommended config, you must explicitly disable the default rule. + +##### Example: Switching from concentric to alphabetical ordering + +```typescript +export default [ + { + files: ['**/*.css.ts'], + plugins: { + 'vanilla-extract': vanillaExtract, + }, + rules: { + ...vanillaExtract.configs.recommended.rules, + 'vanilla-extract/concentric-order': 'off', // Disable the default + 'vanilla-extract/alphabetical-order': 'error', // Enable alphabetical + }, + }, +]; +``` + +##### Example: Using custom-order instead of the recommended concentric-order + +```typescript +export default [ + { + files: ['**/*.css.ts'], + plugins: { + 'vanilla-extract': vanillaExtract, + }, + rules: { + ...vanillaExtract.configs.recommended.rules, + 'vanilla-extract/concentric-order': 'off', // Disable the default + 'vanilla-extract/custom-order': [ + 'error', + { + groupOrder: ['font', 'dimensions', 'margin', 'padding', 'position', 'border'], + sortRemainingProperties: 'alphabetical', + }, + ], + }, + }, +]; +``` + +> **⚠️ Warning:** If multiple ordering rules are enabled simultaneously, they will produce conflicting auto-fixes that ESLint cannot apply, causing auto-fix on save to fail. Always ensure only one ordering rule is active. + ### Using with FlatCompat (for ESLint 8.57.0 & 8.57.1) If you're migrating from legacy ESLint configurations, you can use the `FlatCompat` utility to convert them while adding @@ -203,10 +259,15 @@ The recommended configuration enables the following rules with error severity: - `vanilla-extract/concentric-order`: Enforces concentric CSS property ordering - `vanilla-extract/no-empty-style-blocks`: Prevents empty style blocks -- `vanilla-extract/no-unknown-unit`: prohibits usage of unrecognized CSS units. -- `vanilla-extract/no-zero-unit`: removes unnecessary units for zero values +- `vanilla-extract/no-unknown-unit`: Prohibits usage of unrecognized CSS units +- `vanilla-extract/no-zero-unit`: Removes unnecessary units for zero values -You can use the recommended configuration as a starting point and override rules as needed for your project. +**Additional rules available** (not enabled by default): + +- `vanilla-extract/alphabetical-order`: Alternative ordering rule (alphabetical sorting) +- `vanilla-extract/custom-order`: Alternative ordering rule (custom group-based sorting) + +You can use the recommended configuration as a starting point and override rules as needed for your project. See the configuration examples above for how to switch between ordering rules. ### Custom Configuration @@ -240,6 +301,8 @@ export default [ ]; ``` +> **Note:** Remember to enable only one ordering rule at a time. See the "Important" section above for details on switching between ordering rules. + ## Rules ### vanilla-extract/alphabetical-order diff --git a/package.json b/package.json index 2962b67..c01e2ee 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@antebudimir/eslint-plugin-vanilla-extract", - "version": "1.11.0", + "version": "1.11.1", "description": "ESLint plugin for enforcing best practices in vanilla-extract CSS styles, including CSS property ordering and additional linting rules.", "author": "Ante Budimir", "license": "MIT", diff --git a/src/index.ts b/src/index.ts index 21fc702..aff2672 100644 --- a/src/index.ts +++ b/src/index.ts @@ -8,7 +8,7 @@ import noZeroUnitRule from './css-rules/no-zero-unit/rule-definition.js'; const vanillaExtract = { meta: { name: '@antebudimir/eslint-plugin-vanilla-extract', - version: '1.11.0', + version: '1.11.1', }, rules: { 'alphabetical-order': alphabeticalOrderRule,