[Beta] Reorder API sections (#4328)

* Reorder API pages

* Tweaks

Author: gaearon

beta/src/components/MDX/MDXComponents.tsx

@@ -3,6 +3,7 @@
  */
 
 import * as React from 'react';
+import cn from 'classnames';
 
 import {APIAnatomy, AnatomyStep} from './APIAnatomy';
 import CodeBlock from './CodeBlock';
@@ -26,6 +27,24 @@ import {Challenges, Hint, Solution} from './Challenges';
 import {IconNavArrow} from '../Icon/IconNavArrow';
 import ButtonLink from 'components/ButtonLink';
 
+function CodeStep({children, step}: {children: any; step: number}) {
+  return (
+    <span
+      data-step={step}
+      className={cn(
+        'code-step bg-opacity-10 relative rounded-md p-1 ml-2 pl-3 before:content-[attr(data-step)] before:block before:w-4 before:h-4 before:absolute before:top-1 before:-left-2 before:rounded-full before:text-white before:text-center before:text-xs before:leading-4',
+        {
+          'bg-blue-40 before:bg-blue-40': step === 1,
+          'bg-yellow-40 before:bg-yellow-40': step === 2,
+          'bg-green-40 before:bg-green-40': step === 3,
+          'bg-purple-40 before:bg-purple-40': step === 4,
+        }
+      )}>
+      {children}
+    </span>
+  );
+}
+
 const P = (p: JSX.IntrinsicElements['p']) => (
   <p className="whitespace-pre-wrap my-4" {...p} />
 );
@@ -373,4 +392,5 @@ export const MDXComponents = {
   Challenges,
   Hint,
   Solution,
+  CodeStep,
 };

beta/src/pages/apis/index.md

@@ -34,9 +34,16 @@ If you use React on the web, you'll also need the same version of [ReactDOM](/ap
 
 ## Exports {/*exports*/}
 
-<YouWillLearnCard title="useState" path="/reference/usestate">
+<YouWillLearnCard title="useState" path="/apis/usestate">
+
+Declares a state variable.
+
+```js
+function MyComponent() {
+  const [age, setAge] = useState(42);
+  // ...
+```
 
-A React Hook that lets a component "remember" some information (called state).
 
 </YouWillLearnCard>
 

beta/src/pages/apis/reactdom.md

@@ -38,9 +38,13 @@ ReactDOM supports all popular browsers, including Internet Explorer 9 and above.
 
 ## Exports {/*exports*/}
 
-<YouWillLearnCard title="render" path="/reference/render">
+<YouWillLearnCard title="render" path="/apis/render">
 
-Renders a piece of JSX ("React element") into a browser DOM container node.
+Displays a React component inside a browser DOM node.
+
+```js
+render(<App />, document.getElementById('root'));
+```
 
 </YouWillLearnCard>
 

beta/src/pages/apis/render.md

@@ -1,104 +1,40 @@
 ---
-title: render()
+title: render
 ---
 
 <Intro>
 
 `render` renders a piece of [JSX](/learn/writing-markup-with-jsx) ("React node") into a browser DOM node.
 
-</Intro>
+```js
+render(reactNode, domNode, callback?)
+```
 
-## On this page {/*on-this-page*/}
+</Intro>
 
-- [Reference](#reference)
-  - [`render(reactNode, domNode)`](#render)
-  - [`render(reactNode, domNode, callback)`](#render-callback)
 - [Usage](#usage)
   - [Rendering the root component](#rendering-the-root-component)
   - [Rendering multiple roots](#rendering-multiple-roots)
   - [Updating the rendered tree](#updating-the-rendered-tree)
-
-## Reference {/*reference*/}
-
-### `render(reactNode, domNode)` {/*render*/}
-
-Call `render` to display a React component inside a browser DOM element.
-
-```js
-const domNode = document.getElementById('root');
-render(<App />, domNode);
-```
-
-React will display `<App />` in the `domNode`, and take over managing the DOM inside it.
-
-An app fully built with React will usually only have one `render` call with its root component.  A page that uses "sprinkles" of React for parts of the page may have as many `render` calls as needed.
-
-[See examples below.](#usage)
-
-#### Parameters {/*parameters*/}
-
-* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like `<App />`, but you can also pass a React element constructed with [`createElement()`](/TODO), a string, a number, `null`, or `undefined`. 
-
-* `domNode`: A [DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element). React will display the `reactNode` you pass inside this DOM element. From this moment, React will manage the DOM inside the `domNode` and update it when your React tree changes.
-
-#### Returns {/*returns*/}
-
-`render` usually returns `null`. However, if the `reactNode` you pass is a *class component*, then it will return an instance of that component.
-
-#### Caveats {/*caveats*/}
-
-* The first time you call `render`, React will clear all the existing HTML content inside the `domNode` before rendering the React component into it. If your `domNode` contains HTML generated by React on the server or during the build, use [`hydrate()`](/TODO) instead, which attaches the event handlers to the existing HTML.
-
-* If you call `render` on the same `domNode` more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by ["matching it up"](/learn/preserving-and-resetting-state) with the previously rendered tree. Calling `render` on the same `domNode` again is similar to calling the [`set` function](/apis/usestate#setstate) on the root component: React avoids unnecessary DOM updates.
-
-* If your app is fully built with React, you'll likely have only one `render` call in your app. (If you use a framework, it might do this call for you.) When you want to render a piece of JSX in a different part of the DOM tree that isn't a child of your component (for example, a modal or a tooltip), use [`createPortal`](TODO) instead of `render`.
-
----
-
-### `render(reactNode, domNode, callback)` {/*render-callback*/}
-
-Same as [`render(reactNode, domNode)`](#render), but with a `callback` that notifies you when your component has been placed into the DOM.
-
-#### Parameters {/*render-callback-parameters*/}
-
-* `reactNode`: [Same as above.](#parameters)
-* `domNode`: [Same as above.](#parameters)
-* `callback`: A function. If passed, React will call it after your component is placed into the DOM.
-
-#### Returns {/*render-callback-returns*/}
-
-[Same as above.](#returns)
+- [Reference](#reference)
+  - [`render(reactNode, domNode, callback?)`](#render)
 
 ---
 
 ## Usage {/*usage*/}
 
-### Rendering the root component {/*rendering-the-root-component*/}
-
-To call `render`, you need a piece of JSX and a DOM container:
-
-<APIAnatomy>
-
-<AnatomyStep title="React node">
-
-The UI you want to render.
+Call `render` to display a <CodeStep step={1}>React component</CodeStep> inside a <CodeStep step={2}>browser DOM node</CodeStep>.
 
-</AnatomyStep>
-
-<AnatomyStep title="DOM node">
-
-The DOM node you want to render your UI into. The container itself isn’t modified, only its children are.
-
-</AnatomyStep>
+```js [[1, 4, "<App />"], [2, 4, "document.getElementById('root')"]]
+import {render} from 'react-dom';
+import App from './App.js';
 
-```js [[1, 2, "<App />"], [2, 2, "domNode"]]
-const domNode = document.getElementById('root');
-render(<App />, domNode);
-```
+render(<App />, document.getElementById('root'));
+````
 
-</APIAnatomy>
+### Rendering the root component {/*rendering-the-root-component*/}
 
-In apps fully built with React, you will do this once at the top level of your app--to render the "root" component.
+In apps fully built with React, **you will usually only do this once at startup**--to render the "root" component.
 
 <Sandpack>
 
@@ -118,11 +54,13 @@ export default function App() {
 
 </Sandpack>
 
+Usually you shouldn't need to call `render` again or to call it in more places. From this point on, React will be managing the DOM of your application. If you want to update the UI, your components can do this by [using state](/apis/usestate).
+
 ---
 
 ### Rendering multiple roots {/*rendering-multiple-roots*/}
 
-If you use ["sprinkles"](/learn/add-react-to-a-website) of React here and there, call `render` for each top-level piece of UI managed by React.
+If your page [isn't fully built with React](/learn/add-react-to-a-website), call `render` for each top-level piece of UI managed by React.
 
 <Sandpack>
 
@@ -192,16 +130,19 @@ nav ul li { display: inline-block; margin-right: 20px; }
 
 </Sandpack>
 
+You can destroy the rendered trees with [`unmountComponentAtNode()`](TODO).
+
 ---
 
 ### Updating the rendered tree {/*updating-the-rendered-tree*/}
 
-You can call `render` more than once on the same DOM node. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state](/learn/preserving-and-resetting-state). Notice how you can type in the input:
+You can call `render` more than once on the same DOM node. As long as the component tree structure matches up with what was previously rendered, React will [preserve the state](/learn/preserving-and-resetting-state). Notice how you can type in the input, which means that the updates from repeated `render` calls every second in this example are not destructive:
 
 <Sandpack>
 
 ```js index.js active
 import {render} from 'react-dom';
+import './styles.css';
 import App from './App.js';
 
 let i = 0;
@@ -227,4 +168,46 @@ export default function App({counter}) {
 
 </Sandpack>
 
-You can destroy the rendered tree with [`unmountComponentAtNode()`](TODO).
+It is uncommon to call `render` multiple times. Usually, you'll [update state](/apis/usestate) inside one of the components instead.
+
+---
+
+## Reference {/*reference*/}
+
+### `render(reactNode, domNode, callback?)` {/*render*/}
+
+Call `render` to display a React component inside a browser DOM element.
+
+```js
+const domNode = document.getElementById('root');
+render(<App />, domNode);
+```
+
+React will display `<App />` in the `domNode`, and take over managing the DOM inside it.
+
+An app fully built with React will usually only have one `render` call with its root component.  A page that uses "sprinkles" of React for parts of the page may have as many `render` calls as needed.
+
+[See examples above.](#usage)
+
+#### Parameters {/*parameters*/}
+
+* `reactNode`: A *React node* that you want to display. This will usually be a piece of JSX like `<App />`, but you can also pass a React element constructed with [`createElement()`](/TODO), a string, a number, `null`, or `undefined`. 
+
+* `domNode`: A [DOM element](https://developer.mozilla.org/en-US/docs/Web/API/Element). React will display the `reactNode` you pass inside this DOM element. From this moment, React will manage the DOM inside the `domNode` and update it when your React tree changes.
+
+* **optional** `callback`: A function. If passed, React will call it after your component is placed into the DOM.
+
+
+#### Returns {/*returns*/}
+
+`render` usually returns `null`. However, if the `reactNode` you pass is a *class component*, then it will return an instance of that component.
+
+#### Caveats {/*caveats*/}
+
+* The first time you call `render`, React will clear all the existing HTML content inside the `domNode` before rendering the React component into it. If your `domNode` contains HTML generated by React on the server or during the build, use [`hydrate()`](/TODO) instead, which attaches the event handlers to the existing HTML.
+
+* If you call `render` on the same `domNode` more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by ["matching it up"](/learn/preserving-and-resetting-state) with the previously rendered tree. Calling `render` on the same `domNode` again is similar to calling the [`set` function](/apis/usestate#setstate) on the root component: React avoids unnecessary DOM updates.
+
+* If your app is fully built with React, you'll likely have only one `render` call in your app. (If you use a framework, it might do this call for you.) When you want to render a piece of JSX in a different part of the DOM tree that isn't a child of your component (for example, a modal or a tooltip), use [`createPortal`](TODO) instead of `render`.
+
+---