feat(eslint-rules): add consistent-base-hook rule for v9 base hooks

packages/eslint-plugin/src/internal.js

@@ -35,6 +35,7 @@ const __internal = {
           /** @type {import('eslint').Linter.RulesRecord} */
           rules: {
             '@nx/workspace-consistent-callback-type': 'error',
+            '@nx/workspace-consistent-base-hook': 'error',
             '@nx/workspace-no-restricted-globals': restrictedGlobals.react,
             '@nx/workspace-no-missing-jsx-pragma': ['error', { runtime: 'automatic' }],
           },

packages/react-components/react-menu/library/src/components/MenuTrigger/useMenuTrigger.ts

@@ -75,6 +75,7 @@ export type UseMenuTriggerBaseOptions = {
  *
  * @public
  */
+// eslint-disable-next-line @nx/workspace-consistent-base-hook -- legacy: second param is `options` instead of `ref`; refactor pending
 export const useMenuTriggerBase_unstable = (
   props: MenuTriggerProps,
   options?: UseMenuTriggerBaseOptions,

packages/react-components/react-tags/library/src/components/TagGroup/useTagGroup.ts

@@ -38,6 +38,7 @@ export const useTagGroupBase_unstable = (
 
   const innerRef = React.useRef<HTMLElement>(undefined);
   const { targetDocument } = useFluent();
+  // eslint-disable-next-line @nx/workspace-consistent-base-hook -- legacy: tabster usage should be moved out of base hook
   const { findNextFocusable, findPrevFocusable } = useFocusFinders();
 
   const [items, setItems] = useControllableState<Array<TagValue>>({
@@ -80,6 +81,7 @@ export const useTagGroupBase_unstable = (
     }),
   );
 
+  // eslint-disable-next-line @nx/workspace-consistent-base-hook -- legacy: tabster usage should be moved out of base hook
   const arrowNavigationProps = useArrowNavigationGroup({
     circular: true,
     axis: 'both',

packages/react-components/react-tooltip/library/src/components/Tooltip/useTooltipBase.tsx

@@ -35,7 +35,7 @@ import { Escape } from '@fluentui/keyboard-keys';
  * @param props - props from this instance of Tooltip
  */
 export const useTooltipBase_unstable = (props: TooltipBaseProps): TooltipBaseState => {
-  'use no memo';
+  ('use no memo');
 
   const context = useTooltipVisibility();
   const isServerSideRender = useIsSSR();

tools/eslint-rules/index.ts

@@ -4,6 +4,7 @@ import {
   RULE_NAME as consistentCallbackTypeName,
   rule as consistentCallbackType,
 } from './rules/consistent-callback-type';
+import { RULE_NAME as consistentBaseHookName, rule as consistentBaseHook } from './rules/consistent-base-hook';
 
 /**
  * Import your custom workspace rules at the top of this file.
@@ -32,6 +33,7 @@ module.exports = {
    */
   rules: {
     [consistentCallbackTypeName]: consistentCallbackType,
+    [consistentBaseHookName]: consistentBaseHook,
     [noRestrictedGlobalsName]: noRestrictedGlobals,
     [noMissingJsxPragmaName]: noMissingJsxPragma,
   },

tools/eslint-rules/rules/consistent-base-hook.spec.ts

@@ -0,0 +1,248 @@
+import { RuleTester } from '@typescript-eslint/rule-tester';
+import { rule, RULE_NAME } from './consistent-base-hook';
+
+const ruleTester = new RuleTester();
+
+ruleTester.run(RULE_NAME, rule, {
+  valid: [
+    // Valid base hook: 2 Identifier params, no forbidden imports.
+    {
+      code: `
+        import * as React from 'react';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          return { props, ref };
+        };
+      `,
+    },
+    // Valid base hook declared as FunctionDeclaration.
+    {
+      code: `
+        import { Ref } from 'react';
+        export function useThingBase_unstable(props, ref: Ref<HTMLElement>) {
+          return { props, ref };
+        }
+      `,
+    },
+    // Valid base hook with only `props` (ref is optional).
+    {
+      code: `
+        export const useThingBase_unstable = (props) => {
+          return { props };
+        };
+      `,
+    },
+    // Forbidden import exists but is only used by a non-base hook in the same file.
+    {
+      code: `
+        import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          return { props, ref };
+        };
+        export const useThing_unstable = (props, ref) => {
+          const nav = useArrowNavigationGroup({});
+          return { ...useThingBase_unstable(props, ref), nav };
+        };
+      `,
+    },
+    // Non-base hook is not subject to the param-shape constraint.
+    {
+      code: `
+        export const useThing_unstable = (props, ref, extra) => {
+          return { props, ref, extra };
+        };
+      `,
+    },
+    // Allowlist opt-out: a specific imported name is permitted inside base hooks.
+    {
+      code: `
+        import { useFocusFinders } from '@fluentui/react-tabster';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          const finders = useFocusFinders();
+          return { props, ref, finders };
+        };
+      `,
+      options: [
+        {
+          forbiddenPackages: [{ name: '@fluentui/react-tabster', allow: ['useFocusFinders'] }],
+        },
+      ],
+    },
+    // Default allowlist: `useFocusWithin` and `useFocusVisible` from `@fluentui/react-tabster` are permitted inside base hooks.
+    {
+      code: `
+        import { useFocusWithin, useFocusVisible } from '@fluentui/react-tabster';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLSpanElement>) => {
+          useFocusVisible();
+          return { props, ref: useFocusWithin<HTMLSpanElement>() };
+        };
+      `,
+    },
+    // `keyborg` is not forbidden by default — bindings imported from it are allowed inside base hooks.
+    {
+      code: `
+        import { createKeyborg, KEYBORG_FOCUSIN } from 'keyborg';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          return { kb: createKeyborg(window), evt: KEYBORG_FOCUSIN };
+        };
+      `,
+    },
+    // Identifier with the same local name as a forbidden import alias does not collide via scope analysis.
+    {
+      code: `
+        import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+        export const useThing_unstable = (props, ref) => {
+          return useArrowNavigationGroup({});
+        };
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          const useArrowNavigationGroup = () => 1;
+          return { value: useArrowNavigationGroup() };
+        };
+      `,
+    },
+  ],
+  invalid: [
+    // Too few params (0).
+    {
+      code: `
+        export const useThingBase_unstable = () => ({});
+      `,
+      errors: [{ messageId: 'invalidParamCount', data: { hookName: 'useThingBase_unstable', actual: 0 } }],
+    },
+    // Too many params.
+    {
+      code: `
+        export const useThingBase_unstable = (props, ref, extra) => ({ props, ref, extra });
+      `,
+      errors: [{ messageId: 'invalidParamCount', data: { hookName: 'useThingBase_unstable', actual: 3 } }],
+    },
+    // Wrong param names.
+    {
+      code: `
+        export const useThingBase_unstable = (p, r) => ({ p, r });
+      `,
+      errors: [
+        {
+          messageId: 'invalidParamName',
+          data: { hookName: 'useThingBase_unstable', index: 1, expected: 'props', actual: 'p' },
+        },
+        {
+          messageId: 'invalidParamName',
+          data: { hookName: 'useThingBase_unstable', index: 2, expected: 'ref', actual: 'r' },
+        },
+      ],
+    },
+    // ObjectPattern for `props` is not allowed.
+    {
+      code: `
+        export const useThingBase_unstable = ({ a }, ref: React.Ref<HTMLElement>) => ({ a, ref });
+      `,
+      errors: [
+        {
+          messageId: 'invalidParamName',
+          data: { hookName: 'useThingBase_unstable', index: 1, expected: 'props', actual: '{ ... }' },
+        },
+      ],
+    },
+    // `ref` parameter without a type annotation.
+    {
+      code: `
+        export const useThingBase_unstable = (props, ref) => ({ props, ref });
+      `,
+      errors: [
+        {
+          messageId: 'invalidRefType',
+          data: { hookName: 'useThingBase_unstable', actual: '<missing type annotation>' },
+        },
+      ],
+    },
+    // `ref` parameter typed as something other than React.Ref.
+    {
+      code: `
+        export const useThingBase_unstable = (props, ref: HTMLElement) => ({ props, ref });
+      `,
+      errors: [
+        {
+          messageId: 'invalidRefType',
+          data: { hookName: 'useThingBase_unstable', actual: 'HTMLElement' },
+        },
+      ],
+    },
+    // `ref` parameter typed as React.ForwardedRef (must be React.Ref).
+    {
+      code: `
+        export const useThingBase_unstable = (props, ref: React.ForwardedRef<HTMLElement>) => ({ props, ref });
+      `,
+      errors: [
+        {
+          messageId: 'invalidRefType',
+          data: { hookName: 'useThingBase_unstable', actual: 'React.ForwardedRef' },
+        },
+      ],
+    },
+    // Body uses a binding imported from @fluentui/react-tabster.
+    {
+      code: `
+        import { useArrowNavigationGroup } from '@fluentui/react-tabster';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          const nav = useArrowNavigationGroup({});
+          return { props, ref, nav };
+        };
+      `,
+      errors: [
+        {
+          messageId: 'forbiddenPackageUsage',
+          data: {
+            hookName: 'useThingBase_unstable',
+            importedName: 'useArrowNavigationGroup',
+            package: '@fluentui/react-tabster',
+          },
+        },
+      ],
+    },
+    // Body uses a binding imported from tabster, even when aliased.
+    {
+      code: `
+        import { getTabsterAttribute as gta } from 'tabster';
+        export function useThingBase_unstable(props, ref: React.Ref<HTMLElement>) {
+          return { attr: gta({}) };
+        }
+      `,
+      errors: [
+        {
+          messageId: 'forbiddenPackageUsage',
+          data: {
+            hookName: 'useThingBase_unstable',
+            importedName: 'getTabsterAttribute',
+            package: 'tabster',
+          },
+        },
+      ],
+    },
+    // Allowlist excludes one name; siblings still error.
+    {
+      code: `
+        import { useFocusFinders, useArrowNavigationGroup } from '@fluentui/react-tabster';
+        export const useThingBase_unstable = (props, ref: React.Ref<HTMLElement>) => {
+          const finders = useFocusFinders();
+          const nav = useArrowNavigationGroup({});
+          return { props, ref, finders, nav };
+        };
+      `,
+      options: [
+        {
+          forbiddenPackages: [{ name: '@fluentui/react-tabster', allow: ['useFocusFinders'] }],
+        },
+      ],
+      errors: [
+        {
+          messageId: 'forbiddenPackageUsage',
+          data: {
+            hookName: 'useThingBase_unstable',
+            importedName: 'useArrowNavigationGroup',
+            package: '@fluentui/react-tabster',
+          },
+        },
+      ],
+    },
+  ],
+});