[Beta] Added documentation for React.createFactory (#5120)

* Added documentation for React.createFactory

* Update beta/src/content/apis/react/createFactory.md

Co-authored-by: Strek <[email protected]>

* minor editorial updates (#2)

* Update createFactory.md

* Update createFactory.md

* edits

Co-authored-by: Strek <[email protected]>
Co-authored-by: Holly Sweeney <[email protected]>
Co-authored-by: Dan Abramov <[email protected]>

beta/src/components/MDX/ExpandableCallout.tsx

@@ -6,16 +6,25 @@ import {useRef} from 'react';
 import * as React from 'react';
 import cn from 'classnames';
 import {IconNote} from '../Icon/IconNote';
+import {IconWarning} from '../Icon/IconWarning';
 import {IconGotcha} from '../Icon/IconGotcha';
 
-type CalloutVariants = 'gotcha' | 'note' | 'wip';
+type CalloutVariants = 'deprecated' | 'gotcha' | 'note' | 'wip';
 
 interface ExpandableCalloutProps {
   children: React.ReactNode;
   type: CalloutVariants;
 }
 
 const variantMap = {
+  deprecated: {
+    title: 'Deprecated',
+    Icon: IconWarning,
+    containerClasses: 'bg-red-5 dark:bg-red-60 dark:bg-opacity-20',
+    textColor: 'text-red-50 dark:text-red-40',
+    overlayGradient:
+      'linear-gradient(rgba(249, 247, 243, 0), rgba(249, 247, 243, 1)',
+  },
   note: {
     title: 'Note',
     Icon: IconNote,

beta/src/components/MDX/MDXComponents.tsx

@@ -79,6 +79,9 @@ const Wip = ({children}: {children: React.ReactNode}) => (
 const Gotcha = ({children}: {children: React.ReactNode}) => (
   <ExpandableCallout type="gotcha">{children}</ExpandableCallout>
 );
+const Deprecated = ({children}: {children: React.ReactNode}) => (
+  <ExpandableCallout type="deprecated">{children}</ExpandableCallout>
+);
 const Note = ({children}: {children: React.ReactNode}) => (
   <ExpandableCallout type="note">{children}</ExpandableCallout>
 );
@@ -369,6 +372,7 @@ export const MDXComponents = {
     return <div className="max-w-4xl ml-0 2xl:mx-auto">{children}</div>;
   },
   Gotcha,
+  Deprecated,
   Wip,
   HomepageHero,
   Illustration,

beta/src/content/apis/react/createFactory.md

@@ -2,19 +2,143 @@
 title: createFactory
 ---
 
-<Wip>
+<Deprecated>
 
-This section is incomplete, please see the old docs for [createFactory.](https://reactjs.org/docs/react-api.html#createfactory)
-
-</Wip>
+This API will be removed in a future major version of React. Use [JSX](/learn/writing-markup-with-jsx) or [`createElement`](/api/react/createElement) instead.
 
+</Deprecated>
 
 <Intro>
 
+`createFactory` lets you create a function that produces React elements of a given type.
+
 ```js
-React.createFactory(type)
+const factory = createFactory(type)
 ```
 
 </Intro>
 
 <InlineToc />
+
+---
+
+## Usage {/*usage*/}
+
+### Creating React elements {/*creating-react-elements*/}
+
+You shouldn't use `createFactory` in new code. In the existing code, it's typically used as an alternative to [JSX:](/learn/writing-markup-with-jsx)
+
+<Sandpack>
+
+```js App.js
+import { createFactory } from 'react';
+
+const button = createFactory('button');
+
+export default function App() {
+  return button({
+    onClick: () => {
+      alert('Clicked!')
+    }
+  }, 'Click me');
+}
+```
+
+</Sandpack>
+
+Since `createFactory` has been deprecated, you need to remove it from your project's code.
+
+For example, you can convert it to use [`createElement`](/api/react/createElement) instead of `createFactory` like this:
+
+<Sandpack>
+
+```js App.js
+import { createElement } from 'react';
+
+export default function App() {
+  return createElement('button', {
+    onClick: () => {
+      alert('Clicked!')
+    }
+  }, 'Click me');
+};
+```
+
+</Sandpack>
+
+Alternatively, you can convert it to use [JSX:](/learn/writing-markup-with-jsx)
+
+<Sandpack>
+
+```js App.js
+export default function App() {
+  return (
+    <button onClick={() => {
+      alert('Clicked!');
+    }}>
+      Click me
+    </button>
+  );
+};
+```
+
+</Sandpack>
+
+Every pattern that uses `createFactory` can be converted to either of the two styles above.
+
+<DeepDive title="How is createFactory implemented?">
+
+The full implementation of `createFactory` looks like this:
+
+```js
+import { createElement } from 'react';
+
+function createFactory(type) {
+  return createElement.bind(null, type);
+}
+```
+
+If your project uses `createFactory` a lot, you may copy this helper into your project or publish it on npm.
+
+</DeepDive>
+
+---
+
+## Reference {/*reference*/}
+
+### `createFactory(type)` {/*createfactory*/}
+
+
+<Deprecated>
+
+This API will be removed in a future major version of React. Use [JSX](/learn/writing-markup-with-jsx) or [`createElement`](/api/react/createElement) instead.
+
+</Deprecated>
+
+Call `createFactory(type)` to create a factory function which produces React elements of a given `type`.
+
+```js
+import { createFactory } from 'react';
+
+const button = createFactory('button');
+```
+
+Then you can use it to create React elements without JSX:
+
+```js
+export default function App() {
+  return button({
+    onClick: () => {
+      alert('Clicked!')
+    }
+  }, 'Click me');
+}
+```
+
+#### Parameters {/*parameters*/}
+
+* `type`: The `type` argument must be a valid React component type. For example, it could be a tag name string (such as `'div'` or `'span'`), or a React component (a function, a class, or a special component like [`Fragment`](/apis/react/Fragment)).
+
+#### Returns {/*returns*/}
+
+Returns a factory function. That factory function receives a `props` object as the first argument, followed by a list of `...children` arguments, and returns a React element with the given `type`, `props` and `children`.

beta/src/sidebarReference.json

@@ -37,8 +37,7 @@
             },
             {
               "title": "createFactory",
-              "path": "/apis/react/createFactory",
-              "wip": true
+              "path": "/apis/react/createFactory"
             },
             {
               "title": "createRef",