@types/react 18.2.49 → 18.2.51

react/README.md

@@ -8,7 +8,7 @@ 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: Thu, 01 Feb 2024 06:07:40 GMT
+ * Last updated: Thu, 01 Feb 2024 10:06:59 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

react/index.d.ts

@@ -372,18 +372,14 @@ declare namespace React {
     }
 
     /**
-     * An object masquerading as a component. These are created by
-     * {@link forwardRef}, {@link memo}, and {@link createContext}.
+     * An object masquerading as a component. These are created by functions
+     * like {@link forwardRef}, {@link memo}, and {@link createContext}.
      *
      * In order to make TypeScript work, we pretend that they are normal
      * components.
      *
      * But they are, in fact, not callable - instead, they are objects which
      * are treated specially by the renderer.
-     *
-     * @see {@link forwardRef}
-     * @see {@link memo}
-     * @see {@link createContext}
      */
     interface ExoticComponent<P = {}> {
         (props: P): ReactNode;
@@ -399,29 +395,127 @@ declare namespace React {
          * explicitly if you want to display a different name for
          * debugging purposes.
          *
-         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname}
+         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname Legacy React Docs}
          */
         displayName?: string | undefined;
     }
 
+    /**
+     * An {@link ExoticComponent} with a `propTypes` property applied to it.
+     */
     interface ProviderExoticComponent<P> extends ExoticComponent<P> {
         propTypes?: WeakValidationMap<P> | undefined;
     }
 
+    /**
+     * Used to retrieve the type of a context object from a {@link Context}.
+     *
+     * @example
+     *
+     * ```tsx
+     * import { createContext } from 'react';
+     *
+     * const MyContext = createContext({ foo: 'bar' });
+     *
+     * type ContextType = ContextType<typeof MyContext>;
+     * // ContextType = { foo: string }
+     * ```
+     */
     type ContextType<C extends Context<any>> = C extends Context<infer T> ? T : never;
 
-    // NOTE: only the Context object itself can get a displayName
-    // https://github.com/facebook/react-devtools/blob/e0b854e4c/backend/attachRendererFiber.js#L310-L325
+    /**
+     * Wraps your components to specify the value of this context for all components inside.
+     *
+     * @see {@link https://react.dev/reference/react/createContext#provider React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { createContext } from 'react';
+     *
+     * const ThemeContext = createContext('light');
+     *
+     * function App() {
+     *   return (
+     *     <ThemeContext.Provider value="dark">
+     *       <Toolbar />
+     *     </ThemeContext.Provider>
+     *   );
+     * }
+     * ```
+     */
     type Provider<T> = ProviderExoticComponent<ProviderProps<T>>;
+
+    /**
+     * The old way to read context, before {@link useContext} existed.
+     *
+     * @see {@link https://react.dev/reference/react/createContext#consumer React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { UserContext } from './user-context';
+     *
+     * function Avatar() {
+     *   return (
+     *     <UserContext.Consumer>
+     *       {user => <img src={user.profileImage} alt={user.name} />}
+     *     </UserContext.Consumer>
+     *   );
+     * }
+     * ```
+     */
     type Consumer<T> = ExoticComponent<ConsumerProps<T>>;
+
+    /**
+     * Context lets components pass information deep down without explicitly
+     * passing props.
+     *
+     * Created from {@link createContext}
+     *
+     * @see {@link https://react.dev/learn/passing-data-deeply-with-context React Docs}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/ React TypeScript Cheatsheet}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { createContext } from 'react';
+     *
+     * const ThemeContext = createContext('light');
+     * ```
+     */
     interface Context<T> {
         Provider: Provider<T>;
         Consumer: Consumer<T>;
+        /**
+         * Used in debugging messages. You might want to set it
+         * explicitly if you want to display a different name for
+         * debugging purposes.
+         *
+         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname Legacy React Docs}
+         */
         displayName?: string | undefined;
     }
+
+    /**
+     * Lets you create a {@link Context} that components can provide or read.
+     *
+     * @param defaultValue The value you want the context to have when there is no matching
+     * {@link Provider} in the tree above the component reading the context. This is meant
+     * as a "last resort" fallback.
+     *
+     * @see {@link https://react.dev/reference/react/createContext#reference React Docs}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/context/ React TypeScript Cheatsheet}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { createContext } from 'react';
+     *
+     * const ThemeContext = createContext('light');
+     * ```
+     */
     function createContext<T>(
-        // If you thought this should be optional, see
-        // https://github.com/DefinitelyTyped/DefinitelyTyped/pull/24509#issuecomment-382213106
         defaultValue: T,
     ): Context<T>;
 
@@ -438,9 +532,57 @@ declare namespace React {
         only<C>(children: C): C extends any[] ? never : C;
         toArray(children: ReactNode | ReactNode[]): Array<Exclude<ReactNode, boolean | null | undefined>>;
     };
+    /**
+     * Lets you group elements without a wrapper node.
+     *
+     * @see {@link https://react.dev/reference/react/Fragment React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { Fragment } from 'react';
+     *
+     * <Fragment>
+     *   <td>Hello</td>
+     *   <td>World</td>
+     * </Fragment>
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // Using the <></> shorthand syntax:
+     *
+     * <>
+     *   <td>Hello</td>
+     *   <td>World</td>
+     * </>
+     * ```
+     */
     const Fragment: ExoticComponent<{ children?: ReactNode | undefined }>;
+
+    /**
+     * Lets you find common bugs in your components early during development.
+     *
+     * @see {@link https://react.dev/reference/react/StrictMode React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { StrictMode } from 'react';
+     *
+     * <StrictMode>
+     *   <App />
+     * </StrictMode>
+     * ```
+     */
     const StrictMode: ExoticComponent<{ children?: ReactNode | undefined }>;
 
+    /**
+     * The props accepted by {@link Suspense}.
+     *
+     * @see {@link https://react.dev/reference/react/Suspense React Docs}
+     */
     interface SuspenseProps {
         children?: ReactNode | undefined;
 
@@ -448,27 +590,105 @@ declare namespace React {
         fallback?: ReactNode;
     }
 
+    /**
+     * Lets you display a fallback until its children have finished loading.
+     *
+     * @see {@link https://react.dev/reference/react/Suspense React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * import { Suspense } from 'react';
+     *
+     * <Suspense fallback={<Loading />}>
+     *   <ProfileDetails />
+     * </Suspense>
+     * ```
+     */
     const Suspense: ExoticComponent<SuspenseProps>;
     const version: string;
 
     /**
-     * {@link https://react.dev/reference/react/Profiler#onrender-callback Profiler API}
+     * The callback passed to {@link ProfilerProps.onRender}.
+     *
+     * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
      */
     type ProfilerOnRenderCallback = (
+        /**
+         * The string id prop of the {@link Profiler} tree that has just committed. This lets
+         * you identify which part of the tree was committed if you are using multiple
+         * profilers.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         id: string,
+        /**
+         * This lets you know whether the tree has just been mounted for the first time
+         * or re-rendered due to a change in props, state, or hooks.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         phase: "mount" | "update" | "nested-update",
+        /**
+         * The number of milliseconds spent rendering the {@link Profiler} and its descendants
+         * for the current update. This indicates how well the subtree makes use of
+         * memoization (e.g. {@link memo} and {@link useMemo}). Ideally this value should decrease
+         * significantly after the initial mount as many of the descendants will only need to
+         * re-render if their specific props change.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         actualDuration: number,
+        /**
+         * The number of milliseconds estimating how much time it would take to re-render the entire
+         * {@link Profiler} subtree without any optimizations. It is calculated by summing up the most
+         * recent render durations of each component in the tree. This value estimates a worst-case
+         * cost of rendering (e.g. the initial mount or a tree with no memoization). Compare
+         * {@link actualDuration} against it to see if memoization is working.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         baseDuration: number,
+        /**
+         * A numeric timestamp for when React began rendering the current update.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         startTime: number,
+        /**
+         * A numeric timestamp for when React committed the current update. This value is shared
+         * between all profilers in a commit, enabling them to be grouped if desirable.
+         *
+         * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+         */
         commitTime: number,
         interactions: Set<SchedulerInteraction>,
     ) => void;
+
+    /**
+     * The props accepted by {@link Profiler}.
+     *
+     * @see {@link https://react.dev/reference/react/Profiler React Docs}
+     */
     interface ProfilerProps {
         children?: ReactNode | undefined;
         id: string;
         onRender: ProfilerOnRenderCallback;
     }
 
+    /**
+     * Lets you measure rendering performance of a React tree programmatically.
+     *
+     * @see {@link https://react.dev/reference/react/Profiler#onrender-callback React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * <Profiler id="App" onRender={onRender}>
+     *   <App />
+     * </Profiler>
+     * ```
+     */
     const Profiler: ExoticComponent<ProfilerProps>;
 
     //
@@ -553,6 +773,9 @@ declare namespace React {
 
     /**
      * @deprecated Use `ClassicComponent` from `create-react-class`
+     *
+     * @see {@link https://legacy.reactjs.org/docs/react-without-es6.html Legacy React Docs}
+     * @see {@link https://www.npmjs.com/package/create-react-class `create-react-class` on npm}
      */
     interface ClassicComponent<P = {}, S = {}> extends Component<P, S> {
         replaceState(nextState: S, callback?: () => void): void;
@@ -573,8 +796,8 @@ declare namespace React {
      * receive a type argument that represents the props the component
      * receives.
      *
-     * @param P - The props the component receives.
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/function_components}
+     * @typeparam P - The props the component receives.
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/function_components React TypeScript Cheatsheet}
      * @alias for {@link React.FunctionComponent}
      *
      * @example
@@ -604,8 +827,8 @@ declare namespace React {
      * receive a type argument that represents the props the component
      * accepts.
      *
-     * @param P - The props the component accepts.
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/function_components}
+     * @typeparam P - The props the component accepts.
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/function_components React TypeScript Cheatsheet}
      *
      * @example
      *
@@ -637,7 +860,7 @@ declare namespace React {
          * We recommend using TypeScript instead of checking prop
          * types at runtime.
          *
-         * @see {@link https://react.dev/reference/react/Component#static-proptypes}
+         * @see {@link https://react.dev/reference/react/Component#static-proptypes React Docs}
          */
         propTypes?: WeakValidationMap<P> | undefined;
         /**
@@ -646,14 +869,14 @@ declare namespace React {
          * Lets you specify which legacy context is consumed by
          * this component.
          *
-         * @see {@link https://legacy.reactjs.org/docs/legacy-context.html}
+         * @see {@link https://legacy.reactjs.org/docs/legacy-context.html Legacy React Docs}
          */
         contextTypes?: ValidationMap<any> | undefined;
         /**
          * Used to define default values for the props accepted by
          * the component.
          *
-         * @see {@link https://react.dev/reference/react/Component#static-defaultprops}
+         * @see {@link https://react.dev/reference/react/Component#static-defaultprops React Docs}
          *
          * @example
          *
@@ -675,7 +898,7 @@ declare namespace React {
          * explicitly if you want to display a different name for
          * debugging purposes.
          *
-         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname}
+         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname Legacy React Docs}
          *
          * @example
          *
@@ -719,12 +942,16 @@ declare namespace React {
     type ForwardedRef<T> = ((instance: T | null) => void) | MutableRefObject<T | null> | null;
 
     /**
-     * The type of the function passed to {@link forwardRef}.
+     * The type of the function passed to {@link forwardRef}. This is considered different
+     * to a normal {@link FunctionComponent} because it receives an additional argument,
      *
      * @param props Props passed to the component, if any.
      * @param ref A ref forwarded to the component of type {@link ForwardedRef}.
      *
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/}
+     * @typeparam T The type of the forwarded ref.
+     * @typeparam P The type of the props the component accepts.
+     *
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/ React TypeScript Cheatsheet}
      * @see {@link forwardRef}
      */
     interface ForwardRefRenderFunction<T, P = {}> {
@@ -737,37 +964,82 @@ declare namespace React {
          * Will show `ForwardRef(${Component.displayName || Component.name})`
          * in devtools by default, but can be given its own specific name.
          *
-         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname}
+         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname Legacy React Docs}
          */
         displayName?: string | undefined;
         /**
-         * defaultProps are not supported on components passed to forwardRef.
+         * defaultProps are not supported on render functions passed to forwardRef.
          *
-         * @see {@link https://github.com/microsoft/TypeScript/issues/36826} for context
-         * @see {@link https://react.dev/reference/react/Component#static-defaultprops}
+         * @see {@link https://github.com/microsoft/TypeScript/issues/36826 linked GitHub issue} for context
+         * @see {@link https://react.dev/reference/react/Component#static-defaultprops React Docs}
          */
         defaultProps?: never | undefined;
         /**
-         * propTypes are not supported on components passed to forwardRef.
+         * propTypes are not supported on render functions passed to forwardRef.
          *
-         * @see {@link https://github.com/microsoft/TypeScript/issues/36826} for context
-         * @see {@link https://react.dev/reference/react/Component#static-proptypes}
+         * @see {@link https://github.com/microsoft/TypeScript/issues/36826 linked GitHub issue} for context
+         * @see {@link https://react.dev/reference/react/Component#static-proptypes React Docs}
          */
         propTypes?: never | undefined;
     }
 
+    /**
+     * Represents a component class in React.
+     *
+     * @typeparam P The props the component accepts.
+     * @typeparam S The internal state of the component.
+     */
     interface ComponentClass<P = {}, S = ComponentState> extends StaticLifecycle<P, S> {
         new(props: P, context?: any): Component<P, S>;
+        /**
+         * Used to declare the types of the props accepted by the
+         * component. These types will be checked during rendering
+         * and in development only.
+         *
+         * We recommend using TypeScript instead of checking prop
+         * types at runtime.
+         *
+         * @see {@link https://react.dev/reference/react/Component#static-proptypes React Docs}
+         */
         propTypes?: WeakValidationMap<P> | undefined;
         contextType?: Context<any> | undefined;
+        /**
+         * @deprecated use {@link ComponentClass.contextType} instead
+         *
+         * Lets you specify which legacy context is consumed by
+         * this component.
+         *
+         * @see {@link https://legacy.reactjs.org/docs/legacy-context.html Legacy React Docs}
+         */
         contextTypes?: ValidationMap<any> | undefined;
+        /**
+         * @deprecated
+         *
+         * @see {@link https://legacy.reactjs.org/docs/legacy-context.html#how-to-use-context Legacy React Docs}
+         */
         childContextTypes?: ValidationMap<any> | undefined;
+        /**
+         * Used to define default values for the props accepted by
+         * the component.
+         *
+         * @see {@link https://react.dev/reference/react/Component#static-defaultprops React Docs}
+         */
         defaultProps?: Partial<P> | undefined;
+        /**
+         * Used in debugging messages. You might want to set it
+         * explicitly if you want to display a different name for
+         * debugging purposes.
+         *
+         * @see {@link https://legacy.reactjs.org/docs/react-component.html#displayname Legacy React Docs}
+         */
         displayName?: string | undefined;
     }
 
     /**
      * @deprecated Use `ClassicComponentClass` from `create-react-class`
+     *
+     * @see {@link https://legacy.reactjs.org/docs/react-without-es6.html Legacy React Docs}
+     * @see {@link https://www.npmjs.com/package/create-react-class `create-react-class` on npm}
      */
     interface ClassicComponentClass<P = {}> extends ComponentClass<P> {
         new(props: P, context?: any): ClassicComponent<P, ComponentState>;
@@ -775,7 +1047,10 @@ declare namespace React {
     }
 
     /**
-     * We use an intersection type to infer multiple type parameters from
+     * Used in {@link createElement} and {@link createFactory} to represent
+     * a class.
+     *
+     * An intersection type is used to infer multiple type parameters from
      * a single argument, which is useful for many top-level API defs.
      * See https://github.com/Microsoft/TypeScript/issues/7234 for more info.
      */
@@ -968,7 +1243,9 @@ declare namespace React {
     }
 
     /**
-     * @deprecated https://legacy.reactjs.org/blog/2016/07/13/mixins-considered-harmful.html
+     * @deprecated
+     *
+     * @see {@link https://legacy.reactjs.org/blog/2016/07/13/mixins-considered-harmful.html Mixins Considered Harmful}
      */
     interface ComponentSpec<P, S> extends Mixin<P, S> {
         render(): ReactNode;
@@ -991,11 +1268,11 @@ declare namespace React {
     }
 
     /**
-     * Lets your component expose a DOM node to parent component
+     * Lets your component expose a DOM node to a parent component
      * using a ref.
      *
-     * @see {@link https://react.dev/reference/react/forwardRef}
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/}
+     * @see {@link https://react.dev/reference/react/forwardRef React Docs}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/forward_and_create_ref/ React TypeScript Cheatsheet}
      *
      * @param render See the {@link ForwardRefRenderFunction}.
      *
@@ -1048,7 +1325,7 @@ declare namespace React {
      * instead of this type, as they let you be explicit about whether or not to include
      * the `ref` prop.
      *
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/ React TypeScript Cheatsheet}
      *
      * @example
      *
@@ -1076,7 +1353,7 @@ declare namespace React {
      * passed a string, indicating a DOM element (e.g. 'div', 'span', etc.) or the
      * type of a React component.
      *
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/ React TypeScript Cheatsheet}
      *
      * @example
      *
@@ -1123,7 +1400,7 @@ declare namespace React {
      * passed a string, indicating a DOM element (e.g. 'div', 'span', etc.) or the
      * type of a React component.
      *
-     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/}
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/componentprops/ React TypeScript Cheatsheet}
      *
      * @example
      *

react/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/react",
-    "version": "18.2.49",
+    "version": "18.2.51",
     "description": "TypeScript definitions for react",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/react",
     "license": "MIT",
@@ -201,6 +201,6 @@
         "@types/scheduler": "*",
         "csstype": "^3.0.2"
     },
-    "typesPublisherContentHash": "0eb7a991a00ce343b222b32fb0879928350f9dd65227c90a49a1d8ceccf4a389",
+    "typesPublisherContentHash": "d210a53ee59001ed347fd48af226f2e1968d4c348de7f3b360d5e450f4e1b70f",
     "typeScriptVersion": "4.6"
 }