From 73d7d13446791f5eec812941606202477aa10e10 Mon Sep 17 00:00:00 2001 From: dan Date: Fri, 4 Feb 2022 17:42:27 +0000 Subject: [PATCH] [Beta] Move /reference -> /apis (#4294) * [Beta] Move /reference -> /apis * come on * Update CONTRIBUTING.md * Update sidebarReference.json --- beta/CONTRIBUTING.md | 2 +- beta/plugins/md-layout-loader.js | 2 +- beta/src/components/Layout/Footer.tsx | 6 +++--- beta/src/components/Layout/Nav/MobileNav.tsx | 12 ++++++------ beta/src/components/Layout/Nav/Nav.tsx | 8 ++++---- beta/src/components/MDX/HomepageHero.tsx | 2 +- beta/src/components/useMenu.tsx | 2 +- beta/src/pages/{reference => apis}/index.md | 0 beta/src/pages/{reference => apis}/reactdom.md | 0 beta/src/pages/{reference => apis}/render.md | 0 beta/src/pages/{reference => apis}/usestate.md | 0 beta/src/pages/index.md | 2 +- beta/src/pages/learn/add-react-to-a-website.md | 2 +- beta/src/pages/learn/adding-interactivity.md | 2 +- beta/src/pages/learn/index.md | 4 ++-- beta/src/pages/learn/keeping-components-pure.md | 2 +- beta/src/pages/learn/reacting-to-input-with-state.md | 2 +- beta/src/pages/learn/responding-to-events.md | 2 +- beta/src/pages/learn/state-a-components-memory.md | 6 +++--- beta/src/pages/learn/thinking-in-react.md | 2 +- beta/src/sidebarReference.json | 10 +++++----- beta/vercel.json | 7 ++++++- 22 files changed, 40 insertions(+), 35 deletions(-) rename beta/src/pages/{reference => apis}/index.md (100%) rename beta/src/pages/{reference => apis}/reactdom.md (100%) rename beta/src/pages/{reference => apis}/render.md (100%) rename beta/src/pages/{reference => apis}/usestate.md (100%) diff --git a/beta/CONTRIBUTING.md b/beta/CONTRIBUTING.md index 328afd28..f893cab1 100644 --- a/beta/CONTRIBUTING.md +++ b/beta/CONTRIBUTING.md @@ -20,7 +20,7 @@ The documentation is divided into sections to cater to different learning styles **[Learn React](https://beta.reactjs.org/learn)** is designed to introduce fundamental concepts in a step-by-step way. Each individual article in Learn React builds on the knowledge from the previous ones, so make sure not to add any "cyclical dependencies" between them. It is important that the reader can start with the first article and work their way to the last Learn React article without ever having to "look ahead" for a definition. This explains some ordering choices (e.g. that state is explained before events, or that "thinking in React" doesn't use refs). Learn React also serves as a reference manual for React concepts, so it is important to be very strict about their definitions and relationships between them. -**[API Reference](https://reactjs.org/reference)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Learn React should be mentioned in the reference documentation for the corresponding APIs. +**[API Reference](https://reactjs.org/apis)** is organized by APIs rather than concepts. It is intended to be exhaustive. Any corner cases or recommendations that were skipped for brevity in Learn React should be mentioned in the reference documentation for the corresponding APIs. **Try to follow your own instructions.** diff --git a/beta/plugins/md-layout-loader.js b/beta/plugins/md-layout-loader.js index 1fee3136..25383925 100644 --- a/beta/plugins/md-layout-loader.js +++ b/beta/plugins/md-layout-loader.js @@ -23,7 +23,7 @@ module.exports = async function (src) { const layoutMap = { blog: 'Post', learn: 'Learn', - reference: 'API', + apis: 'API', }; const layout = layoutMap[pageParentDir] || 'Home'; const code = diff --git a/beta/src/components/Layout/Footer.tsx b/beta/src/components/Layout/Footer.tsx index dc08d4d6..f4db85b4 100644 --- a/beta/src/components/Layout/Footer.tsx +++ b/beta/src/components/Layout/Footer.tsx @@ -89,11 +89,11 @@ export function Footer() {
- + API Reference - React APIs - React DOM APIs + React APIs + React DOM APIs
diff --git a/beta/src/components/Layout/Nav/MobileNav.tsx b/beta/src/components/Layout/Nav/MobileNav.tsx index 2b310b43..fe96dffc 100644 --- a/beta/src/components/Layout/Nav/MobileNav.tsx +++ b/beta/src/components/Layout/Nav/MobileNav.tsx @@ -11,11 +11,11 @@ import sidebarHome from '../../../sidebarHome.json'; import sidebarLearn from '../../../sidebarLearn.json'; import sidebarReference from '../../../sidebarReference.json'; -function inferSection(pathname: string): 'learn' | 'reference' | 'home' { +function inferSection(pathname: string): 'learn' | 'apis' | 'home' { if (pathname.startsWith('/learn')) { return 'learn'; - } else if (pathname.startsWith('/reference')) { - return 'reference'; + } else if (pathname.startsWith('/apis')) { + return 'apis'; } else { return 'home'; } @@ -33,7 +33,7 @@ export function MobileNav() { case 'learn': tree = sidebarLearn.routes[0]; break; - case 'reference': + case 'apis': tree = sidebarReference.routes[0]; break; } @@ -52,8 +52,8 @@ export function MobileNav() { Learn setSection('reference')}> + isActive={section === 'apis'} + onClick={() => setSection('apis')}> API
diff --git a/beta/src/components/Layout/Nav/Nav.tsx b/beta/src/components/Layout/Nav/Nav.tsx index 98a130ce..0c6db813 100644 --- a/beta/src/components/Layout/Nav/Nav.tsx +++ b/beta/src/components/Layout/Nav/Nav.tsx @@ -86,11 +86,11 @@ const lightIcon = ( ); -function inferSection(pathname: string): 'learn' | 'reference' | 'home' { +function inferSection(pathname: string): 'learn' | 'apis' | 'home' { if (pathname.startsWith('/learn')) { return 'learn'; - } else if (pathname.startsWith('/reference')) { - return 'reference'; + } else if (pathname.startsWith('/apis')) { + return 'apis'; } else { return 'home'; } @@ -166,7 +166,7 @@ export default function Nav() { Learn - + API diff --git a/beta/src/components/MDX/HomepageHero.tsx b/beta/src/components/MDX/HomepageHero.tsx index 14f2580d..91959649 100644 --- a/beta/src/components/MDX/HomepageHero.tsx +++ b/beta/src/components/MDX/HomepageHero.tsx @@ -30,7 +30,7 @@ function HomepageHero() {
- +

Look up the API signatures of React Hooks, and see their shape using the visual code diagrams. diff --git a/beta/src/components/useMenu.tsx b/beta/src/components/useMenu.tsx index cdc81218..e7d52ab6 100644 --- a/beta/src/components/useMenu.tsx +++ b/beta/src/components/useMenu.tsx @@ -10,7 +10,7 @@ import { } from 'body-scroll-lock'; import {useRouter} from 'next/router'; -type SidebarNav = 'root' | 'docs' | 'reference'; +type SidebarNav = 'root' | 'docs' | 'apis'; /** * Menu toggle that enables body scroll locking (for * iOS Mobile and Tablet, Android, desktop Safari/Chrome/Firefox) diff --git a/beta/src/pages/reference/index.md b/beta/src/pages/apis/index.md similarity index 100% rename from beta/src/pages/reference/index.md rename to beta/src/pages/apis/index.md diff --git a/beta/src/pages/reference/reactdom.md b/beta/src/pages/apis/reactdom.md similarity index 100% rename from beta/src/pages/reference/reactdom.md rename to beta/src/pages/apis/reactdom.md diff --git a/beta/src/pages/reference/render.md b/beta/src/pages/apis/render.md similarity index 100% rename from beta/src/pages/reference/render.md rename to beta/src/pages/apis/render.md diff --git a/beta/src/pages/reference/usestate.md b/beta/src/pages/apis/usestate.md similarity index 100% rename from beta/src/pages/reference/usestate.md rename to beta/src/pages/apis/usestate.md diff --git a/beta/src/pages/index.md b/beta/src/pages/index.md index 313e6fb6..ba05d8e2 100644 --- a/beta/src/pages/index.md +++ b/beta/src/pages/index.md @@ -23,7 +23,7 @@ This is a **beta website**. There will be bugs, performance issues, and missing ## How much content is ready? {/*how-much-content-is-ready*/} * [Learn React](/learn): ~70% finished. -* [API Reference](/reference): ~5% finished. +* [API Reference](/apis): ~5% finished. You can track our progress [on GitHub](https://github.com/reactjs/reactjs.org/issues/3308). diff --git a/beta/src/pages/learn/add-react-to-a-website.md b/beta/src/pages/learn/add-react-to-a-website.md index f3d166bc..474514cb 100644 --- a/beta/src/pages/learn/add-react-to-a-website.md +++ b/beta/src/pages/learn/add-react-to-a-website.md @@ -230,7 +230,7 @@ If you're getting comfortable with build tools and want them to do more for you, Originally JSX was introduced to make writing components with React feel as familiar as writing HTML. Since then, the syntax has become widespread. However, there may be instances where you do not want to use or cannot use JSX. You have two options: - Use a JSX alternative like [htm](https://github.com/developit/htm) which doesn't use a compiler—it uses JavaScript's native Tagged Templates. -- Use [`React.createElement()`](/reference/createelement), which has a special structure explained below. +- Use [`React.createElement()`](/apis/createelement), which has a special structure explained below. With JSX, you would write a component like so: diff --git a/beta/src/pages/learn/adding-interactivity.md b/beta/src/pages/learn/adding-interactivity.md index 67a48ec4..2a93f703 100644 --- a/beta/src/pages/learn/adding-interactivity.md +++ b/beta/src/pages/learn/adding-interactivity.md @@ -76,7 +76,7 @@ Read **[Responding to Events](/learn/responding-to-events)** to learn how to add Components often need to change what's on the screen as a result of an interaction. Typing into the form should update the input field, clicking "next" on an image carousel should change which image is displayed, clicking "buy" puts a product in the shopping cart. Components need to "remember" things: the current input value, the current image, the shopping cart. In React, this kind of component-specific memory is called state. -You can add state to a component with a [`useState`](/reference/usestate) Hook. Hooks are special functions that let your components use React features (state is one of those features). The `useState` Hook lets you declare a state variable. It takes the initial state and returns a pair of values: the current state, and a state setter function that lets you update it. +You can add state to a component with a [`useState`](/apis/usestate) Hook. Hooks are special functions that let your components use React features (state is one of those features). The `useState` Hook lets you declare a state variable. It takes the initial state and returns a pair of values: the current state, and a state setter function that lets you update it. ```js const [index, setIndex] = useState(0); diff --git a/beta/src/pages/learn/index.md b/beta/src/pages/learn/index.md index 14f86d43..22757bf9 100644 --- a/beta/src/pages/learn/index.md +++ b/beta/src/pages/learn/index.md @@ -302,7 +302,7 @@ Notice how `onClick={handleClick}` has no parentheses at the end! Do not _call_ Often, you'll want your component to "remember" some information and display it. For example, maybe you want to count the number of times a button is clicked. To do this, add *state* to your component. -First, import [`useState`](/reference/usestate) from React: +First, import [`useState`](/apis/usestate) from React: ```js {1,4} import { useState } from 'react'; @@ -383,7 +383,7 @@ Notice how each button "remembers" its own `count` state and doesn't affect othe ## Using Hooks {/*using-hooks*/} -Functions starting with `use` are called Hooks. `useState` is a built-in Hook provided by React. You can find other built-in Hooks in the [React API reference](/reference). You can also write your own Hooks by combining the existing ones. +Functions starting with `use` are called Hooks. `useState` is a built-in Hook provided by React. You can find other built-in Hooks in the [React API reference](/apis). You can also write your own Hooks by combining the existing ones. Hooks are more restrictive than regular functions. You can only call Hooks *at the top level* of your components (or other Hooks). If you want to `useState` in a condition or a loop, extract a new component and put it there. diff --git a/beta/src/pages/learn/keeping-components-pure.md b/beta/src/pages/learn/keeping-components-pure.md index 416a39fc..7095441c 100644 --- a/beta/src/pages/learn/keeping-components-pure.md +++ b/beta/src/pages/learn/keeping-components-pure.md @@ -193,7 +193,7 @@ While functional programming relies heavily on purity, at some point, somewhere, In React, **side effects usually belong inside [event handlers](/learn/responding-to-events).** Event handlers are functions that React runs when you perform some action—for example, when you click a button. Even though event handlers are defined *inside* your component, they don't run *during* rendering! **So event handlers don't need to be pure.** -If you've exhausted all other options and can't find the right event handler for your side effect, you can still attach it to your returned JSX with a [`useEffect`](/reference/useeffect) call in your component. This tells React to execute it later, after rendering, when side effects are allowed. **However, this approach should be your last resort.** +If you've exhausted all other options and can't find the right event handler for your side effect, you can still attach it to your returned JSX with a [`useEffect`](/apis/useeffect) call in your component. This tells React to execute it later, after rendering, when side effects are allowed. **However, this approach should be your last resort.** When possible, try to express your logic with rendering alone. You'll be surprised how far this can take you! diff --git a/beta/src/pages/learn/reacting-to-input-with-state.md b/beta/src/pages/learn/reacting-to-input-with-state.md index ead3ea56..9695454e 100644 --- a/beta/src/pages/learn/reacting-to-input-with-state.md +++ b/beta/src/pages/learn/reacting-to-input-with-state.md @@ -336,7 +336,7 @@ To help visualize this flow, try drawing each state on paper as a labeled circle ### Step 3: Represent the state in memory with `useState` {/*step-3-represent-the-state-in-memory-with-usestate*/} -Next you'll need to represent the visual states of your component in memory with [`useState`](/reference/usestate). Simplicity is key: each piece of state is a "moving piece", and **you want as few "moving pieces" as possible**. More complexity leads to more bugs! +Next you'll need to represent the visual states of your component in memory with [`useState`](/apis/usestate). Simplicity is key: each piece of state is a "moving piece", and **you want as few "moving pieces" as possible**. More complexity leads to more bugs! Start with the state that *absolutely must* be there. For example, you'll need to store the `answer` for the input, and the `error` (if it exists) to store the last error: diff --git a/beta/src/pages/learn/responding-to-events.md b/beta/src/pages/learn/responding-to-events.md index 39c241a5..8baac793 100644 --- a/beta/src/pages/learn/responding-to-events.md +++ b/beta/src/pages/learn/responding-to-events.md @@ -231,7 +231,7 @@ If you use a [design system](https://uxdesign.cc/everything-you-need-to-know-abo ### Naming event handler props {/*naming-event-handler-props*/} -Built-in components like `