@types/react 18.2.52 → 18.2.54

react/ts5.0/index.d.ts

@@ -20,11 +20,26 @@ type NativePointerEvent = PointerEvent;
 type NativeTransitionEvent = TransitionEvent;
 type NativeUIEvent = UIEvent;
 type NativeWheelEvent = WheelEvent;
+
+/**
+ * Used to represent DOM API's where users can either pass
+ * true or false as a boolean or as its equivalent strings.
+ */
 type Booleanish = boolean | "true" | "false";
+
+/**
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin MDN}
+ */
 type CrossOrigin = "anonymous" | "use-credentials" | "" | undefined;
 
 declare const UNDEFINED_VOID_ONLY: unique symbol;
-// Destructors are only allowed to return void.
+
+/**
+ * The function returned from an effect passed to {@link React.useEffect useEffect},
+ * which can be used to clean up the effect when the component unmounts.
+ *
+ * @see {@link https://react.dev/reference/react/useEffect React Docs}
+ */
 type Destructor = () => void | { [UNDEFINED_VOID_ONLY]: never };
 type VoidOrUndefinedOnly = void | { [UNDEFINED_VOID_ONLY]: never };
 
@@ -37,52 +52,158 @@ declare namespace React {
     // React Elements
     // ----------------------------------------------------------------------
 
-    type ElementType<P = any> =
-        | {
-            [K in keyof JSX.IntrinsicElements]: P extends JSX.IntrinsicElements[K] ? K : never;
-        }[keyof JSX.IntrinsicElements]
+    /**
+     * Used to retrieve the possible components which accept a given set of props.
+     *
+     * Can be passed no type parameters to get a union of all possible components
+     * and tags.
+     *
+     * Is a superset of {@link ComponentType}.
+     *
+     * @template P The props to match against. If not passed, defaults to any.
+     * @template Tag An optional tag to match against. If not passed, attempts to match against all possible tags.
+     *
+     * @example
+     *
+     * ```tsx
+     * // All components and tags (img, embed etc.)
+     * // which accept `src`
+     * type SrcComponents = ElementType<{ src: any }>;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // All components
+     * type AllComponents = ElementType;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // All custom components which match `src`, and tags which
+     * // match `src`, narrowed down to just `audio` and `embed`
+     * type SrcComponents = ElementType<{ src: any }, 'audio' | 'embed'>;
+     * ```
+     */
+    type ElementType<P = any, Tag extends keyof JSX.IntrinsicElements = keyof JSX.IntrinsicElements> =
+        | { [K in Tag]: P extends JSX.IntrinsicElements[K] ? K : never }[Tag]
         | ComponentType<P>;
+
+    /**
+     * Represents any user-defined component, either as a function component or
+     * a class component.
+     *
+     * @template P The props the component accepts.
+     *
+     * @see {@link ComponentClass}
+     * @see {@link FunctionComponent}
+     */
     type ComponentType<P = {}> = ComponentClass<P> | FunctionComponent<P>;
 
+    /**
+     * Represents any user-defined component, either as a function or a class.
+     *
+     * Similar to {@link ComponentType}, but without extra properties like
+     * {@link FunctionComponent.defaultProps defaultProps } and
+     * {@link ComponentClass.contextTypes contextTypes}.
+     *
+     * @template P The props the component accepts.
+     */
     type JSXElementConstructor<P> =
         | ((
             props: P,
             /**
-             * @deprecated https://legacy.react/ts5.0js.org/docs/legacy-context.html#referencing-context-in-stateless-function-components
+             * @deprecated
+             *
+             * @see {@link https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-stateless-function-components React Docs}
              */
             deprecatedLegacyContext?: any,
         ) => ReactElement<any, any> | null)
         | (new(
             props: P,
             /**
-             * @deprecated https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods
+             * @deprecated
+             *
+             * @see {@link https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods React Docs}
              */
             deprecatedLegacyContext?: any,
         ) => Component<any, any>);
 
+    /**
+     * A readonly ref container where {@link current} cannot be mutated.
+     *
+     * Created by {@link createRef}, or {@link useRef} when passed `null`.
+     *
+     * @template T The type of the ref's value.
+     *
+     * @example
+     *
+     * ```tsx
+     * const ref = createRef<HTMLDivElement>();
+     *
+     * ref.current = document.createElement('div'); // Error
+     * ```
+     */
     interface RefObject<T> {
+        /**
+         * The current value of the ref.
+         */
         readonly current: T | null;
     }
-    // Bivariance hack for consistent unsoundness with RefObject
+
+    /**
+     * A callback fired whenever the ref's value changes.
+     *
+     * @template T The type of the ref's value.
+     *
+     * @see {@link https://react.dev/reference/react-dom/components/common#ref-callback React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * <div ref={(node) => console.log(node)} />
+     * ```
+     */
     type RefCallback<T> = { bivarianceHack(instance: T | null): void }["bivarianceHack"];
+
+    /**
+     * A union type of all possible shapes for React refs.
+     *
+     * @see {@link RefCallback}
+     * @see {@link RefObject}
+     */
+
     type Ref<T> = RefCallback<T> | RefObject<T> | null;
+    /**
+     * A legacy implementation of refs where you can pass a string to a ref prop.
+     *
+     * @see {@link https://react.dev/reference/react/Component#refs React Docs}
+     *
+     * @example
+     *
+     * ```tsx
+     * <div ref="myRef" />
+     * ```
+     */
     type LegacyRef<T> = string | Ref<T>;
+
     /**
-     * Gets the instance type for a React element. The instance will be different for various component types:
+     * Retrieves the type of the 'ref' prop for a given component type or tag name.
      *
-     * - React class components will be the class instance. So if you had `class Foo extends React.Component<{}> {}`
-     *   and used `React.ElementRef<typeof Foo>` then the type would be the instance of `Foo`.
-     * - React stateless functional components do not have a backing instance and so `React.ElementRef<typeof Bar>`
-     *   (when `Bar` is `function Bar() {}`) will give you the `undefined` type.
-     * - JSX intrinsics like `div` will give you their DOM instance. For `React.ElementRef<'div'>` that would be
-     *   `HTMLDivElement`. For `React.ElementRef<'input'>` that would be `HTMLInputElement`.
-     * - React stateless functional components that forward a `ref` will give you the `ElementRef` of the forwarded
-     *   to component.
+     * @template C The component type.
      *
-     * `C` must be the type _of_ a React component so you need to use typeof as in `React.ElementRef<typeof MyComponent>`.
+     * @example
      *
-     * @todo In Flow, this works a little different with forwarded refs and the `AbstractComponent` that
-     *       `React.forwardRef()` returns.
+     * ```tsx
+     * type MyComponentRef = React.ElementRef<typeof MyComponent>;
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * type DivRef = React.ElementRef<'div'>;
+     * ```
      */
     type ElementRef<
         C extends
@@ -101,6 +222,11 @@ declare namespace React {
 
     type ComponentState = any;
 
+    /**
+     * A value which uniquely identifies a node among items in an array.
+     *
+     * @see {@link https://react.dev/learn/rendering-lists#keeping-list-items-in-order-with-key React Docs}
+     */
     type Key = string | number | bigint;
 
     /**
@@ -114,15 +240,18 @@ declare namespace React {
         /**
          * 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 https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom
+         * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom}
          */
         ref?: Ref<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 https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom
+         * @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom}
          */
         ref?: LegacyRef<T> | undefined;
     }
@@ -150,6 +279,9 @@ declare namespace React {
         ref?: LegacyRef<T> | undefined;
     }
 
+    /**
+     * @deprecated Use `ComponentElement<P, ClassicComponent<P, any>>` instead.
+     */
     type ClassicElement<P> = CElement<P, ClassicComponent<P, ComponentState>>;
 
     // string fallback for custom web-components
@@ -242,6 +374,34 @@ declare namespace React {
      * App or library types should never augment this interface.
      */
     interface DO_NOT_USE_OR_YOU_WILL_BE_FIRED_EXPERIMENTAL_REACT_NODES {}
+
+    /**
+     * Represents all of the things React can render.
+     *
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/react-types/reactnode/ React TypeScript Cheatsheet}
+     *
+     * @example
+     *
+     * ```tsx
+     * // Typing children
+     * type Props = { children: ReactNode }
+     *
+     * const Component = ({ children }: Props) => <div>{children}</div>
+     *
+     * <Component>hello</Component>
+     * ```
+     *
+     * @example
+     *
+     * ```tsx
+     * // Typing a custom element
+     * type Props = { customElement: ReactNode }
+     *
+     * const Component = ({ customElement }: Props) => <div>{customElement}</div>
+     *
+     * <Component customElement={<div>hello</div>} />
+     * ```
+     */
     type ReactNode =
         | ReactElement
         | string
@@ -272,9 +432,6 @@ declare namespace React {
 
     // Custom components
     function createFactory<P>(type: FunctionComponent<P>): FunctionComponentFactory<P>;
-    function createFactory<P>(
-        type: ClassType<P, ClassicComponent<P, ComponentState>, ClassicComponentClass<P>>,
-    ): CFactory<P, ClassicComponent<P, ComponentState>>;
     function createFactory<P, T extends Component<P, ComponentState>, C extends ComponentClass<P>>(
         type: ClassType<P, T, C>,
     ): CFactory<P, T>;
@@ -310,11 +467,6 @@ declare namespace React {
         props?: Attributes & P | null,
         ...children: ReactNode[]
     ): FunctionComponentElement<P>;
-    function createElement<P extends {}>(
-        type: ClassType<P, ClassicComponent<P, ComponentState>, ClassicComponentClass<P>>,
-        props?: ClassAttributes<ClassicComponent<P, ComponentState>> & P | null,
-        ...children: ReactNode[]
-    ): CElement<P, ClassicComponent<P, ComponentState>>;
     function createElement<P extends {}, T extends Component<P, ComponentState>, C extends ComponentClass<P>>(
         type: ClassType<P, T, C>,
         props?: ClassAttributes<T> & P | null,
@@ -369,53 +521,169 @@ declare namespace React {
         ...children: ReactNode[]
     ): ReactElement<P>;
 
-    // Context via RenderProps
+    /**
+     * Describes the props accepted by a Context {@link Provider}.
+     *
+     * @template T The type of the value the context provides.
+     */
     interface ProviderProps<T> {
         value: T;
         children?: ReactNode | undefined;
     }
 
+    /**
+     * Describes the props accepted by a Context {@link Consumer}.
+     *
+     * @template T The type of the value the context provides.
+     */
     interface ConsumerProps<T> {
         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 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.
+     */
     interface ExoticComponent<P = {}> {
-        /**
-         * **NOTE**: Exotic components are not callable.
-         */
         (props: P): ReactElement | null;
         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;
     }
 
+    /**
+     * 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
@@ -424,7 +692,9 @@ declare namespace React {
 
     function isValidElement<P>(object: {} | null | undefined): object is ReactElement<P>;
 
-    // Sync with `ReactChildren` until `ReactChildren` is removed.
+    /**
+     * Maintainer's note: Sync with {@link ReactChildren} until {@link ReactChildren} is removed.
+     */
     const Children: {
         map<T, C>(
             children: C | readonly C[],
@@ -435,9 +705,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;
 
@@ -445,27 +763,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>;
 
     //
@@ -481,7 +877,7 @@ declare namespace React {
         /**
          * If set, `this.context` will be set at runtime to the current value of the given Context.
          *
-         * Usage:
+         * @example
          *
          * ```ts
          * type MyContext = number
@@ -496,7 +892,7 @@ declare namespace React {
          * }
          * ```
          *
-         * @see https://react.dev/reference/react/Component#static-contexttype
+         * @see {@link https://react.dev/reference/react/Component#static-contexttype}
          */
         static contextType?: Context<any> | undefined;
 
@@ -505,6 +901,8 @@ declare namespace React {
          * `React.ContextType` of your `static contextType`.
          * Should be used with type annotation or static contextType.
          *
+         * @example
+         *
          * ```ts
          * static contextType = MyContext
          * // For TS pre-3.7:
@@ -513,14 +911,14 @@ declare namespace React {
          * declare context: React.ContextType<typeof MyContext>
          * ```
          *
-         * @see https://react.dev/reference/react/Component#context
+         * @see {@link https://react.dev/reference/react/Component#context}
          */
         context: unknown;
 
         constructor(props: Readonly<P> | P);
         /**
          * @deprecated
-         * @see https://legacy.reactjs.org/docs/legacy-context.html
+         * @see {@link https://legacy.reactjs.org/docs/legacy-context.html}
          */
         constructor(props: P, context: any);
 
@@ -548,6 +946,12 @@ declare namespace React {
 
     class PureComponent<P = {}, S = {}, SS = any> extends Component<P, S, SS> {}
 
+    /**
+     * @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;
         isMounted(): boolean;
@@ -562,23 +966,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.
+     *
+     * @template P The props the component accepts.
+     * @see {@link https://react-typescript-cheatsheet.netlify.app/docs/basic/getting-started/function_components React TypeScript Cheatsheet}
+     * @alias for {@link 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.
+     *
+     * @template 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): ReactElement<any, any> | null;
+        /**
+         * 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): ReactElement<any, any> | null;
@@ -588,42 +1109,126 @@ 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}. 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}.
+     *
+     * @template T The type of the forwarded ref.
+     * @template 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 = {}> {
         (props: P, ref: ForwardedRef<T>): ReactElement | null;
+        /**
+         * 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 render functions 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 render functions 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.
+     *
+     * @template P The props the component accepts.
+     * @template 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>;
         getDefaultProps?(): P;
     }
 
     /**
-     * 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.
+     * See {@link https://github.com/Microsoft/TypeScript/issues/7234 this GitHub issue}
+     * for more info.
      */
     type ClassType<P, T extends Component<P, ComponentState>, C extends ComponentClass<P>> =
         & C
@@ -648,7 +1253,7 @@ declare namespace React {
          * `PureComponent` implements a shallow comparison on props and state and returns true if any
          * props or states have changed.
          *
-         * If false is returned, `Component#render`, `componentWillUpdate`
+         * If false is returned, {@link Component.render}, `componentWillUpdate`
          * and `componentDidUpdate` will not be called.
          */
         shouldComponentUpdate?(nextProps: Readonly<P>, nextState: Readonly<S>, nextContext: any): boolean;
@@ -690,47 +1295,49 @@ declare namespace React {
     // This should be "infer SS" but can't use it yet
     interface NewLifecycle<P, S, SS> {
         /**
-         * Runs before React applies the result of `render` to the document, and
-         * returns an object to be given to componentDidUpdate. Useful for saving
-         * things such as scroll position before `render` causes changes to it.
+         * Runs before React applies the result of {@link Component.render render} to the document, and
+         * returns an object to be given to {@link componentDidUpdate}. Useful for saving
+         * things such as scroll position before {@link Component.render render} causes changes to it.
          *
-         * Note: the presence of getSnapshotBeforeUpdate prevents any of the deprecated
+         * Note: the presence of this method prevents any of the deprecated
          * lifecycle events from running.
          */
         getSnapshotBeforeUpdate?(prevProps: Readonly<P>, prevState: Readonly<S>): SS | null;
         /**
          * Called immediately after updating occurs. Not called for the initial render.
          *
-         * The snapshot is only present if getSnapshotBeforeUpdate is present and returns non-null.
+         * The snapshot is only present if {@link getSnapshotBeforeUpdate} is present and returns non-null.
          */
         componentDidUpdate?(prevProps: Readonly<P>, prevState: Readonly<S>, snapshot?: SS): void;
     }
 
     interface DeprecatedLifecycle<P, S> {
         /**
-         * Called immediately before mounting occurs, and before `Component#render`.
+         * Called immediately before mounting occurs, and before {@link Component.render}.
          * Avoid introducing any side-effects or subscriptions in this method.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use componentDidMount or the constructor instead; will stop working in React 17
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         componentWillMount?(): void;
         /**
-         * Called immediately before mounting occurs, and before `Component#render`.
+         * Called immediately before mounting occurs, and before {@link Component.render}.
          * Avoid introducing any side-effects or subscriptions in this method.
          *
          * This method will not stop working in React 17.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use componentDidMount or the constructor instead
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#initializing-state}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         UNSAFE_componentWillMount?(): void;
         /**
@@ -738,14 +1345,15 @@ declare namespace React {
          * React may call this even if props have not changed, so be sure to compare new and existing
          * props if you only want to handle changes.
          *
-         * Calling `Component#setState` generally does not trigger this method.
+         * Calling {@link Component.setState} generally does not trigger this method.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use static getDerivedStateFromProps instead; will stop working in React 17
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         componentWillReceiveProps?(nextProps: Readonly<P>, nextContext: any): void;
         /**
@@ -753,44 +1361,47 @@ declare namespace React {
          * React may call this even if props have not changed, so be sure to compare new and existing
          * props if you only want to handle changes.
          *
-         * Calling `Component#setState` generally does not trigger this method.
+         * Calling {@link Component.setState} generally does not trigger this method.
          *
          * This method will not stop working in React 17.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use static getDerivedStateFromProps instead
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#updating-state-based-on-props}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         UNSAFE_componentWillReceiveProps?(nextProps: Readonly<P>, nextContext: any): void;
         /**
          * Called immediately before rendering when new props or state is received. Not called for the initial render.
          *
-         * Note: You cannot call `Component#setState` here.
+         * Note: You cannot call {@link Component.setState} here.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use getSnapshotBeforeUpdate instead; will stop working in React 17
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         componentWillUpdate?(nextProps: Readonly<P>, nextState: Readonly<S>, nextContext: any): void;
         /**
          * Called immediately before rendering when new props or state is received. Not called for the initial render.
          *
-         * Note: You cannot call `Component#setState` here.
+         * Note: You cannot call {@link Component.setState} here.
          *
          * This method will not stop working in React 17.
          *
-         * Note: the presence of getSnapshotBeforeUpdate or getDerivedStateFromProps
-         * prevents this from being invoked.
+         * Note: the presence of {@link NewLifecycle.getSnapshotBeforeUpdate getSnapshotBeforeUpdate}
+         * or {@link StaticLifecycle.getDerivedStateFromProps getDerivedStateFromProps} prevents
+         * this from being invoked.
          *
          * @deprecated 16.3, use getSnapshotBeforeUpdate instead
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update
-         * @see https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#reading-dom-properties-before-an-update}
+         * @see {@link https://legacy.reactjs.org/blog/2018/03/27/update-on-async-rendering.html#gradual-migration-path}
          */
         UNSAFE_componentWillUpdate?(nextProps: Readonly<P>, nextState: Readonly<S>, nextContext: any): void;
     }
@@ -814,7 +1425,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;
@@ -824,18 +1437,54 @@ 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}.
+     *
+     * @template 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 a 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}.
+     *
+     * @template T The type of the DOM node.
+     * @template 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>>;
 
-    /** Ensures that the props do not include ref at all */
+    /**
+     * Omits the 'ref' attribute from the given props object.
+     *
+     * @template P The props object type.
+     */
     type PropsWithoutRef<P> =
         // Omit would not be sufficient for this. We'd like to avoid unnecessary mapping and need a distributive conditional to support unions.
         // see: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
@@ -854,28 +1503,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}
+     *
+     * @example
+     *
+     * ```tsx
+     * // Retrieves the props an 'input' element accepts
+     * type InputProps = React.ComponentPropsWithRef<'input'>;
+     * ```
      *
-     * WARNING: Use `CustomComponentPropsWithRef` if you know that `T` is not a host component for better type-checking performance.
+     * @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<
@@ -946,14 +1674,14 @@ declare namespace React {
      * context value, as given by the nearest context provider for the given context.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useContext
+     * @see {@link https://react.dev/reference/react/useContext}
      */
     function useContext<T>(context: Context<T> /*, (not public API) observedBits?: number|boolean */): T;
     /**
      * Returns a stateful value, and a function to update it.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useState
+     * @see {@link https://react.dev/reference/react/useState}
      */
     function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>];
     // convenience overload when first argument is omitted
@@ -961,7 +1689,7 @@ declare namespace React {
      * Returns a stateful value, and a function to update it.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useState
+     * @see {@link https://react.dev/reference/react/useState}
      */
     function useState<S = undefined>(): [S | undefined, Dispatch<SetStateAction<S | undefined>>];
     /**
@@ -972,7 +1700,7 @@ declare namespace React {
      * updates because you can pass `dispatch` down instead of callbacks.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useReducer
+     * @see {@link https://react.dev/reference/react/useReducer}
      */
     // overload where dispatch could accept 0 arguments.
     function useReducer<R extends ReducerWithoutAction<any>, I>(
@@ -988,7 +1716,7 @@ declare namespace React {
      * updates because you can pass `dispatch` down instead of callbacks.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useReducer
+     * @see {@link https://react.dev/reference/react/useReducer}
      */
     // overload where dispatch could accept 0 arguments.
     function useReducer<R extends ReducerWithoutAction<any>>(
@@ -1004,7 +1732,7 @@ declare namespace React {
      * updates because you can pass `dispatch` down instead of callbacks.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useReducer
+     * @see {@link https://react.dev/reference/react/useReducer}
      */
     // overload where "I" may be a subset of ReducerState<R>; used to provide autocompletion.
     // If "I" matches ReducerState<R> exactly then the last overload will allow initializer to be omitted.
@@ -1022,7 +1750,7 @@ declare namespace React {
      * updates because you can pass `dispatch` down instead of callbacks.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useReducer
+     * @see {@link https://react.dev/reference/react/useReducer}
      */
     // overload for free "I"; all goes as long as initializer converts it into "ReducerState<R>".
     function useReducer<R extends Reducer<any, any>, I>(
@@ -1038,7 +1766,7 @@ declare namespace React {
      * updates because you can pass `dispatch` down instead of callbacks.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useReducer
+     * @see {@link https://react.dev/reference/react/useReducer}
      */
 
     // I'm not sure if I keep this 2-ary or if I make it (2,3)-ary; it's currently (2,3)-ary.
@@ -1063,7 +1791,7 @@ declare namespace React {
      * value around similar to how you’d use instance fields in classes.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useRef
+     * @see {@link https://react.dev/reference/react/useRef}
      */
     function useRef<T>(initialValue: T): MutableRefObject<T>;
     // convenience overload for refs given as a ref prop as they typically start with a null value
@@ -1078,7 +1806,7 @@ declare namespace React {
      * of the generic argument.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useRef
+     * @see {@link https://react.dev/reference/react/useRef}
      */
     function useRef<T>(initialValue: T | null): RefObject<T>;
     // convenience overload for potentially undefined initialValue / call with 0 arguments
@@ -1091,7 +1819,7 @@ declare namespace React {
      * value around similar to how you’d use instance fields in classes.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useRef
+     * @see {@link https://react.dev/reference/react/useRef}
      */
     function useRef<T = undefined>(): MutableRefObject<T | undefined>;
     /**
@@ -1105,7 +1833,7 @@ declare namespace React {
      * `componentDidMount` and `componentDidUpdate`.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useLayoutEffect
+     * @see {@link https://react.dev/reference/react/useLayoutEffect}
      */
     function useLayoutEffect(effect: EffectCallback, deps?: DependencyList): void;
     /**
@@ -1115,7 +1843,7 @@ declare namespace React {
      * @param deps If present, effect will only activate if the values in the list change.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useEffect
+     * @see {@link https://react.dev/reference/react/useEffect}
      */
     function useEffect(effect: EffectCallback, deps?: DependencyList): void;
     // NOTE: this does not accept strings, but this will have to be fixed by removing strings from type Ref<T>
@@ -1126,7 +1854,7 @@ declare namespace React {
      * `useImperativeHandle` should be used with `React.forwardRef`.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useImperativeHandle
+     * @see {@link https://react.dev/reference/react/useImperativeHandle}
      */
     function useImperativeHandle<T, R extends T>(ref: Ref<T> | undefined, init: () => R, deps?: DependencyList): void;
     // I made 'inputs' required here and in useMemo as there's no point to memoizing without the memoization key
@@ -1136,7 +1864,7 @@ declare namespace React {
      * has changed.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useCallback
+     * @see {@link https://react.dev/reference/react/useCallback}
      */
     // A specific function type would not trigger implicit any.
     // See https://github.com/DefinitelyTyped/DefinitelyTyped/issues/52873#issuecomment-845806435 for a comparison between `Function` and more specific types.
@@ -1146,7 +1874,7 @@ declare namespace React {
      * `useMemo` will only recompute the memoized value when one of the `deps` has changed.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useMemo
+     * @see {@link https://react.dev/reference/react/useMemo}
      */
     // allow undefined, but don't make it optional as that is very likely a mistake
     function useMemo<T>(factory: () => T, deps: DependencyList): T;
@@ -1157,7 +1885,7 @@ declare namespace React {
      * It’s most valuable for custom hooks that are part of shared libraries.
      *
      * @version 16.8.0
-     * @see https://react.dev/reference/react/useDebugValue
+     * @see {@link https://react.dev/reference/react/useDebugValue}
      */
     // the name of the custom hook is itself derived from the function name at runtime:
     // it's just the function name without the "use" prefix.
@@ -1187,7 +1915,7 @@ declare namespace React {
      *
      * @param value The value that is going to be deferred
      *
-     * @see https://react.dev/reference/react/useDeferredValue
+     * @see {@link https://react.dev/reference/react/useDeferredValue}
      */
     export function useDeferredValue<T>(value: T): T;
 
@@ -1202,9 +1930,9 @@ declare namespace React {
      * The first is a boolean, React’s way of informing us whether we’re waiting for the transition to finish.
      * The second is a function that takes a callback. We can use it to tell React which state we want to defer.
      *
-     * **If some state update causes a component to suspend, that state update should be wrapped in a transition.**`
+     * **If some state update causes a component to suspend, that state update should be wrapped in a transition.**
      *
-     * @see https://react.dev/reference/react/useTransition
+     * @see {@link https://react.dev/reference/react/useTransition}
      */
     export function useTransition(): [boolean, TransitionStartFunction];
 
@@ -1221,7 +1949,7 @@ declare namespace React {
      * @param effect Imperative function that can return a cleanup function
      * @param deps If present, effect will only activate if the values in the list change.
      *
-     * @see https://github.com/facebook/react/pull/21913
+     * @see {@link https://github.com/facebook/react/pull/21913}
      */
     export function useInsertionEffect(effect: EffectCallback, deps?: DependencyList): void;
 
@@ -1229,7 +1957,7 @@ declare namespace React {
      * @param subscribe
      * @param getSnapshot
      *
-     * @see https://github.com/reactwg/react-18/discussions/86
+     * @see {@link https://github.com/reactwg/react-18/discussions/86}
      */
     // keep in sync with `useSyncExternalStore` from `use-sync-external-store`
     export function useSyncExternalStore<Snapshot>(
@@ -2022,12 +2750,12 @@ declare namespace React {
         // Living Standard
         /**
          * Hints at the type of data that might be entered by the user while editing the element or its contents
-         * @see https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute
+         * @see {@link https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute}
          */
         inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search" | undefined;
         /**
          * Specify that a standard HTML element should behave like a defined custom built-in element
-         * @see https://html.spec.whatwg.org/multipage/custom-elements.html#attr-is
+         * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#attr-is}
          */
         is?: string | undefined;
     }