[New] jsx-sort-props: add sortFirst option

Fixes #3175.
Fixes #3639.
Fixes #3193.
Closes #3853.

Author: ljharb

CHANGELOG.md

@@ -10,6 +10,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 * [`jsx-props-no-multi-spaces`]: improve autofix for multi-line ([#3930][] @justisb)
 * [`jsx-handler-names`]: support namespaced component names ([#3943][] @takuji)
 * [`jsx-no-leaked-render`]: add `ignoreAttributes` option ([#3441][] @aleclarson)
+* [`jsx-sort-props`]: add `sortFirst` option ([#3965][] @loderunner)
 
 ### Fixed
 * [`no-unknown-property`]: allow `onLoad` on `body` ([#3923][] @DerekStapleton)
@@ -24,6 +25,7 @@ This change log adheres to standards from [Keep a CHANGELOG](https://keepachange
 [#3978]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3978
 [#3958]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3958
 [#3980]: https://github.com/jsx-eslint/eslint-plugin-react/issues/3980
+[#3965]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3965
 [#3943]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3943
 [#3942]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3942
 [#3930]: https://github.com/jsx-eslint/eslint-plugin-react/pull/3930

docs/rules/jsx-sort-props.md

@@ -15,7 +15,7 @@ This rule checks all JSX components and verifies that all props are sorted alpha
 Examples of **incorrect** code for this rule:
 
 ```jsx
-<Hello lastName="Smith" firstName="John" />;
+<Hello lastName="Smith" firstName="John" />
 ```
 
 Examples of **correct** code for this rule:
@@ -37,6 +37,7 @@ Examples of **correct** code for this rule:
   "ignoreCase": <boolean>,
   "noSortAlphabetically": <boolean>,
   "reservedFirst": <boolean>|<array<string>>,
+  "sortFirst": <array<string>>,
   "locale": "auto" | "any valid locale"
 }]
 ...
@@ -49,7 +50,7 @@ When `true` the rule ignores the case-sensitivity of the props order.
 Examples of **correct** code for this rule
 
 ```jsx
-<Hello name="John" Number="2" />;
+<Hello name="John" Number="2" />
 ```
 
 ### `callbacksLast`
@@ -140,6 +141,32 @@ With `reservedFirst: ["key"]`, the following will **not** warn:
 <Hello key={'uuid'} name="John" ref={johnRef} />
 ```
 
+### `sortFirst`
+
+When `sortFirst` is defined as an array of prop names, those props must be listed before all other props, maintaining the exact order specified in the array. This option has the highest priority and takes precedence over all other sorting options (including `reservedFirst`, `shorthandFirst`, `callbacksLast`, and `multiline`).
+
+The prop names in the array are matched case-sensitively by default, but respect the `ignoreCase` option when enabled.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+// 'jsx-sort-props': [1, { sortFirst: ['className'] }]
+<Hello name="John" className="test" />
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+// 'jsx-sort-props': [1, { sortFirst: ['className'] }]
+<Hello className="test" name="John" />
+
+// 'jsx-sort-props': [1, { sortFirst: ['className', 'id'] }]
+<Hello className="test" id="test" name="John" />
+
+// 'jsx-sort-props': [1, { sortFirst: ['className'], ignoreCase: true }]
+<Hello classname="test" name="John" />
+```
+
 ### `locale`
 
 Defaults to `"auto"`, meaning, the locale of the current environment.

lib/rules/jsx-sort-props.js

@@ -35,6 +35,7 @@ const messages = {
   listShorthandLast: 'Shorthand props must be listed after all other props',
   listMultilineFirst: 'Multiline props must be listed before all other props',
   listMultilineLast: 'Multiline props must be listed after all other props',
+  listSortFirstPropsFirst: 'Props in sortFirst must be listed before all other props',
   sortPropsByAlpha: 'Props should be sorted alphabetically',
 };
 
@@ -49,6 +50,17 @@ function isReservedPropName(name, list) {
   return list.indexOf(name) >= 0;
 }
 
+function getSortFirstIndex(name, sortFirstList, ignoreCase) {
+  const normalizedPropName = ignoreCase ? name.toLowerCase() : name;
+  for (let i = 0; i < sortFirstList.length; i++) {
+    const normalizedListName = ignoreCase ? sortFirstList[i].toLowerCase() : sortFirstList[i];
+    if (normalizedPropName === normalizedListName) {
+      return i;
+    }
+  }
+  return -1;
+}
+
 let attributeMap;
 // attributeMap = { end: endrange, hasComment: true||false if comment in between nodes exists, it needs to be sorted to end }
 
@@ -70,6 +82,24 @@ function contextCompare(a, b, options) {
     return -1;
   }
 
+  if (options.sortFirst && options.sortFirst.length > 0) {
+    const aSortFirstIndex = getSortFirstIndex(aProp, options.sortFirst, options.ignoreCase);
+    const bSortFirstIndex = getSortFirstIndex(bProp, options.sortFirst, options.ignoreCase);
+    if (aSortFirstIndex >= 0 && bSortFirstIndex >= 0) {
+      // Both are in sortFirst, maintain their exact order
+      if (aSortFirstIndex !== bSortFirstIndex) {
+        return aSortFirstIndex - bSortFirstIndex;
+      }
+      return 0;
+    }
+    if (aSortFirstIndex >= 0 && bSortFirstIndex < 0) {
+      return -1;
+    }
+    if (aSortFirstIndex < 0 && bSortFirstIndex >= 0) {
+      return 1;
+    }
+  }
+
   if (options.reservedFirst) {
     const aIsReserved = isReservedPropName(aProp, options.reservedList);
     const bIsReserved = isReservedPropName(bProp, options.reservedList);
@@ -222,6 +252,7 @@ function generateFixerFunction(node, context, reservedList) {
   const multiline = configuration.multiline || 'ignore';
   const noSortAlphabetically = configuration.noSortAlphabetically || false;
   const reservedFirst = configuration.reservedFirst || false;
+  const sortFirst = configuration.sortFirst || [];
   const locale = configuration.locale || 'auto';
 
   // Sort props according to the context. Only supports ignoreCase.
@@ -236,6 +267,7 @@ function generateFixerFunction(node, context, reservedList) {
     noSortAlphabetically,
     reservedFirst,
     reservedList,
+    sortFirst,
     locale,
   };
   const sortableAttributeGroups = getGroupsOfSortableAttributes(attributes, context);
@@ -382,6 +414,13 @@ module.exports = {
         reservedFirst: {
           type: ['array', 'boolean'],
         },
+        sortFirst: {
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+          uniqueItems: true,
+        },
         locale: {
           type: 'string',
           default: 'auto',
@@ -402,6 +441,7 @@ module.exports = {
     const reservedFirst = configuration.reservedFirst || false;
     const reservedFirstError = validateReservedFirstConfig(context, reservedFirst);
     const reservedList = Array.isArray(reservedFirst) ? reservedFirst : RESERVED_PROPS_LIST;
+    const sortFirst = configuration.sortFirst || [];
     const locale = configuration.locale || 'auto';
 
     return {
@@ -425,6 +465,31 @@ module.exports = {
           const previousIsCallback = propTypesSortUtil.isCallbackPropName(previousPropName);
           const currentIsCallback = propTypesSortUtil.isCallbackPropName(currentPropName);
 
+          if (sortFirst && sortFirst.length > 0) {
+            const previousSortFirstIndex = getSortFirstIndex(previousPropName, sortFirst, ignoreCase);
+            const currentSortFirstIndex = getSortFirstIndex(currentPropName, sortFirst, ignoreCase);
+
+            if (previousSortFirstIndex >= 0 && currentSortFirstIndex >= 0) {
+              // Both are in sortFirst, check their order
+              if (previousSortFirstIndex > currentSortFirstIndex) {
+                reportNodeAttribute(decl, 'listSortFirstPropsFirst', node, context, nodeReservedList);
+                return memo;
+              }
+              return decl;
+            }
+
+            if (previousSortFirstIndex >= 0 && currentSortFirstIndex < 0) {
+              // Previous is in sortFirst, current is not - this is correct, continue to next prop
+              return decl;
+            }
+
+            if (previousSortFirstIndex < 0 && currentSortFirstIndex >= 0) {
+              // Current is in sortFirst but previous is not - error
+              reportNodeAttribute(decl, 'listSortFirstPropsFirst', node, context, nodeReservedList);
+              return memo;
+            }
+          }
+
           if (ignoreCase) {
             previousPropName = previousPropName.toLowerCase();
             currentPropName = currentPropName.toLowerCase();

tests/lib/rules/jsx-sort-props.js

@@ -58,6 +58,10 @@ const expectedReservedFirstError = {
   messageId: 'listReservedPropsFirst',
   type: 'JSXIdentifier',
 };
+const expectedSortFirstError = {
+  messageId: 'listSortFirstPropsFirst',
+  type: 'JSXIdentifier',
+};
 const expectedEmptyReservedFirstError = {
   messageId: 'listIsEmpty',
 };
@@ -120,6 +124,33 @@ const multilineAndShorthandAndCallbackLastArgs = [
     callbacksLast: true,
   },
 ];
+const sortFirstArgs = [{ sortFirst: ['className'] }];
+const sortFirstMultipleArgs = [{ sortFirst: ['className', 'id'] }];
+const sortFirstWithIgnoreCaseArgs = [{ sortFirst: ['className'], ignoreCase: true }];
+const sortFirstWithReservedFirstArgs = [
+  {
+    sortFirst: ['className'],
+    reservedFirst: true,
+  },
+];
+const sortFirstWithShorthandFirstArgs = [
+  {
+    sortFirst: ['className'],
+    shorthandFirst: true,
+  },
+];
+const sortFirstWithCallbacksLastArgs = [
+  {
+    sortFirst: ['className'],
+    callbacksLast: true,
+  },
+];
+const sortFirstWithMultilineFirstArgs = [
+  {
+    sortFirst: ['className'],
+    multiline: 'first',
+  },
+];
 
 ruleTester.run('jsx-sort-props', rule, {
   valid: parsers.all([].concat(
@@ -296,7 +327,29 @@ ruleTester.run('jsx-sort-props', rule, {
         />
       `,
       options: [{ locale: 'sk-SK' }],
-    } : []
+    } : [],
+    // sortFirst
+    { code: '<App className="test" name="John" />;', options: sortFirstArgs },
+    { code: '<App className="test" id="test" name="John" />;', options: sortFirstMultipleArgs },
+    { code: '<App className="test" id="test" />;', options: sortFirstMultipleArgs },
+    { code: '<App className="test" a b c />;', options: sortFirstArgs },
+    { code: '<App className="test" id="test" a b c />;', options: sortFirstMultipleArgs },
+    { code: '<App className="test" key={0} name="John" />;', options: sortFirstWithReservedFirstArgs },
+    { code: '<App className="test" a name="John" />;', options: sortFirstWithShorthandFirstArgs },
+    { code: '<App className="test" name="John" onClick={handleClick} />;', options: sortFirstWithCallbacksLastArgs },
+    {
+      code: `
+        <App
+          className="test"
+          data={{
+            test: 1,
+          }}
+          name="John"
+        />
+      `,
+      options: sortFirstWithMultilineFirstArgs,
+    },
+    { code: '<App classname="test" a="test2" />;', options: sortFirstWithIgnoreCaseArgs }
   )),
   invalid: parsers.all([].concat(
     {
@@ -1101,6 +1154,83 @@ ruleTester.run('jsx-sort-props', rule, {
           line: 11,
         },
       ],
+    },
+    // sortFirst
+    {
+      code: '<App name="John" className="test" />;',
+      options: sortFirstArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" name="John" />;',
+    },
+    {
+      code: '<App id="test" className="test" name="John" />;',
+      options: sortFirstMultipleArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" id="test" name="John" />;',
+    },
+    {
+      code: '<App a className="test" b />;',
+      options: sortFirstArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" a b />;',
+    },
+    {
+      code: '<App key={0} className="test" name="John" />;',
+      options: sortFirstWithReservedFirstArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" key={0} name="John" />;',
+    },
+    {
+      code: '<App a className="test" name="John" />;',
+      options: sortFirstWithShorthandFirstArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" a name="John" />;',
+    },
+    {
+      code: '<App name="John" onClick={handleClick} className="test" />;',
+      options: sortFirstWithCallbacksLastArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" name="John" onClick={handleClick} />;',
+    },
+    {
+      code: `
+        <App
+          name="John"
+          className="test"
+          data={{
+            test: 1,
+          }}
+        />
+      `,
+      options: sortFirstWithMultilineFirstArgs,
+      errors: [expectedSortFirstError, expectedMultilineFirstError],
+      output: `
+        <App
+          className="test"
+          data={{
+            test: 1,
+          }}
+          name="John"
+        />
+      `,
+    },
+    {
+      code: '<App name="John" classname="test" />;',
+      options: sortFirstWithIgnoreCaseArgs,
+      errors: [expectedSortFirstError],
+      output: '<App classname="test" name="John" />;',
+    },
+    {
+      code: '<App className="test" id="test" tel={5555555} name="John" />;',
+      options: sortFirstMultipleArgs,
+      errors: [expectedError],
+      output: '<App className="test" id="test" name="John" tel={5555555} />;',
+    },
+    {
+      code: '<App id="test" className="test" id="test2" />;',
+      options: sortFirstMultipleArgs,
+      errors: [expectedSortFirstError],
+      output: '<App className="test" id="test" id="test2" />;',
     }
   )),
 });