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" | "replaceIconWithJsx" | "replaceStackWithFlex" | "replaceFocusZoneWithTabster", {
+        preview?: 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,40 @@
+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';`,
+    },
+  ],
+  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: 'replaceFluent8With9',
+          data: { fluent8: 'DatePicker', fluent9: 'DatePicker', package: '@fluentui/react-datepicker-compat' },
+        },
+      ],
+    },
+  ],
+});

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

@@ -0,0 +1,158 @@
+import { createRule } from './utils/create-rule';
+
+export const RULE_NAME = 'prefer-fluentui-v9';
+
+type Options = Array<{}>;
+
+type MessageIds = 'replaceFluent8With9' | 'replaceIconWithJsx' | 'replaceStackWithFlex' | 'replaceFocusZoneWithTabster';
+
+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: {},
+      },
+    ],
+    messages: {
+      replaceFluent8With9: `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. More details are available at https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-components-flex-stack--docs`,
+      replaceFocusZoneWithTabster: `Avoid using {{ fluent8 }} from '@fluentui/react', as this package has already migrated to Fluent UI 9. Use the equivalent [Tabster](https://tabster.io/) hook instead.`,
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    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;
+              case 'FocusTrapZone':
+              case 'FocusZone':
+                context.report({ node, messageId: 'replaceFocusZoneWithTabster', data: { fluent8: name } });
+                break;
+              default:
+                if (isMigration(name)) {
+                  const migration = getMigrationData(MIGRATIONS[name]);
+
+                  context.report({
+                    node,
+                    messageId: 'replaceFluent8With9',
+                    data: {
+                      fluent8: name,
+                      fluent9: migration.component,
+                      package: migration.package,
+                    },
+                  });
+                }
+            }
+          }
+        }
+      },
+    };
+  },
+});
+
+type Migration = string | { component: string; package: string };
+
+/**
+ * Migrations from Fluent 8 components to Fluent 9 components.
+ * @see https://react.fluentui.dev/?path=/docs/concepts-migration-from-v8-component-mapping--docs
+ */
+const MIGRATIONS = {
+  makeStyles: 'makeStyles',
+  ActionButton: 'Button',
+  Announced: 'useAnnounce',
+  Breadcrumb: 'Breadcrumb',
+  Button: 'Button',
+  Callout: 'Popover',
+  Calendar: { component: 'Calendar', package: '@fluentui/react-calendar-compat' },
+  CommandBar: 'Toolbar',
+  CommandBarButton: 'Toolbar',
+  CommandButton: 'MenuButton',
+  CompoundButton: 'CompoundButton',
+  Checkbox: 'Checkbox',
+  ChoiceGroup: 'RadioGroup',
+  Coachmark: 'TeachingPopover',
+  ComboBox: 'Combobox',
+  ContextualMenu: 'Menu',
+  DefaultButton: 'Button',
+  DatePicker: { component: 'DatePicker', package: '@fluentui/react-datepicker-compat' },
+  DetailsList: 'DataGrid',
+  Dialog: 'Dialog',
+  DocumentCard: 'Card',
+  Dropdown: 'Dropdown',
+  Fabric: 'FluentProvider',
+  Facepile: 'AvatarGroup',
+  FocusTrapZone: 'Tabster',
+  FocusZone: 'Tabster',
+  GroupedList: 'Tree',
+  HoverCard: 'Popover', // Not a direct equivalent; but could be used with custom behavior.
+  IconButton: 'Button',
+  Image: 'Image',
+  Keytips: { component: 'Keytips', package: '@fluentui-contrib/react-keytips' },
+  Label: 'Label',
+  Layer: 'Portal',
+  Link: 'Link',
+  MessageBar: 'MessageBar',
+  Modal: 'Dialog',
+  OverflowSet: 'Overflow',
+  Overlay: 'Portal',
+  Panel: 'Drawer',
+  PeoplePicker: 'TagPicker',
+  Persona: 'Persona',
+  Pivot: 'TabList',
+  PivotItem: 'Tab',
+  ProgressIndicator: 'ProgressBar',
+  Rating: 'Rating',
+  SearchBox: 'SearchBox',
+  Separator: 'Divider',
+  Shimmer: 'Skeleton',
+  Slider: 'Slider',
+  SplitButton: 'SplitButton',
+  SpinButton: 'SpinButton',
+  Spinner: 'Spinner',
+  Stack: 'StackShim',
+  SwatchColorPicker: 'SwatchPicker',
+  TagPicker: 'TagPicker',
+  TeachingBubble: 'TeachingPopover',
+  Text: 'Text',
+  TextField: 'Input',
+  TimePicker: { component: 'TimePicker', package: '@fluentui/react-timepicker-compat' },
+  ToggleButton: 'ToggleButton',
+  Toggle: 'Switch',
+  Tooltip: 'Tooltip',
+} 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;
+
+/**
+ * Get the component and package name to use for a migration.
+ */
+const getMigrationData = (migration: Migration) => {
+  return typeof migration === 'string' ? { component: migration, package: '@fluentui/react-components' } : migration;
+};

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}`,
+);

packages/react-components/eslint-plugin-react-components/tsconfig.spec.json

@@ -1,7 +1,8 @@
 {
   "extends": "./tsconfig.json",
   "compilerOptions": {
-    "module": "CommonJS",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "outDir": "dist",
     "types": ["jest", "node"]
   },