[Beta] Add Alternatives to createFactory API (#5149)

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

@@ -4,7 +4,7 @@ title: 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.
+This API will be removed in a future major version of React. [See the alternatives.](#alternatives)
 
 </Deprecated>
 
@@ -24,9 +24,25 @@ const factory = createFactory(type)
 
 ## Usage {/*usage*/}
 
-### Creating React elements {/*creating-react-elements*/}
+### Creating React elements with a factory {/*creating-react-elements-with-a-factory*/}
 
-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)
+<Deprecated>
+
+This API will be removed in a future major version of React. [See the alternatives.](#alternatives)
+
+</Deprecated>
+
+Although most React projects use [JSX](/learn/writing-markup-with-jsx) to describe the user interface, JSX is not required. In the past, `createFactory` used to be one of the ways you could describe the user interface without JSX.
+
+Call `createFactory` to create a *factory function* for a specific element type like `'button'`:
+
+```js
+import { createFactory } from 'react';
+
+const button = createFactory('button');
+```
+
+Calling that factory function will produce React elements with the props and children you have provided:
 
 <Sandpack>
 
@@ -46,13 +62,68 @@ export default function App() {
 
 </Sandpack>
 
-Since `createFactory` has been deprecated, you need to remove it from your project's code.
+This is how `createFactory` was used as an alternative to JSX. However, `createFactory` is deprecated, and you should not call `createFactory` in any new code. See how to migrate away from `createFactory` below.
+
+---
+
+## Alternatives {/*alternatives*/}
 
-For example, you can convert it to use [`createElement`](/api/react/createElement) instead of `createFactory` like this:
+### Copying `createFactory` into your project {/*copying-createfactory-into-your-project*/}
+
+If your project has many `createFactory` calls, copy this `createFactory.js` implementation into your project:
 
 <Sandpack>
 
 ```js App.js
+import { createFactory } from './createFactory.js';
+
+const button = createFactory('button');
+
+export default function App() {
+  return button({
+    onClick: () => {
+      alert('Clicked!')
+    }
+  }, 'Click me');
+}
+```
+
+```js createFactory.js
+import { createElement } from 'react';
+
+export function createFactory(type) {
+  return createElement.bind(null, type);
+}
+```
+
+</Sandpack>
+
+This lets you keep all of your code unchanged except the imports.
+
+---
+
+### Replacing `createFactory` with `createElement` {/*replacing-createfactory-with-createelement*/}
+
+If you have a few `createFactory` calls that you don't mind porting manually, and you don't want to use JSX, you can replace every call a factory function with a [`createElement`](/api/react/createElement) call. For example, you can replace this code:
+
+```js {1,3,6}
+import { createFactory } from 'react';
+
+const button = createFactory('button');
+
+export default function App() {
+  return button({
+    onClick: () => {
+      alert('Clicked!')
+    }
+  }, 'Click me');
+}
+```
+
+with this code:
+
+
+```js {1,4}
 import { createElement } from 'react';
 
 export default function App() {
@@ -61,12 +132,32 @@ export default function App() {
       alert('Clicked!')
     }
   }, 'Click me');
-};
+}
+```
+
+Here is a complete example of using React without JSX:
+
+<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)
+---
+
+### Replacing `createFactory` with JSX {/*replacing-createfactory-with-jsx*/}
+
+Finally, you can use JSX instead of `createFactory`. This is the most common way to use React:
 
 <Sandpack>
 
@@ -84,23 +175,30 @@ export default function App() {
 
 </Sandpack>
 
-Every pattern that uses `createFactory` can be converted to either of the two styles above.
+<Gotcha>
 
-<DeepDive title="How is createFactory implemented?">
+Sometimes, your existing code might pass some variable as a `type` instead of a constant like `'button'`:
 
-The full implementation of `createFactory` looks like this:
+```js {3}
+function Heading({ isSubheading, ...props }) {
+  let type = isSubheading ? 'h2' : 'h1';
+  const factory = createFactory(type);
+  return factory(props);
+}
+```
 
-```js
-import { createElement } from 'react';
+To do the same in JSX, you need to rename your variable to start with an uppercase letter like `Type`:
 
-function createFactory(type) {
-  return createElement.bind(null, type);
+```js {2,3}
+function Heading({ size, ...props }) {
+  let Type = isSubheading ? 'h2' : 'h1';
+  return <Type {...props} />;
 }
 ```
 
-If your project uses `createFactory` a lot, you may copy this helper into your project or publish it on npm.
+Otherwise React will interpret `<type>` as a built-in HTML tag because it is lowercase.
 
-</DeepDive>
+</Gotcha>
 
 ---
 
@@ -108,10 +206,9 @@ If your project uses `createFactory` a lot, you may copy this helper into your p
 
 ### `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.
+This API will be removed in a future major version of React. [See the alternatives.](#alternatives)
 
 </Deprecated>