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/[email protected]

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/[email protected]",
+  "packageName": "@fluentui/react-utilities",
+  "email": "[email protected]",
+  "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/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 { DistributiveOmit, RefAttributes, 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/[email protected]`
+ * - `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)

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

@@ -73,7 +73,7 @@ export {
   createPriorityQueue,
 } from './utils/index';
 
-export type { DistributiveOmit, UnionToIntersection } from './utils/types';
+export type { DistributiveOmit, UnionToIntersection, RefAttributes } from './utils/types';
 
 export type { PriorityQueue } from './utils/priorityQueue';
 

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

@@ -1,3 +1,4 @@
+import * as React from 'react';
 /**
  * Helper type that works similar to Omit,
  * but when modifying an union type it will distribute the omission to all the union members.
@@ -31,3 +32,24 @@ export type UnionToIntersection<U> = (U extends unknown ? (x: U) => U : never) e
  * If type T includes `null`, remove it and add `undefined` instead.
  */
 export type ReplaceNullWithUndefined<T> = T extends null ? Exclude<T, null> | undefined : T;
+
+/**
+ * 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/[email protected]` (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/[email protected]/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;
+}