feat(react-utilities): add custom RefAttributes interface which is used within ForwardRefComponent to mitigate React.RefAttributes expansion causing breaking changes in v8/v9 mixed context - shipped as patch release in @types/react@18.2.61

change/@fluentui-react-utilities-66a3d122-bdde-45be-a7b3-d6ae2b28a1d6.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add custom RefAttributes interface which is used within ForwardRefComponent to mitigate breaking changes shipped as patch release in @types/react@18.2.61",
+  "packageName": "@fluentui/react-utilities",
+  "email": "martinhochel@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/eslint-plugin/src/configs/react.js

@@ -23,6 +23,8 @@ module.exports = {
     'jsdoc/check-tag-names': [
       'error',
       {
+        // Allow TSDoc tags
+        definedTags: ['remarks'],
         jsxTags: true,
       },
     ],

packages/react-components/react-utilities/etc/react-utilities.api.md

@@ -63,7 +63,7 @@ export type FluentTriggerComponent = {
 };
 
 // @public
-export type ForwardRefComponent<Props> = React_2.ForwardRefExoticComponent<Props & React_2.RefAttributes<InferredElementRefType<Props>>>;
+export type ForwardRefComponent<Props> = React_2.ForwardRefExoticComponent<Props & RefAttributes<InferredElementRefType<Props>>>;
 
 // @public
 export function getEventClientCoords(event: TouchOrMouseEvent): {
@@ -190,6 +190,12 @@ export interface PriorityQueue<T> {
 // @public (undocumented)
 export type ReactTouchOrMouseEvent = React_2.MouseEvent | React_2.TouchEvent;
 
+// @public
+export interface RefAttributes<T> extends React_2.Attributes {
+    // (undocumented)
+    ref?: React_2.Ref<T> | undefined;
+}
+
 // @public
 export type RefObjectFunction<T> = React_2.RefObject<T> & ((value: T | null) => void);
 

packages/react-components/react-utilities/src/compose/index.ts

@@ -8,6 +8,7 @@ export type {
   EventHandler,
   ExtractSlotProps,
   ForwardRefComponent,
+  RefAttributes,
   InferredElementRefType,
   IsSingleton,
   PropsWithoutChildren,

packages/react-components/react-utilities/src/compose/types.test.ts

@@ -1,3 +1,4 @@
+/*  eslint-disable @typescript-eslint/naming-convention */
 import * as React from 'react';
 import type * as Types from './types';
 
@@ -54,6 +55,47 @@ describe(`types`, () => {
       componentEl = { greeting: 123, who: false };
 
       expect(componentEl).toBeDefined();
+
+      //
+      // v9 ForwardRefComponent + RefAttributes with React 18.2.61 types issue
+      //
+
+      // @types/react@18.2.61 introduced a change in the `RefAttributes` type to include `LegacyRef<T>`
+      interface RefAttributesAfterTypesReact18_2_61<T> extends React.Attributes {
+        ref?: React.LegacyRef<T>;
+      }
+
+      // previous change affects forwardRef api
+      function forwardRefAfterTypesReact18_2_61<T, P = {}>(
+        render: React.ForwardRefRenderFunction<T, P>,
+      ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & RefAttributesAfterTypesReact18_2_61<T>> {
+        return null as unknown as React.ForwardRefExoticComponent<
+          React.PropsWithoutRef<P> & RefAttributesAfterTypesReact18_2_61<T>
+        >;
+      }
+
+      type ButtonProps = Types.ComponentProps<{
+        root: NonNullable<Types.Slot<'button'>>;
+
+        icon?: Types.Slot<'span'>;
+      }>;
+      const Button = (_props => {
+        return null;
+      }) as Types.ForwardRefComponent<ButtonProps>;
+
+      const Example = forwardRefAfterTypesReact18_2_61((props: { hello?: string }, _ref) => {
+        const wrong = React.createElement(
+          Button,
+          // @ts-expect-error - Type 'LegacyRef<HTMLButtonElement> | undefined' is not assignable to type 'Ref<HTMLButtonElement> | undefined'. -> Type 'string' is not assignable to type 'Ref<HTMLButtonElement> | undefined'.
+          {
+            ...(props as RefAttributesAfterTypesReact18_2_61<HTMLButtonElement>),
+          },
+        );
+        const correct = React.createElement(Button, { ...(props as Types.RefAttributes<HTMLButtonElement>) });
+
+        return React.createElement(React.Fragment, null, wrong, correct);
+      });
+      console.log(Example);
     });
   });
 });

packages/react-components/react-utilities/src/compose/types.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { SLOT_CLASS_NAME_PROP_SYMBOL, SLOT_ELEMENT_TYPE_SYMBOL, SLOT_RENDER_FUNCTION_SYMBOL } from './constants';
-import { DistributiveOmit, ReplaceNullWithUndefined } from '../utils/types';
+import type { DistributiveOmit, ReplaceNullWithUndefined } from '../utils/types';
 
 export type SlotRenderFunction<Props> = (
   Component: React.ElementType<Props>,
@@ -216,9 +216,15 @@ export type InferredElementRefType<Props> = ObscureEventName extends keyof Props
 
 /**
  * Return type for `React.forwardRef`, including inference of the proper typing for the ref.
+ *
+ * @remarks
+ * {@link React.RefAttributes} is {@link https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/69756 | leaking string references} into `forwardRef` components
+ *  after introducing {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/68720 | RefAttributes Type Extension}, which shipped in `@types/react@18.2.61`
+ * - `forwardRef` component do not support string refs.
+ * - uses custom `RefAttributes` which is compatible with all React versions enforcing no `string` allowance.
  */
 export type ForwardRefComponent<Props> = React.ForwardRefExoticComponent<
-  Props & React.RefAttributes<InferredElementRefType<Props>>
+  Props & RefAttributes<InferredElementRefType<Props>>
 >;
 // A definition like this would also work, but typescript is more likely to unnecessarily expand
 // the props type with this version (and it's likely much more expensive to evaluate)
@@ -289,3 +295,24 @@ export type EventHandler<TData extends EventData<string, unknown>> = (
   ev: React.SyntheticEvent | Event,
   data: TData,
 ) => void;
+
+/**
+ * This type should be used in place of `React.RefAttributes<T>` in all components that specify `ref` prop.
+ *
+ * If user is using React 18 types `>=18.2.61`, they will run into type issues of incompatible refs, using this type mitigates this issues across react type versions.
+ *
+ * @remarks
+ *
+ * React 18 types introduced Type Expansion Change to the `RefAttributes` interface as patch release.
+ * These changes were released in `@types/react@18.2.61` (replacing ref with `LegacyRef`, which leaks `string` into the union type, causing breaking changes between v8/v9 libraries):
+ *  - {@link https://github.com/DefinitelyTyped/DefinitelyTyped/pull/68720 | PR }
+ *  - {@link https://app.unpkg.com/@types/react@18.2.61/files/index.d.ts | shipped definitions }
+ *
+ *
+ * In React 19 types this was "reverted" back to the original `Ref<T>` type.
+ * In order to maintain compatibility with React 17,18,19, we are forced to use our own version of `RefAttributes`.
+ *
+ */
+export interface RefAttributes<T> extends React.Attributes {
+  ref?: React.Ref<T> | undefined;
+}

packages/react-components/react-utilities/src/index.ts

@@ -20,6 +20,7 @@ export type {
   ComponentProps,
   ComponentState,
   ForwardRefComponent,
+  RefAttributes,
   // eslint-disable-next-line @typescript-eslint/no-deprecated
   ResolveShorthandFunction,
   // eslint-disable-next-line @typescript-eslint/no-deprecated