feat: introduce stylelint plugin

apps/site/.stylelintrc.mjs

@@ -23,7 +23,11 @@ const ONLY_ALLOW_CAMEL_CASE_SELECTORS = [
 
 export default {
   extends: ['stylelint-config-standard'],
-  plugins: ['stylelint-order', 'stylelint-selector-bem-pattern'],
+  plugins: [
+    'stylelint-order',
+    'stylelint-selector-bem-pattern',
+    '@node-core/ui-components/stylelint.plugin.mjs',
+  ],
   rules: {
     // Enforces Element Class Names to be camelCase
     'selector-class-pattern': ONLY_ALLOW_CAMEL_CASE_SELECTORS,
@@ -45,5 +49,6 @@ export default {
     'import-notation': 'string',
     // Allow the `@apply` at rule as its part of Tailwind
     'at-rule-no-deprecated': [true, { ignoreAtRules: CUSTOM_AT_RULES }],
+    'ui-components/one-tailwind-token-per-line': true,
   },
 };

apps/site/layouts/layouts.module.css

@@ -137,14 +137,14 @@
 
     &:nth-of-type(2) {
       @apply flex
-          min-w-0
-          max-w-full
-          flex-[1_1]
-          flex-col
-          items-center
-          gap-4
-          md:max-w-2xl
-          lg:max-w-3xl;
+        min-w-0
+        max-w-full
+        flex-[1_1]
+        flex-col
+        items-center
+        gap-4
+        md:max-w-2xl
+        lg:max-w-3xl;
 
       > div {
         @apply w-full
@@ -154,9 +154,9 @@
 
       > p {
         @apply text-center
-            text-sm
-            text-neutral-800
-            dark:text-neutral-200;
+          text-sm
+          text-neutral-800
+          dark:text-neutral-200;
       }
     }
   }

apps/site/styles/effects.css

@@ -21,7 +21,7 @@
 
   & img {
     @apply h-auto
-    w-24
-    md:w-48;
+      w-24
+      md:w-48;
   }
 }

packages/ui-components/.stylelintrc.mjs

@@ -23,7 +23,11 @@ const ONLY_ALLOW_CAMEL_CASE_SELECTORS = [
 
 export default {
   extends: ['stylelint-config-standard'],
-  plugins: ['stylelint-order', 'stylelint-selector-bem-pattern'],
+  plugins: [
+    'stylelint-order',
+    'stylelint-selector-bem-pattern',
+    './stylelint.plugin.mjs',
+  ],
   rules: {
     // Enforces Element Class Names to be camelCase
     'selector-class-pattern': ONLY_ALLOW_CAMEL_CASE_SELECTORS,
@@ -45,5 +49,6 @@ export default {
     'import-notation': 'string',
     // Allow the `@apply` at rule as its part of Tailwind
     'at-rule-no-deprecated': [true, { ignoreAtRules: CUSTOM_AT_RULES }],
+    'ui-components/one-tailwind-token-per-line': true,
   },
 };

packages/ui-components/Common/Blockquote/index.module.css

@@ -1,10 +1,26 @@
 @reference "../../styles/index.css";
 
 .wrapper {
-  @apply flex max-w-2xl flex-col items-start gap-4 self-stretch border-l-2 border-green-600 py-2 pl-5 text-lg font-semibold text-neutral-900 dark:border-green-400 dark:text-white;
+  @apply flex
+    max-w-2xl
+    flex-col
+    items-start
+    gap-4
+    self-stretch
+    border-l-2
+    border-green-600
+    py-2
+    pl-5
+    text-lg
+    font-semibold
+    text-neutral-900
+    dark:border-green-400
+    dark:text-white;
 
   & cite {
-    @apply font-regular text-base not-italic;
+    @apply font-regular
+      text-base
+      not-italic;
 
     &::before {
       @apply content-['—_'];

packages/ui-components/Common/Breadcrumbs/BreadcrumbItem/index.module.css

@@ -1,27 +1,41 @@
 @reference "../../../styles/index.css";
 
 .item {
-  @apply flex max-w-fit items-center gap-5 truncate text-sm font-medium;
+  @apply flex
+    max-w-fit
+    items-center
+    gap-5
+    truncate
+    text-sm
+    font-medium;
 
   &:last-child {
     @apply w-full;
   }
 
   a {
-    @apply shrink grow;
+    @apply shrink
+      grow;
   }
 
   &,
   > a,
   > a:hover {
-    @apply text-neutral-800 motion-safe:transition-colors dark:text-neutral-200;
+    @apply text-neutral-800
+      motion-safe:transition-colors
+      dark:text-neutral-200;
   }
 
   &.visuallyHidden {
     @apply hidden;
   }
 
   .separator {
-    @apply size-4 max-w-fit shrink-0 grow text-neutral-600 dark:text-neutral-400;
+    @apply size-4
+      max-w-fit
+      shrink-0
+      grow
+      text-neutral-600
+      dark:text-neutral-400;
   }
 }

packages/ui-components/Common/Breadcrumbs/BreadcrumbLink/index.module.css

@@ -1,13 +1,22 @@
 @reference "../../../styles/index.css";
 
 .link {
-  @apply max-w-fit truncate;
+  @apply max-w-fit
+    truncate;
 
   &.active {
-    @apply rounded bg-green-600 px-2 py-1 font-semibold text-white motion-safe:transition-colors dark:text-white;
+    @apply rounded
+      bg-green-600
+      px-2
+      py-1
+      font-semibold
+      text-white
+      motion-safe:transition-colors
+      dark:text-white;
 
     &:hover {
-      @apply bg-green-700 text-white;
+      @apply bg-green-700
+        text-white;
     }
   }
 }

packages/ui-components/Common/Breadcrumbs/BreadcrumbRoot/index.module.css

@@ -1,5 +1,9 @@
 @reference "../../../styles/index.css";
 
 .list {
-  @apply xs:w-full flex w-screen gap-5 px-6;
+  @apply xs:w-full
+    flex
+    w-screen
+    gap-5
+    px-6;
 }

packages/ui-components/Common/LanguageDropDown/index.module.css

@@ -29,7 +29,8 @@
 
   > div {
     @apply max-h-80
-      w-48 overflow-y-auto;
+      w-48
+      overflow-y-auto;
   }
 }
 
@@ -47,5 +48,6 @@
 }
 
 .currentDropDown {
-  @apply bg-green-600 text-white;
+  @apply bg-green-600
+    text-white;
 }

packages/ui-components/Common/Tabs/index.module.css

@@ -35,7 +35,7 @@
 
         .tabSecondaryLabel {
           @apply text-green-800
-          dark:text-green-600;
+            dark:text-green-600;
         }
       }
     }

packages/ui-components/stylelint.plugin.mjs

@@ -0,0 +1,116 @@
+import stylelint from 'stylelint';
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages },
+} = stylelint;
+
+const name = 'ui-components/one-tailwind-token-per-line';
+
+const messages = ruleMessages(name, {
+  className: tokens =>
+    `Each line should contain only one Tailwind token; "${tokens}"`,
+  spacing: tokens =>
+    `Each class used with @apply should be indented by 2 spaces on a new line; ${tokens}`,
+});
+
+const meta = {
+  url: 'https://github.com/nodejs/nodejs.org/blob/main/COLLABORATOR_GUIDE.md#styling-a-component',
+  fixable: true,
+};
+
+/**
+ * Adjusts the class names in the rule by cleaning and adding proper indentation.
+ *
+ * @param {Object} rule - The rule object containing the class names to be processed.
+ * @param {string} rule.params - The class names as a string to be formatted.
+ * @param {Object} rule.raws - The raw data of the rule.
+ * @param {string} rule.raws.before - The raw string before to the @apply rule.
+ * @returns {Object|null} The modified rule with properly formatted class names, or null if the rule is invalid.
+ */
+const indentClassNames = rule => {
+  // Ensure that the rule contains necessary properties
+  if (!rule || !rule.params || !rule.raws || !rule.raws.before) {
+    return null;
+  }
+
+  const indent = ' '.repeat(rule.raws.before.length + 1);
+
+  // Clean and split the class names
+  const cleanedClasses = cleanClassNames(rule.params);
+
+  // Apply the indentation and join the class names back together
+  rule.params = applyIndentation(cleanedClasses, indent);
+
+  return rule;
+};
+
+/**
+ * Cleans the input string by removing unnecessary whitespace and newlines.
+ *
+ * @param {string} params - The class names string to be cleaned.
+ * @returns {string} The cleaned class names string.
+ */
+const cleanClassNames = params => {
+  return params
+    .replace(/\n+/g, '') // Remove new lines
+    .replace(/\s+/g, ' ') // Replace multiple spaces with a single space
+    .trim(); // Trim leading/trailing spaces
+};
+
+/**
+ * Applies the correct indentation to each class name in the string.
+ *
+ * @param {string} classes - The cleaned class names as a string.
+ * @param {string} indent - The string used for indentation.
+ * @returns {string} The class names string with applied indentation.
+ */
+const applyIndentation = (classes, indent) => {
+  return classes
+    .split(' ') // Split into an array of class names
+    .map(className => indent + className) // Add indentation to each class
+    .join('\n') // Join with new lines
+    .trim(); // Remove extra space at the end
+};
+
+/** @type {import('stylelint').Rule} */
+const rule = () => (root, result) => {
+  root.walkAtRules('apply', rule => {
+    if (!rule.params.includes(' ')) {
+      // If there are no spaces in the params, we don't need to check anything
+      return;
+    }
+
+    // Since we use 2 spaces for indentation, each line in the apply rule
+    // should be indented with two extra whitespaces.
+    const classes = rule.params.split(`${rule.raws.before}  `);
+    const classNames = classes.join('');
+
+    // Check if the params contain any spaces
+    if (classNames.includes(' ')) {
+      if (classNames.includes('\n')) {
+        return report({
+          ruleName: name,
+          result: result,
+          message: messages.spacing(JSON.stringify(rule.params)),
+          node: rule,
+          fix: indentClassNames(rule),
+        });
+      }
+
+      return report({
+        ruleName: name,
+        result,
+        message: messages.className(rule.params),
+        node: rule,
+        fix: indentClassNames(rule),
+      });
+    }
+  });
+};
+
+rule.ruleName = name;
+rule.messages = messages;
+rule.meta = meta;
+
+export default createPlugin(name, rule);