@types/react 18.2.48 → 18.2.50

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: Mon, 15 Jan 2024 09:07:05 GMT
+ * Last updated: Thu, 01 Feb 2024 07:35:21 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

@@ -371,25 +371,36 @@ declare namespace React {
         children: (value: T) => ReactNode;
     }
 
-    // TODO: similar to how Fragment is actually a symbol, the values returned from createContext,
-    // forwardRef and memo are actually objects that are treated specially by the renderer; see:
-    // https://github.com/facebook/react/blob/v16.6.0/packages/react/src/ReactContext.js#L35-L48
-    // https://github.com/facebook/react/blob/v16.6.0/packages/react/src/forwardRef.js#L42-L45
-    // https://github.com/facebook/react/blob/v16.6.0/packages/react/src/memo.js#L27-L31
-    // However, we have no way of telling the JSX parser that it's a JSX element type or its props other than
-    // by pretending to be a normal component.
-    //
-    // We don't just use ComponentType or FunctionComponent types because you are not supposed to attach statics to this
-    // object, but rather to the original function.
+    /**
+     * An object masquerading as a component. These are created by
+     * {@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 = {}> {
-        /**
-         * **NOTE**: Exotic components are not callable.
-         */
         (props: P): ReactNode;
         readonly $$typeof: symbol;
     }
 
+    /**
+     * An {@link ExoticComponent} with a `displayName` property applied to it.
+     */
     interface NamedExoticComponent<P = {}> extends ExoticComponent<P> {
+        /**
+         * 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;
     }
 
@@ -441,7 +452,7 @@ declare namespace React {
     const version: string;
 
     /**
-     * {@link https://react.dev/reference/react/Profiler#onrender-callback Profiler API}
+     * @see {@link https://react.dev/reference/react/Profiler#onrender-callback Profiler API React Docs}
      */
     type ProfilerOnRenderCallback = (
         id: string,
@@ -557,23 +568,140 @@ declare namespace React {
     // Class Interfaces
     // ----------------------------------------------------------------------
 
+    /**
+     * Represents the type of a function component. Can optionally
+     * receive a type argument that represents the props the component
+     * receives.
+     *
+     * @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
+     *
+     * ```tsx
+     * // With props:
+     * type Props = { name: string }
+     *
+     * const MyComponent: FC<Props> = (props) => {
+     *  return <div>{props.name}</div>
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // Without props:
+     * const MyComponentWithoutProps: FC = () => {
+     *   return <div>MyComponentWithoutProps</div>
+     * }
+     * ```
+     */
     type FC<P = {}> = FunctionComponent<P>;
 
+    /**
+     * Represents the type of a function component. Can optionally
+     * receive a type argument that represents the props the component
+     * accepts.
+     *
+     * @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
+     *
+     * ```tsx
+     * // With props:
+     * type Props = { name: string }
+     *
+     * const MyComponent: FunctionComponent<Props> = (props) => {
+     *  return <div>{props.name}</div>
+     * }
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // Without props:
+     * const MyComponentWithoutProps: FunctionComponent = () => {
+     *   return <div>MyComponentWithoutProps</div>
+     * }
+     * ```
+     */
     interface FunctionComponent<P = {}> {
         (props: P, context?: any): ReactNode;
+        /**
+         * 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;
+        /**
+         * @deprecated
+         *
+         * 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;
+        /**
+         * Used to define default values for the props accepted by
+         * the component.
+         *
+         * @see {@link https://react.dev/reference/react/Component#static-defaultprops React Docs}
+         *
+         * @example
+         *
+         * ```tsx
+         * type Props = { name?: string }
+         *
+         * const MyComponent: FC<Props> = (props) => {
+         *   return <div>{props.name}</div>
+         * }
+         *
+         * MyComponent.defaultProps = {
+         *   name: 'John Doe'
+         * }
+         * ```
+         */
         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}
+         *
+         * @example
+         *
+         * ```tsx
+         *
+         * const MyComponent: FC = () => {
+         *   return <div>Hello!</div>
+         * }
+         *
+         * MyComponent.displayName = 'MyAwesomeComponent'
+         * ```
+         */
         displayName?: string | undefined;
     }
 
     /**
-     * @deprecated - Equivalent with `React.FC`.
+     * @deprecated - Equivalent to {@link React.FunctionComponent}.
+     *
+     * @see {@link React.FunctionComponent}
      */
     type VFC<P = {}> = VoidFunctionComponent<P>;
 
     /**
-     * @deprecated - Equivalent with `React.FunctionComponent`.
+     * @deprecated - Equivalent to {@link React.FunctionComponent}.
+     *
+     * @see {@link React.FunctionComponent}
      */
     interface VoidFunctionComponent<P = {}> {
         (props: P, context?: any): ReactNode;
@@ -583,35 +711,108 @@ declare namespace React {
         displayName?: string | undefined;
     }
 
+    /**
+     * The type of the ref received by a {@link ForwardRefRenderFunction}.
+     *
+     * @see {@link ForwardRefRenderFunction}
+     */
     type ForwardedRef<T> = ((instance: T | null) => void) | MutableRefObject<T | null> | null;
 
+    /**
+     * The type of the function passed to {@link forwardRef}.
+     *
+     * @typeparam props Props passed to the component, if any.
+     * @typeparam 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/ React TypeScript Cheatsheet}
+     * @see {@link forwardRef}
+     */
     interface ForwardRefRenderFunction<T, P = {}> {
         (props: P, ref: ForwardedRef<T>): ReactNode;
+        /**
+         * Used in debugging messages. You might want to set it
+         * explicitly if you want to display a different name for
+         * debugging purposes.
+         *
+         * 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 Legacy React Docs}
+         */
         displayName?: string | undefined;
-        // explicit rejected with `never` required due to
-        // https://github.com/microsoft/TypeScript/issues/36826
         /**
-         * defaultProps are not supported on render functions
+         * defaultProps are not supported on components passed to forwardRef.
+         *
+         * @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 render functions
+         * propTypes are not supported on components passed to forwardRef.
+         *
+         * @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>;
@@ -619,7 +820,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.
      */
@@ -812,7 +1016,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;
@@ -822,13 +1028,45 @@ declare namespace React {
 
     function createRef<T>(): RefObject<T>;
 
-    // will show `ForwardRef(${Component.displayName || Component.name})` in devtools by default,
-    // but can be given its own specific name
+    /**
+     * The type of the component returned from {@link forwardRef}.
+     *
+     * @typeparam P The props the component accepts, if any.
+     *
+     * @see {@link ExoticComponent}
+     */
     interface ForwardRefExoticComponent<P> extends NamedExoticComponent<P> {
         defaultProps?: Partial<P> | undefined;
         propTypes?: WeakValidationMap<P> | undefined;
     }
 
+    /**
+     * Lets your component expose a DOM node to parent component
+     * using a 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}.
+     *
+     * @typeparam T The type of the DOM node.
+     * @typeparam P The props the component accepts, if any.
+     *
+     * @example
+     *
+     * ```tsx
+     * interface Props {
+     *   children?: ReactNode;
+     *   type: "submit" | "button";
+     * }
+     *
+     * export const FancyButton = forwardRef<HTMLButtonElement, Props>((props, ref) => (
+     *   <button ref={ref} className="MyClassName" type={props.type}>
+     *     {props.children}
+     *   </button>
+     * ));
+     * ```
+     */
     function forwardRef<T, P = {}>(
         render: ForwardRefRenderFunction<T, P>,
     ): ForwardRefExoticComponent<PropsWithoutRef<P> & RefAttributes<T>>;
@@ -852,28 +1090,107 @@ declare namespace React {
     type PropsWithChildren<P = unknown> = P & { children?: ReactNode | undefined };
 
     /**
-     * NOTE: prefer ComponentPropsWithRef, if the ref is forwarded,
-     * or ComponentPropsWithoutRef when refs are not supported.
+     * Used to retrieve the props a component accepts. Can either be passed a string,
+     * indicating a DOM element (e.g. 'div', 'span', etc.) or the type of a React
+     * component.
+     *
+     * It's usually better to use {@link ComponentPropsWithRef} or {@link ComponentPropsWithoutRef}
+     * 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/ React TypeScript Cheatsheet}
+     *
+     * @example
+     *
+     * ```tsx
+     * // Retrieves the props an 'input' element accepts
+     * type InputProps = React.ComponentProps<'input'>;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * const MyComponent = (props: { foo: number, bar: string }) => <div />;
+     *
+     * // Retrieves the props 'MyComponent' accepts
+     * type MyComponentProps = React.ComponentProps<typeof MyComponent>;
+     * ```
      */
     type ComponentProps<T extends keyof JSX.IntrinsicElements | JSXElementConstructor<any>> = T extends
         JSXElementConstructor<infer P> ? P
         : T extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[T]
         : {};
+
     /**
-     * Get the props of a component that supports the `ref` prop.
+     * Used to retrieve the props a component accepts with its ref. Can either be
+     * 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/ React TypeScript Cheatsheet}
      *
-     * WARNING: Use `CustomComponentPropsWithRef` if you know that `T` is not a host component for better type-checking performance.
+     * @example
+     *
+     * ```tsx
+     * // Retrieves the props an 'input' element accepts
+     * type InputProps = React.ComponentPropsWithRef<'input'>;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * const MyComponent = (props: { foo: number, bar: string }) => <div />;
+     *
+     * // Retrieves the props 'MyComponent' accepts
+     * type MyComponentPropsWithRef = React.ComponentPropsWithRef<typeof MyComponent>;
+     * ```
      */
     type ComponentPropsWithRef<T extends ElementType> = T extends (new(props: infer P) => Component<any, any>)
         ? PropsWithoutRef<P> & RefAttributes<InstanceType<T>>
         : PropsWithRef<ComponentProps<T>>;
     /**
-     * Like `ComponentPropsWithRef` but without support for host components (i.e. just "custom components") to improve type-checking performance.
+     * Used to retrieve the props a custom component accepts with its ref.
+     *
+     * Unlike {@link ComponentPropsWithRef}, this only works with custom
+     * components, i.e. components you define yourself. This is to improve
+     * type-checking performance.
+     *
+     * @example
+     *
+     * ```tsx
+     * const MyComponent = (props: { foo: number, bar: string }) => <div />;
+     *
+     * // Retrieves the props 'MyComponent' accepts
+     * type MyComponentPropsWithRef = React.CustomComponentPropsWithRef<typeof MyComponent>;
+     * ```
      */
     type CustomComponentPropsWithRef<T extends ComponentType> = T extends (new(props: infer P) => Component<any, any>)
         ? (PropsWithoutRef<P> & RefAttributes<InstanceType<T>>)
         : T extends ((props: infer P, legacyContext?: any) => ReactNode) ? PropsWithRef<P>
         : never;
+
+    /**
+     * Used to retrieve the props a component accepts without its ref. Can either be
+     * 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/ React TypeScript Cheatsheet}
+     *
+     * @example
+     *
+     * ```tsx
+     * // Retrieves the props an 'input' element accepts
+     * type InputProps = React.ComponentPropsWithoutRef<'input'>;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * const MyComponent = (props: { foo: number, bar: string }) => <div />;
+     *
+     * // Retrieves the props 'MyComponent' accepts
+     * type MyComponentPropsWithoutRef = React.ComponentPropsWithoutRef<typeof MyComponent>;
+     * ```
+     */
     type ComponentPropsWithoutRef<T extends ElementType> = PropsWithoutRef<ComponentProps<T>>;
 
     type ComponentRef<T extends ElementType> = T extends NamedExoticComponent<

react/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/react",
-    "version": "18.2.48",
+    "version": "18.2.50",
     "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": "fc13b2b40312ff0746a89155473d332ecb923a60c52ab414c3711f90c1230bbe",
+    "typesPublisherContentHash": "de06a0c7b26443a49092798af7022732df079fdccd6114cb9ad9dbe3f9d35963",
     "typeScriptVersion": "4.6"
 }