typescript-eslint · bradzacher · Oct 4, 2022 · Oct 1, 2022 · Oct 4, 2022 · Oct 4, 2022
diff --git a/packages/website/plugins/generated-rule-docs.ts b/packages/website/plugins/generated-rule-docs.ts
@@ -52,20 +52,26 @@ export const generatedRuleDocs: Plugin = () => {
     );
 
     // 2. Add a description of the rule at the top of the file
-    root.children.unshift({
-      children: [
-        {
-          children: meta.docs.description
-            .split(/`(.+?)`/)
-            .map((value, index, array) => ({
-              type: index % 2 === 0 ? 'text' : 'inlineCode',
-              value: index === array.length - 1 ? `${value}.` : value,
-            })),
-          type: 'paragraph',
-        },
-      ],
-      type: 'blockquote',
-    } as mdast.Blockquote);
+    root.children.unshift(
+      {
+        children: [
+          {
+            children: meta.docs.description
+              .split(/`(.+?)`/)
+              .map((value, index, array) => ({
+                type: index % 2 === 0 ? 'text' : 'inlineCode',
+                value: index === array.length - 1 ? `${value}.` : value,
+              })),
+            type: 'paragraph',
+          },
+        ],
+        type: 'blockquote',
+      } as mdast.Blockquote,
+      {
+        type: 'jsx',
+        value: `<rule-attributes name="${file.stem}" />`,
+      } as unist.Node,
+    );
 
     // 3. Add a notice about formatting rules being 🤢
     if (meta.type === 'layout') {
@@ -82,19 +88,7 @@ export const generatedRuleDocs: Plugin = () => {
       root.children.unshift(warningNode);
     }
 
-    // 4. Add a rule attributes list before the first h2.
-    const attributesH2Index = root.children.findIndex(
-      child => nodeIsHeading(child) && child.depth === 2,
-    );
-
-    // The actual content will be injected on client side.
-    const attributesNode = {
-      type: 'jsx',
-      value: `<rule-attributes name="${file.stem}" />`,
-    };
-    root.children.splice(attributesH2Index, 0, attributesNode);
-
-    // 5. Make sure the appropriate headers exist to place content under
+    // 4. Make sure the appropriate headers exist to place content under
     const [howToUseH2Index, optionsH2Index] = ((): [number, number] => {
       let howToUseH2Index = root.children.findIndex(
         createH2TextFilter('How to Use'),
@@ -162,7 +156,7 @@ export const generatedRuleDocs: Plugin = () => {
       return [howToUseH2Index, optionsH2Index];
     })();
 
-    // 6. Add a description of how to use / options for the rule
+    // 5. Add a description of how to use / options for the rule
     const optionLevel = meta.docs.recommended === 'error' ? 'error' : 'warn';
 
     if (meta.docs.extendsBaseRule) {
@@ -210,7 +204,12 @@ export const generatedRuleDocs: Plugin = () => {
 };`,
       } as mdast.Code);
     } else {
-      root.children.splice(optionsH2Index, 0, {
+      // For non-extended rules, the code snippet is placed before the first h2
+      // (i.e. at the end of the initial explanation)
+      const firstH2Index = root.children.findIndex(
+        child => nodeIsHeading(child) && child.depth === 2,
+      );
+      root.children.splice(firstH2Index, 0, {
         lang: 'js',
         type: 'code',
         meta: 'title=".eslintrc.cjs"',
@@ -297,7 +296,7 @@ export const generatedRuleDocs: Plugin = () => {
       }
     }
 
-    // 7. Add a notice about coming from ESLint core for extension rules
+    // 6. Add a notice about coming from ESLint core for extension rules
     if (meta.docs.extendsBaseRule) {
       root.children.push({
         children: [
@@ -329,7 +328,7 @@ export const generatedRuleDocs: Plugin = () => {
       } as mdast.Paragraph);
     }
 
-    // 8. Also add a link to view the rule's source and test code
+    // 7. Also add a link to view the rule's source and test code
     root.children.push(
       {
         children: [

diff --git a/packages/website/src/theme/MDXComponents/Feature.module.css b/packages/website/src/theme/MDXComponents/Feature.module.css
@@ -0,0 +1,22 @@
+.feature {
+  background-color: var(--token-background);
+  border-radius: var(--ifm-code-border-radius);
+  box-shadow: var(--ifm-global-shadow-lw);
+  color: var(--token-color) !important;
+  display: flex;
+  flex-basis: 30%;
+  flex-grow: 1;
+  flex-shrink: 3;
+  font-size: 0.8rem;
+  margin: 0 0 1rem;
+  min-width: 15rem;
+  padding: 0.75rem 1rem;
+}
+
+.emoji {
+  margin-right: 0.5rem;
+}
+
+.children {
+  margin: 0;
+}
diff --git a/packages/website/src/theme/MDXComponents/Feature.tsx b/packages/website/src/theme/MDXComponents/Feature.tsx
@@ -0,0 +1,17 @@
+import React from 'react';
+
+import styles from './Feature.module.css';
+
+export interface FeatureProps {
+  children: React.ReactNode;
+  emoji: string;
+}
+
+export function Feature({ children, emoji }: FeatureProps): JSX.Element {
+  return (
+    <div className={styles.feature}>
+      <div className={styles.emoji}>{emoji}</div>
+      <p className={styles.children}>{children}</p>
+    </div>
+  );
+}
diff --git a/packages/website/src/theme/MDXComponents/RuleAttributes.module.css b/packages/website/src/theme/MDXComponents/RuleAttributes.module.css
@@ -1,7 +1,9 @@
-.taskList {
-  list-style: none;
+.features {
+  display: flex;
+  gap: 0 1rem;
+  flex-wrap: wrap;
 }
 
-:not(.taskList > li) > .taskList {
-  padding-left: 0;
+.features + h2 {
+  margin-top: 1rem;
 }
diff --git a/packages/website/src/theme/MDXComponents/RuleAttributes.tsx b/packages/website/src/theme/MDXComponents/RuleAttributes.tsx
@@ -1,73 +1,109 @@
+import type { RuleMetaDataDocs } from '@site/../utils/dist/ts-eslint/Rule';
 import { useRulesMeta } from '@site/src/hooks/useRulesMeta';
-import type { TSESLint } from '@typescript-eslint/utils';
 import React from 'react';
 
+import type { FeatureProps } from './Feature';
+import { Feature } from './Feature';
 import styles from './RuleAttributes.module.css';
 
-export function RuleAttributes({ name }: { name: string }): JSX.Element | null {
+const getRecommendation = (docs: RuleMetaDataDocs): [string, string] => {
+  return docs.recommended === 'strict'
+    ? ['🔒', 'strict']
+    : docs.requiresTypeChecking
+    ? ['🧠', 'recommended-requiring-type-checking']
+    : ['✅', 'recommended'];
+};
+
+export function RuleAttributes({ name }: { name: string }): React.ReactNode {
   const rules = useRulesMeta();
   const rule = rules.find(rule => rule.name === name);
-  if (!rule) {
+  if (!rule?.docs) {
     return null;
   }
+
+  const features: FeatureProps[] = [];
+
+  if (rule.docs.recommended) {
+    const [emoji, recommendation] = getRecommendation(rule.docs);
+    features.push({
+      children: (
+        <>
+          Extending{' '}
+          <a href={`/docs/linting/configs#${recommendation}`} target="_blank">
+            <code className={styles.code}>
+              "plugin:@typescript-eslint/{recommendation}"
+            </code>
+          </a>{' '}
+          in an{' '}
+          <a
+            href="https://eslint.org/docs/latest/user-guide/configuring/configuration-files#extending-configuration-files"
+            target="_blank"
+          >
+            ESLint configuration
+          </a>{' '}
+          enables this rule.
+        </>
+      ),
+      emoji,
+    });
+  }
+
+  if (rule.fixable) {
+    features.push({
+      children: (
+        <>
+          Some problems reported by this rule are automatically fixable by the{' '}
+          <a
+            href="https://eslint.org/docs/latest/user-guide/command-line-interface#--fix"
+            target="_blank"
+          >
+            <code>--fix</code> ESLint command line option
+          </a>
+          .
+        </>
+      ),
+      emoji: '🛠',
+    });
+  }
+
+  if (rule.hasSuggestions) {
+    features.push({
+      children: (
+        <>
+          Some problems reported by this rule are manually fixable by editor{' '}
+          <a
+            href="https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions"
+            target="_blank"
+          >
+            suggestions
+          </a>
+          .
+        </>
+      ),
+      emoji: '💡',
+    });
+  }
+
+  if (rule.docs.requiresTypeChecking) {
+    features.push({
+      children: (
+        <>
+          This rule requires{' '}
+          <a href="/docs/linting/typed-linting" target="_blank">
+            type information
+          </a>{' '}
+          to run.
+        </>
+      ),
+      emoji: '💭',
+    });
+  }
+
   return (
-    <>
-      <h2 id="attributes">Attributes</h2>
-      <ul className={styles.taskList}>
-        <li>
-          <input type="checkbox" disabled checked={!!rule.docs?.recommended} />
-          Included in configs
-          <ul className={styles.taskList}>
-            <li>
-              <input
-                type="checkbox"
-                disabled
-                checked={(
-                  ['error', 'warn'] as (
-                    | TSESLint.RuleRecommendation
-                    | undefined
-                  )[]
-                ).includes(rule.docs?.recommended)}
-              />
-              ✅ Recommended
-            </li>
-            <li>
-              <input
-                type="checkbox"
-                disabled
-                checked={rule.docs?.recommended === 'strict'}
-              />
-              🔒 Strict
-            </li>
-          </ul>
-        </li>
-        <li>
-          <input
-            type="checkbox"
-            disabled
-            checked={!!rule.fixable || rule.hasSuggestions}
-          />
-          Fixable
-          <ul className={styles.taskList}>
-            <li>
-              <input type="checkbox" disabled checked={!!rule.fixable} />
-              🔧 Automated Fixer
-            </li>
-            <li>
-              <input type="checkbox" disabled checked={!!rule.hasSuggestions} />
-              💡 Suggestion Fixer
-            </li>
-          </ul>
-        </li>
-        <li>
-          <input
-            type="checkbox"
-            disabled
-            checked={!!rule.docs?.requiresTypeChecking}
-          />
-          💭 Requires type information
-        </li>
-      </ul>
-    </>
+    <div className={styles.features}>
+      {features.map(feature => (
+        <Feature {...feature} key={feature.emoji} />
+      ))}
+    </div>
   );
 }