feat(eslint-plugin-react-components): add prefer-fluentui-v9 rule

change/@fluentui-eslint-plugin-react-components-1c2bc691-c857-43cf-9806-ffe8d0d058c0.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add prefer-fluentui-v9 rule",
+  "packageName": "@fluentui/eslint-plugin-react-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/eslint-plugin-react-components/README.md

@@ -40,21 +40,46 @@ module.exports = {
 };
 ```
 
-1. Or configure individual rules manually:
+2. Or configure individual rules manually:
 
 ```js
 module.exports = {
   plugins: ['@fluentui/react-components'],
   rules: {
-    '@fluentui/react-components/rule-name-1': 'error',
-    '@fluentui/react-components/rule-name-2': 'warn',
+    '@fluentui/react-components/prefer-fluentui-v9': 'warn',
   },
 };
 ```
 
 ## Available Rules
 
-TBD
+### prefer-fluentui-v9
+
+This rule ensures the use of Fluent UI v9 counterparts for Fluent UI v8 components.
+
+#### Options
+
+- `unstable` (boolean): Whether to enforce Fluent UI v9 preview component migrations.
+
+#### Examples
+
+**✅ Do**
+
+```js
+// Import and use components that have been already migrated to Fluent UI v9
+import { Button } from '@fluentui/react-components';
+
+const Component = () => <Button>...</Button>;
+```
+
+**❌ Don't**
+
+```js
+// Avoid importing and using Fluent UI V8 components that have already been migrated to Fluent UI V9.
+import { DefaultButton } from '@fluentui/react';
+
+const Component = () => <DefaultButton>...</DefaultButton>;
+```
 
 ## License
 

packages/react-components/eslint-plugin-react-components/etc/eslint-plugin-react-components.api.md

@@ -4,21 +4,29 @@
 
 ```ts
 
+import { RuleListener } from '@typescript-eslint/utils/dist/ts-eslint';
+import { RuleModule } from '@typescript-eslint/utils/dist/ts-eslint';
+
 // @public (undocumented)
-const plugin: {
+export const plugin: {
     meta: {
         name: string;
         version: string;
     };
     configs: {
         recommended: {
             plugins: string[];
-            rules: {};
+            rules: {
+                "@fluentui/react-components/prefer-fluentui-v9": string;
+            };
         };
     };
-    rules: {};
+    rules: {
+        "prefer-fluentui-v9": RuleModule<"replaceFluent8With9" | "replaceFluent8With9Unstable" | "replaceIconWithJsx" | "replaceStackWithFlex", {
+        unstable?: boolean | undefined;
+        }[], unknown, RuleListener>;
+    };
 };
-export default plugin;
 
 // (No @packageDocumentation comment for this package)
 

packages/react-components/eslint-plugin-react-components/src/index.ts

@@ -1,20 +1,21 @@
 import { name, version } from '../package.json';
+import { RULE_NAME as preferFluentUIV9Name, rule as preferFluentUIV9 } from './rules/prefer-fluentui-v9';
 
 const allRules = {
-  // add all rules here
+  [preferFluentUIV9Name]: preferFluentUIV9,
 };
 
 const configs = {
   recommended: {
     plugins: [name],
     rules: {
-      // add all recommended rules here
+      [`@fluentui/react-components/${preferFluentUIV9Name}`]: 'warn',
     },
   },
 };
 
 // Plugin definition
-const plugin = {
+export const plugin = {
   meta: {
     name,
     version,
@@ -33,4 +34,4 @@ Object.assign(configs, {
   },
 });
 
-export default plugin;
+module.exports = plugin;

packages/react-components/eslint-plugin-react-components/src/rules/prefer-fluentui-v9.spec.ts

@@ -0,0 +1,44 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { RULE_NAME, rule } from './prefer-fluentui-v9';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run(RULE_NAME, rule, {
+  valid: [
+    {
+      code: `import type { IDropdownOption } from '@fluentui/react';`,
+    },
+    {
+      code: `import type { ITheme } from '@fluentui/react';`,
+    },
+    {
+      code: `import { ThemeProvider } from '@fluentui/react';`,
+    },
+    {
+      code: `import { Button } from '@fluentui/react-components';`,
+    },
+    {
+      code: `import { Rating } from '@fluentui/react';`,
+      options: [{ unstable: false }],
+    },
+  ],
+  invalid: [
+    {
+      code: `import { Dropdown, Icon } from '@fluentui/react';`,
+      errors: [{ messageId: 'replaceFluent8With9' }, { messageId: 'replaceIconWithJsx' }],
+    },
+    {
+      code: `import { Stack } from '@fluentui/react';`,
+      errors: [{ messageId: 'replaceStackWithFlex' }],
+    },
+    {
+      code: `import { DatePicker } from '@fluentui/react';`,
+      errors: [{ messageId: 'replaceFluent8With9Unstable' }],
+    },
+    {
+      code: `import { Rating } from '@fluentui/react';`,
+      options: [{ unstable: true }],
+      errors: [{ messageId: 'replaceFluent8With9Unstable' }],
+    },
+  ],
+});

packages/react-components/eslint-plugin-react-components/src/rules/prefer-fluentui-v9.ts

@@ -0,0 +1,192 @@
+import { createRule } from './utils/create-rule';
+
+export const RULE_NAME = 'prefer-fluentui-v9';
+
+type Options = Array<{
+  /** Whether to enforce Fluent UI v9 preview component migrations. */
+  unstable?: boolean;
+}>;
+
+type MessageIds = 'replaceFluent8With9' | 'replaceFluent8With9Unstable' | 'replaceIconWithJsx' | 'replaceStackWithFlex';
+
+export const rule = createRule<Options, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'This rule ensures the use of Fluent UI v9 counterparts for Fluent UI v8 components.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          unstable: { type: 'boolean' },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      replaceFluent8With9: `Avoid importing {{ fluent8 }} from '@fluentui/react', as this package has already migrated to Fluent UI 9. Import {{ fluent9 }} from '@fluentui/react-components' instead.`,
+      replaceFluent8With9Unstable: `Avoid importing {{ fluent8 }} from '@fluentui/react', as this package has started migration to Fluent UI 9. Import {{ fluent9 }} from '{{ package }}' instead.`,
+      replaceIconWithJsx: `Avoid using Icon from '@fluentui/react', as this package has already migrated to Fluent UI 9. Use a JSX SVG icon from '@fluentui/react-icons' instead.`,
+      replaceStackWithFlex: `Avoid using Stack from '@fluentui/react', as this package has already migrated to Fluent UI 9. Use native CSS flexbox instead.`,
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const { unstable = false } = context.options[0] ?? {};
+
+    return {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      ImportDeclaration(node) {
+        if (node.source.value !== '@fluentui/react') {
+          return;
+        }
+
+        for (const specifier of node.specifiers) {
+          if (specifier.type === 'ImportSpecifier' && specifier.imported.type === 'Identifier') {
+            const name = specifier.imported.name;
+
+            switch (name) {
+              case 'Icon':
+                context.report({ node, messageId: 'replaceIconWithJsx' });
+                break;
+              case 'Stack':
+                context.report({ node, messageId: 'replaceStackWithFlex' });
+                break;
+              default:
+                if (isMigration(name)) {
+                  context.report({
+                    node,
+                    messageId: 'replaceFluent8With9',
+                    data: {
+                      fluent8: name,
+                      fluent9: MIGRATIONS[name],
+                    },
+                  });
+                } else if (isCompatMigration(name)) {
+                  context.report({
+                    node,
+                    messageId: 'replaceFluent8With9Unstable',
+                    data: {
+                      fluent8: name,
+                      fluent9: COMPAT_MIGRATIONS[name].component,
+                      package: COMPAT_MIGRATIONS[name].package,
+                    },
+                  });
+                } else if (isPreviewMigration(name) && unstable) {
+                  context.report({
+                    node,
+                    messageId: 'replaceFluent8With9Unstable',
+                    data: {
+                      fluent8: name,
+                      fluent9: PREVIEW_MIGRATIONS[name].component,
+                      package: PREVIEW_MIGRATIONS[name].package,
+                    },
+                  });
+                }
+                break;
+            }
+          }
+        }
+      },
+    };
+  },
+});
+
+type Migration = string | { component: string; package: string };
+
+/**
+ * Migrations from Fluent 8 components to Fluent 9 components as of Fluent UI 9.46.3
+ * @see https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-component-mapping--page
+ */
+const MIGRATIONS = {
+  mergeStyles: 'makeStyles',
+  ActionButton: 'Button',
+  Announced: 'useAnnounce',
+  Breadcrumb: 'Breadcrumb',
+  CommandBar: 'Toolbar',
+  CommandBarButton: 'ToolbarButton',
+  CommandButton: 'MenuButton',
+  CompoundButton: 'CompoundButton',
+  Callout: 'Popover',
+  Checkbox: 'Checkbox',
+  ChoiceGroup: 'Radio',
+  ComboBox: 'Dropdown',
+  ContextualMenu: 'Menu',
+  DefaultButton: 'Button',
+  DetailsList: 'DataGrid',
+  Dialog: 'Dialog',
+  DocumentCard: 'Card',
+  Dropdown: 'Dropdown',
+  Facepile: 'AvatarGroup',
+  GroupedList: 'Tree',
+  IconButton: 'Button',
+  Image: 'Image',
+  Label: 'Label',
+  Layer: 'Portal',
+  Link: 'Link',
+  MessageBar: 'MessageBar',
+  Modal: 'Dialog',
+  OverflowSet: 'Overflow',
+  Overlay: 'Portal',
+  Panel: 'Drawer',
+  Popup: 'Dialog',
+  PrimaryButton: 'Button',
+  Persona: 'Avatar',
+  Pivot: 'TabList',
+  PivotItem: 'Tab',
+  ProgressIndicator: 'ProgressBar',
+  Separator: 'Divider',
+  Shimmer: 'Skeleton',
+  Slider: 'Slider',
+  SplitButton: 'SplitButton',
+  SpinButton: 'SpinButton',
+  Spinner: 'Spinner',
+  Text: 'Text',
+  TextField: 'Input',
+  ToggleButton: 'ToggleButton',
+  Toggle: 'Switch',
+  Tooltip: 'Tooltip',
+  TooltipHost: 'Tooltip',
+  VerticalDivider: 'Divider',
+} satisfies Record<string, Migration>;
+
+/**
+ * Compatibility migrations for certain components.
+ * @see https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-component-mapping--page
+ */
+const COMPAT_MIGRATIONS = {
+  DatePicker: { component: 'DatePicker', package: '@fluentui/react-datepicker-compat' },
+  TimePicker: { component: 'TeachingPopover', package: '@fluentui/react-timepicker-compat' },
+} satisfies Record<string, Migration>;
+
+/**
+ * Preview migrations for certain components.
+ * @see https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-component-mapping--page
+ */
+const PREVIEW_MIGRATIONS = {
+  Rating: { component: 'Rating', package: '@fluentui/react-rating-preview' },
+  TeachingBubble: { component: 'TeachingPopover', package: '@fluentui/react-teaching-popover-preview' },
+} satisfies Record<string, Migration>;
+
+/**
+ * Checks if a component name is in the MIGRATIONS list.
+ * @param name - The name of the component.
+ * @returns True if the component is in the MIGRATIONS list, false otherwise.
+ */
+const isMigration = (name: string): name is keyof typeof MIGRATIONS => name in MIGRATIONS;
+
+/**
+ * Checks if a component name is in the COMPAT_MIGRATIONS list.
+ * @param name - The name of the component.
+ * @returns True if the component is in the COMPAT_MIGRATIONS list, false otherwise.
+ */
+const isCompatMigration = (name: string): name is keyof typeof COMPAT_MIGRATIONS => name in COMPAT_MIGRATIONS;
+
+/**
+ * Checks if a component name is in the PREVIEW_MIGRATIONS list.
+ * @param name - The name of the component.
+ * @returns True if the component is in the PREVIEW_MIGRATIONS list, false otherwise.
+ */
+const isPreviewMigration = (name: string): name is keyof typeof PREVIEW_MIGRATIONS => name in PREVIEW_MIGRATIONS;

packages/react-components/eslint-plugin-react-components/src/rules/utils/create-rule.ts

@@ -0,0 +1,9 @@
+import { ESLintUtils } from '@typescript-eslint/utils';
+
+/**
+ * Creates an ESLint rule with a pre-configured URL pointing to the rule's documentation.
+ */
+export const createRule = ESLintUtils.RuleCreator(
+  name =>
+    `https://github.com/microsoft/fluentui/blob/master/packages/react-components/eslint-plugin-react-components/README.md#${name}`,
+);