@types/react 18.2.60 → 18.2.61

react/README.md

@@ -8,8 +8,8 @@ This package contains type definitions for react (https://react.dev/).
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react.
 
 ### Additional Details
- * Last updated: Tue, 27 Feb 2024 09:06:52 GMT
+ * Last updated: Thu, 29 Feb 2024 12:09:49 GMT
  * Dependencies: [@types/prop-types](https://npmjs.com/package/@types/prop-types), [@types/scheduler](https://npmjs.com/package/@types/scheduler), [csstype](https://npmjs.com/package/csstype)
 
 # Credits
-These definitions were written by [Asana](https://asana.com), [AssureSign](http://www.assuresign.com), [Microsoft](https://microsoft.com), [John Reilly](https://github.com/johnnyreilly), [Benoit Benezech](https://github.com/bbenezech), [Patricio Zavolinsky](https://github.com/pzavolinsky), [Eric Anderson](https://github.com/ericanderson), [Dovydas Navickas](https://github.com/DovydasNavickas), [Josh Rutherford](https://github.com/theruther4d), [Guilherme Hübner](https://github.com/guilhermehubner), [Ferdy Budhidharma](https://github.com/ferdaber), [Johann Rakotoharisoa](https://github.com/jrakotoharisoa), [Olivier Pascal](https://github.com/pascaloliv), [Martin Hochel](https://github.com/hotell), [Frank Li](https://github.com/franklixuefei), [Jessica Franco](https://github.com/Jessidhia), [Saransh Kataria](https://github.com/saranshkataria), [Kanitkorn Sujautra](https://github.com/lukyth), [Sebastian Silbermann](https://github.com/eps1lon), [Kyle Scully](https://github.com/zieka), [Cong Zhang](https://github.com/dancerphil), [Dimitri Mitropoulos](https://github.com/dimitropoulos), [JongChan Choi](https://github.com/disjukr), [Victor Magalhães](https://github.com/vhfmag), [Dale Tan](https://github.com/hellatan), [Priyanshu Rav](https://github.com/priyanshurav), and [Dmitry Semigradsky](https://github.com/Semigradsky).
+These definitions were written by [Asana](https://asana.com), [AssureSign](http://www.assuresign.com), [Microsoft](https://microsoft.com), [John Reilly](https://github.com/johnnyreilly), [Benoit Benezech](https://github.com/bbenezech), [Patricio Zavolinsky](https://github.com/pzavolinsky), [Eric Anderson](https://github.com/ericanderson), [Dovydas Navickas](https://github.com/DovydasNavickas), [Josh Rutherford](https://github.com/theruther4d), [Guilherme Hübner](https://github.com/guilhermehubner), [Ferdy Budhidharma](https://github.com/ferdaber), [Johann Rakotoharisoa](https://github.com/jrakotoharisoa), [Olivier Pascal](https://github.com/pascaloliv), [Martin Hochel](https://github.com/hotell), [Frank Li](https://github.com/franklixuefei), [Jessica Franco](https://github.com/Jessidhia), [Saransh Kataria](https://github.com/saranshkataria), [Kanitkorn Sujautra](https://github.com/lukyth), [Sebastian Silbermann](https://github.com/eps1lon), [Kyle Scully](https://github.com/zieka), [Cong Zhang](https://github.com/dancerphil), [Dimitri Mitropoulos](https://github.com/dimitropoulos), [JongChan Choi](https://github.com/disjukr), [Victor Magalhães](https://github.com/vhfmag), [Dale Tan](https://github.com/hellatan), [Priyanshu Rav](https://github.com/priyanshurav), [Dmitry Semigradsky](https://github.com/Semigradsky), and [Matt Pocock](https://github.com/mattpocock).

react/index.d.ts

@@ -189,6 +189,7 @@ declare namespace React {
      * <div ref="myRef" />
      * ```
      */
+    // TODO: Remove the string ref special case from `PropsWithRef` once we remove LegacyRef
     type LegacyRef<T> = string | Ref<T>;
 
     /**
@@ -217,9 +218,10 @@ declare namespace React {
     > =
         // need to check first if `ref` is a valid prop for ts@3.0
         // otherwise it will infer `{}` instead of `never`
-        "ref" extends keyof ComponentPropsWithRef<C> ? NonNullable<ComponentPropsWithRef<C>["ref"]> extends Ref<
+        "ref" extends keyof ComponentPropsWithRef<C>
+            ? NonNullable<ComponentPropsWithRef<C>["ref"]> extends RefAttributes<
                 infer Instance
-            > ? Instance
+            >["ref"] ? Instance
             : never
             : never;
 
@@ -232,9 +234,55 @@ declare namespace React {
      */
     type Key = string | number | bigint;
 
+    /**
+     * @internal The props any component can receive.
+     * You don't have to add this type. All components automatically accept these props.
+     * ```tsx
+     * const Component = () => <div />;
+     * <Component key="one" />
+     * ```
+     *
+     * WARNING: The implementation of a component will never have access to these attributes.
+     * The following example would be incorrect usage because {@link Component} would never have access to `key`:
+     * ```tsx
+     * const Component = (props: React.Attributes) => props.key;
+     * ```
+     */
     interface Attributes {
         key?: Key | null | undefined;
     }
+    /**
+     * The props any component accepting refs can receive.
+     * Class components, built-in browser components (e.g. `div`) and forwardRef components can receive refs and automatically accept these props.
+     * ```tsx
+     * const Component = forwardRef(() => <div />);
+     * <Component ref={(current) => console.log(current)} />
+     * ```
+     *
+     * You only need this type if you manually author the types of props that need to be compatible with legacy refs.
+     * ```tsx
+     * interface Props extends React.RefAttributes<HTMLDivElement> {}
+     * declare const Component: React.FunctionComponent<Props>;
+     * ```
+     *
+     * Otherwise it's simpler to directly use {@link Ref} since you can safely use the
+     * props type to describe to props that a consumer can pass to the component
+     * as well as describing the props the implementation of a component "sees".
+     * {@link RefAttributes} is generally not safe to describe both consumer and seen props.
+     *
+     * ```tsx
+     * interface Props extends {
+     *   ref?: React.Ref<HTMLDivElement> | undefined;
+     * }
+     * declare const Component: React.FunctionComponent<Props>;
+     * ```
+     *
+     * WARNING: The implementation of a component will not have access to the same type in versions of React supporting string refs.
+     * The following example would be incorrect usage because {@link Component} would never have access to a `ref` with type `string`
+     * ```tsx
+     * const Component = (props: React.RefAttributes) => props.ref;
+     * ```
+     */
     interface RefAttributes<T> extends Attributes {
         /**
          * Allows getting a ref to the component instance.
@@ -243,21 +291,13 @@ declare namespace React {
          *
          * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
          */
-        ref?: Ref<T> | undefined;
+        ref?: LegacyRef<T> | undefined;
     }
 
     /**
      * Represents the built-in attributes available to class components.
      */
-    interface ClassAttributes<T> extends Attributes {
-        /**
-         * Allows getting a ref to the component instance.
-         * Once the component unmounts, React will set `ref.current` to `null`
-         * (or call the ref with `null` if you passed a callback ref).
-         *
-         * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
-         */
-        ref?: LegacyRef<T> | undefined;
+    interface ClassAttributes<T> extends RefAttributes<T> {
     }
 
     /**
@@ -1522,6 +1562,7 @@ declare namespace React {
         P extends any ? ("ref" extends keyof P ? Omit<P, "ref"> : P) : P;
     /** Ensures that the props do not include string ref, which cannot be forwarded */
     type PropsWithRef<P> =
+        // Note: String refs can be forwarded. We can't fix this bug without breaking a bunch of libraries now though.
         // Just "P extends { ref?: infer R }" looks sufficient, but R will infer as {} if P is {}.
         "ref" extends keyof P
             ? P extends { ref?: infer R | undefined }

react/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/react",
-    "version": "18.2.60",
+    "version": "18.2.61",
     "description": "TypeScript definitions for react",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react",
     "license": "MIT",
@@ -136,6 +136,11 @@
             "name": "Dmitry Semigradsky",
             "githubUsername": "Semigradsky",
             "url": "https://github.com/Semigradsky"
+        },
+        {
+            "name": "Matt Pocock",
+            "githubUsername": "mattpocock",
+            "url": "https://github.com/mattpocock"
         }
     ],
     "main": "",
@@ -201,6 +206,6 @@
         "@types/scheduler": "*",
         "csstype": "^3.0.2"
     },
-    "typesPublisherContentHash": "cc510b85587c5066cc0a536acf0b69e30af6fea74671e2c9af44f21d265f95a0",
+    "typesPublisherContentHash": "c969d4c49fc5be8c9712e6a7cc38c14d908da611af884cf2da96ba279fe8495e",
     "typeScriptVersion": "4.6"
 }

react/ts5.0/index.d.ts

@@ -186,6 +186,7 @@ declare namespace React {
      * <div ref="myRef" />
      * ```
      */
+    // TODO: Remove the string ref special case from `PropsWithRef` once we remove LegacyRef
     type LegacyRef<T> = string | Ref<T>;
 
     /**
@@ -214,9 +215,10 @@ declare namespace React {
     > =
         // need to check first if `ref` is a valid prop for ts@3.0
         // otherwise it will infer `{}` instead of `never`
-        "ref" extends keyof ComponentPropsWithRef<C> ? NonNullable<ComponentPropsWithRef<C>["ref"]> extends Ref<
+        "ref" extends keyof ComponentPropsWithRef<C>
+            ? NonNullable<ComponentPropsWithRef<C>["ref"]> extends RefAttributes<
                 infer Instance
-            > ? Instance
+            >["ref"] ? Instance
             : never
             : never;
 
@@ -230,30 +232,66 @@ declare namespace React {
     type Key = string | number | bigint;
 
     /**
-     * @internal You shouldn't need to use this type since you never see these attributes
-     * inside your component or have to validate them.
+     * @internal The props any component can receive.
+     * You don't have to add this type. All components automatically accept these props.
+     * ```tsx
+     * const Component = () => <div />;
+     * <Component key="one" />
+     * ```
+     *
+     * WARNING: The implementation of a component will never have access to these attributes.
+     * The following example would be incorrect usage because {@link Component} would never have access to `key`:
+     * ```tsx
+     * const Component = (props: React.Attributes) => props.key;
+     * ```
      */
     interface Attributes {
         key?: Key | null | undefined;
     }
+    /**
+     * The props any component accepting refs can receive.
+     * Class components, built-in browser components (e.g. `div`) and forwardRef components can receive refs and automatically accept these props.
+     * ```tsx
+     * const Component = forwardRef(() => <div />);
+     * <Component ref={(current) => console.log(current)} />
+     * ```
+     *
+     * You only need this type if you manually author the types of props that need to be compatible with legacy refs.
+     * ```tsx
+     * interface Props extends React.RefAttributes<HTMLDivElement> {}
+     * declare const Component: React.FunctionComponent<Props>;
+     * ```
+     *
+     * Otherwise it's simpler to directly use {@link Ref} since you can safely use the
+     * props type to describe to props that a consumer can pass to the component
+     * as well as describing the props the implementation of a component "sees".
+     * {@link RefAttributes} is generally not safe to describe both consumer and seen props.
+     *
+     * ```tsx
+     * interface Props extends {
+     *   ref?: React.Ref<HTMLDivElement> | undefined;
+     * }
+     * declare const Component: React.FunctionComponent<Props>;
+     * ```
+     *
+     * WARNING: The implementation of a component will not have access to the same type in versions of React supporting string refs.
+     * The following example would be incorrect usage because {@link Component} would never have access to a `ref` with type `string`
+     * ```tsx
+     * const Component = (props: React.RefAttributes) => props.ref;
+     * ```
+     */
     interface RefAttributes<T> extends Attributes {
         /**
          * Allows getting a ref to the component instance.
          * Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
          * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom}
          */
-        ref?: Ref<T> | undefined;
+        ref?: LegacyRef<T> | undefined;
     }
     /**
      * Represents the built-in attributes available to class components.
      */
-    interface ClassAttributes<T> extends Attributes {
-        /**
-         * Allows getting a ref to the component instance.
-         * Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
-         * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom}
-         */
-        ref?: LegacyRef<T> | undefined;
+    interface ClassAttributes<T> extends RefAttributes<T> {
     }
 
     /**
@@ -1520,6 +1558,7 @@ declare namespace React {
         P extends any ? ("ref" extends keyof P ? Omit<P, "ref"> : P) : P;
     /** Ensures that the props do not include string ref, which cannot be forwarded */
     type PropsWithRef<P> =
+        // Note: String refs can be forwarded. We can't fix this bug without breaking a bunch of libraries now though.
         // Just "P extends { ref?: infer R }" looks sufficient, but R will infer as {} if P is {}.
         "ref" extends keyof P
             ? P extends { ref?: infer R | undefined }