docs(en): merge reactjs.org/main into zh-hans.reactjs.org/main @ 20f0fe2

Author: QC-L

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.**
 

beta/package.json

@@ -22,7 +22,7 @@
     "check-all": "npm-run-all prettier lint:fix tsc"
   },
   "dependencies": {
-    "@codesandbox/sandpack-react": "0.13.9-experimental.6",
+    "@codesandbox/sandpack-react": "0.13.11-experimental.0",
     "@docsearch/css": "3.0.0-alpha.41",
     "@docsearch/react": "3.0.0-alpha.41",
     "@headlessui/react": "^1.3.0",
@@ -100,6 +100,6 @@
   },
   "lint-staged": {
     "*.{js,ts,jsx,tsx,css}": "yarn prettier",
-    "*.md": "yarn fix-headings"
+    "src/**/*.md": "yarn fix-headings"
   }
 }

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 =

beta/src/components/Layout/Footer.tsx

@@ -89,11 +89,11 @@ export function Footer() {
               </FooterLink>
             </div>
             <div className="flex flex-col">
-              <FooterLink href="/reference" isHeader={true}>
+              <FooterLink href="/apis" isHeader={true}>
                 API Reference
               </FooterLink>
-              <FooterLink href="/reference">React APIs</FooterLink>
-              <FooterLink href="/reference/reactdom">React DOM APIs</FooterLink>
+              <FooterLink href="/apis">React APIs</FooterLink>
+              <FooterLink href="/apis/reactdom">React DOM APIs</FooterLink>
             </div>
             <div className="flex flex-col sm:col-start-2 xl:col-start-4">
               <FooterLink href="/" isHeader={true}>

beta/src/components/Layout/MarkdownPage.tsx

@@ -34,7 +34,7 @@ export function MarkdownPage<
   }> = React.Children.toArray(children)
     .filter((child: any) => {
       if (child.props?.mdxType) {
-        return ['h1', 'h2', 'h3', 'Challenges', 'Recipes', 'Recap'].includes(
+        return ['h1', 'h2', 'h3', 'Challenges', 'Recap'].includes(
           child.props.mdxType
         );
       }
@@ -48,13 +48,6 @@ export function MarkdownPage<
           text: 'Challenges',
         };
       }
-      if (child.props.mdxType === 'Recipes') {
-        return {
-          url: '#' + (child.props.titleId ?? 'examples'),
-          depth: 0,
-          text: child.props.titleText ?? 'Examples',
-        };
-      }
       if (child.props.mdxType === 'Recap') {
         return {
           url: '#recap',

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
         </TabButton>
         <TabButton
-          isActive={section === 'reference'}
-          onClick={() => setSection('reference')}>
+          isActive={section === 'apis'}
+          onClick={() => setSection('apis')}>
           API
         </TabButton>
       </div>

beta/src/components/Layout/Nav/Nav.tsx

@@ -86,11 +86,11 @@ const lightIcon = (
   </svg>
 );
 
-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() {
         <NavLink href="/learn" isActive={section === 'learn'}>
           Learn
         </NavLink>
-        <NavLink href="/reference" isActive={section === 'reference'}>
+        <NavLink href="/apis" isActive={section === 'apis'}>
           API
         </NavLink>
       </div>

beta/src/components/Layout/useMediaQuery.tsx

@@ -17,14 +17,29 @@ const useMediaQuery = (width: number) => {
 
   useEffect(() => {
     const media = window.matchMedia(`(max-width: ${width}px)`);
-    media.addEventListener('change', updateTarget);
+
+    try {
+      // Chrome & Firefox
+      media.addEventListener('change', updateTarget);
+    } catch {
+      // @deprecated method - Safari <= iOS12
+      media.addListener(updateTarget);
+    }
 
     // Check on mount (callback is not called until a change occurs)
     if (media.matches) {
       setTargetReached(true);
     }
 
-    return () => media.removeEventListener('change', updateTarget);
+    return () => {
+      try {
+        // Chrome & Firefox
+        media.removeEventListener('change', updateTarget);
+      } catch {
+        // @deprecated method - Safari <= iOS12
+        media.removeListener(updateTarget);
+      }
+    };
   }, [updateTarget, width]);
 
   return targetReached;

beta/src/components/MDX/Challenges/Challenges.tsx

@@ -6,6 +6,7 @@ import * as React from 'react';
 import cn from 'classnames';
 import {Button} from 'components/Button';
 import {H2} from 'components/MDX/Heading';
+import {H4} from 'components/MDX/Heading';
 import {Navigation} from './Navigation';
 import {IconHint} from '../../Icon/IconHint';
 import {IconSolution} from '../../Icon/IconSolution';
@@ -111,21 +112,24 @@ export function Challenges({
     return order === currentChallenge.order + 1;
   });
 
+  const Heading = isRecipes ? H4 : H2;
   return (
-    <div className="max-w-7xl mx-auto py-4 md:py-12">
+    <div className="max-w-7xl mx-auto py-4">
       <div
         className={cn(
           'border-gray-10 bg-card dark:bg-card-dark shadow-inner rounded-none -mx-5 sm:mx-auto sm:rounded-lg'
         )}>
         <div ref={scrollAnchorRef} className="py-2 px-5 sm:px-8 pb-0 md:pb-0">
-          <H2
+          <Heading
             id={titleId}
             className={cn(
-              'text-3xl mb-2 leading-10 relative',
-              isRecipes ? 'text-purple-50 dark:text-purple-30' : 'text-link'
+              'mb-2 leading-10 relative',
+              isRecipes
+                ? 'text-xl text-purple-50 dark:text-purple-30'
+                : 'text-3xl text-link'
             )}>
             {titleText}
-          </H2>
+          </Heading>
           {challenges.length > 1 && (
             <Navigation
               currentChallenge={currentChallenge}

beta/src/components/MDX/ExpandableCallout.tsx

@@ -25,7 +25,7 @@ const variantMap = {
       'linear-gradient(rgba(245, 249, 248, 0), rgba(245, 249, 248, 1)',
   },
   gotcha: {
-    title: 'Gotcha',
+    title: 'Pitfall',
     Icon: IconGotcha,
     containerClasses: 'bg-yellow-5 dark:bg-yellow-60 dark:bg-opacity-20',
     textColor: 'text-yellow-50 dark:text-yellow-40',

beta/src/components/MDX/HomepageHero.tsx

@@ -27,7 +27,7 @@ function HomepageHero() {
           </YouWillLearnCard>
         </div>
         <div className="flex flex-col justify-center">
-          <YouWillLearnCard title="API Reference" path="/reference">
+          <YouWillLearnCard title="API Reference" path="/apis">
             <p>
               查阅 React Hooks 的 API
               签名，并通过可视化的代码图解来学习如何使用。

beta/src/components/MDX/Sandpack/index.tsx

@@ -127,9 +127,7 @@ function Sandpack(props: SandpackProps) {
       <SandpackProvider
         template="react"
         customSetup={{...setup, files: files}}
-        autorun={autorun}
-        initMode="user-visible"
-        initModeObserverOptions={{rootMargin: '1400px 0px'}}>
+        autorun={autorun}>
         <CustomPreset
           isSingleFile={isSingleFile}
           showDevTools={showDevTools}

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)