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

 (#1293)

src/components/Icon/IconCanary.tsx

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ */
+
+import {memo} from 'react';
+
+export const IconCanary = memo<JSX.IntrinsicElements['svg'] & {title?: string}>(
+  function IconCanary({className, title}) {
+    return (
+      <svg
+        className={className}
+        width="20px"
+        height="20px"
+        viewBox="0 0 20 20"
+        version="1.1"
+        xmlns="http://www.w3.org/2000/svg">
+        {title && <title>{title}</title>}
+        <g stroke="none" strokeWidth="1" fill="none" fillRule="evenodd">
+          <g
+            id="noun-labs-1201738-(2)"
+            transform="translate(2, 0)"
+            fill="currentColor"
+            fillRule="nonzero">
+            <path
+              d="M10.2865804,5.55665262 L10.2865804,2.22331605 L10.8591544,2.22331605 C11.0103911,2.22244799 11.1551447,2.16342155 11.2617505,2.05914367 C11.3684534,1.95486857 11.4282767,1.81370176 11.4282767,1.66667106 L11.4282767,0.556642208 C11.4282767,0.40907262 11.3678934,0.26747526 11.2605218,0.16308627 C11.1531503,0.0587028348 11.0074938,0 10.8556998,0 L5.14338868,0 C4.9915947,0 4.84594391,0.0587028348 4.73856664,0.16308627 C4.63119507,0.267469704 4.57081178,0.40907262 4.57081178,0.556642208 L4.57081178,1.66667106 C4.57081178,1.81434899 4.63119507,1.95594912 4.73856664,2.06033811 C4.8459382,2.16472155 4.9915947,2.22331605 5.14338868,2.22331605 L5.71596273,2.22331605 L5.71596273,5.55665262 C5.71596273,8.38665538 2.97295619,9.88999017 0.651686904,15.5566623 C-0.0957823782,17.360053 -2.00560068,20 7.99951567,20 C18.004632,20 16.0948137,17.3600252 15.3507732,15.5566623 C13.0124432,9.88999017 10.2865804,8.38665538 10.2865804,5.55665262 Z M9.89570197,10.709991 C10.0921412,10.709991 10.2805515,10.7858383 10.4193876,10.9209301 C10.5583466,11.0559135 10.6363652,11.2390693 10.6363652,11.4300417 C10.6363652,11.6210141 10.5583466,11.8040698 10.4193876,11.9391533 C10.2805401,12.0741367 10.0921412,12.1499813 9.89570197,12.1499813 C9.6992627,12.1499813 9.51096673,12.074134 9.37201631,11.9391533 C9.23316875,11.8040615 9.15515307,11.6210141 9.15515307,11.4300417 C9.15515307,11.2390693 9.2331716,11.0559024 9.37201631,10.9209301 C9.57264221,10.7258996 9.61239426,10.709991 9.89570197,10.709991 Z M8.98919546,9.04212824 C9.09790709,9.14792278 9.15884755,9.29158681 9.1585213,9.44110085 C9.15829001,9.59073155 9.09678989,9.73407335 8.98763252,9.83954568 C8.87847514,9.945018 8.73069852,10.0039347 8.57678157,10.0033977 C8.42286747,10.0027392 8.27565088,9.94273467 8.16727355,9.83639845 C8.05900765,9.73006224 7.99873866,9.58628988 7.99963013,9.43664806 C8.00052304,9.28788403 8.0620221,9.14542556 8.17051087,9.04048101 C8.27911107,8.93555591 8.42599335,8.87663641 8.57913312,8.87663641 C8.73291864,8.87665585 8.88047525,8.93622535 8.98919546,9.04212824 Z M7.99965585,17.9999981 C4.91377349,17.9999981 3.29882839,17.7332867 2.51364277,17.4999976 C2.37780966,17.4476975 2.26954376,17.3439641 2.21396931,17.2125528 C2.15838628,17.0811499 2.16006066,16.9334692 2.21876871,16.8033858 C2.6144474,15.5921346 3.14916224,14.4280501 3.81316983,13.3333824 C5.980145,9.82337899 8.22941036,13.8867718 10.0980836,13.8867718 C11.9666996,13.8867718 11.4695868,12.1534924 12.1827971,13.3333824 C12.8511505,14.4269112 13.3916656,15.5896902 13.794259,16.8000524 C13.8533022,16.9322137 13.8537479,17.0822749 13.7952635,17.2147751 C13.7368889,17.3472613 13.6248314,17.4504531 13.4856467,17.5000531 C12.6833967,17.7332867 11.0855382,17.9999981 7.99965585,17.9999981 Z"
+              id="Shape"></path>
+          </g>
+        </g>
+      </svg>
+    );
+  }
+);

src/components/Layout/Page.tsx

@@ -28,7 +28,7 @@ interface PageProps {
   children: React.ReactNode;
   toc: Array<TocItem>;
   routeTree: RouteItem;
-  meta: {title?: string; description?: string};
+  meta: {title?: string; canary?: boolean; description?: string};
   section: 'learn' | 'reference' | 'community' | 'blog' | 'home' | 'unknown';
 }
 
@@ -40,6 +40,7 @@ export function Page({children, toc, routeTree, meta, section}: PageProps) {
     routeTree
   );
   const title = meta.title || route?.title || '';
+  const canary = meta.canary || false;
   const description = meta.description || route?.description || '';
   const isHomePage = cleanedPath === '/';
   const isBlogIndex = cleanedPath === '/blog';
@@ -56,6 +57,7 @@ export function Page({children, toc, routeTree, meta, section}: PageProps) {
           )}>
           <PageHeading
             title={title}
+            canary={canary}
             description={description}
             tags={route?.tags}
             breadcrumbs={breadcrumbs}

src/components/Layout/Sidebar/SidebarLink.tsx

@@ -8,14 +8,15 @@ import {useRef, useEffect} from 'react';
 import * as React from 'react';
 import cn from 'classnames';
 import {IconNavArrow} from 'components/Icon/IconNavArrow';
+import {IconCanary} from 'components/Icon/IconCanary';
 import Link from 'next/link';
 
 interface SidebarLinkProps {
   href: string;
   selected?: boolean;
   title: string;
   level: number;
-  wip: boolean | undefined;
+  canary?: boolean;
   icon?: React.ReactNode;
   isExpanded?: boolean;
   hideArrow?: boolean;
@@ -26,7 +27,7 @@ export function SidebarLink({
   href,
   selected = false,
   title,
-  wip,
+  canary,
   level,
   isExpanded,
   hideArrow,
@@ -72,12 +73,16 @@ export function SidebarLink({
         }
       )}>
       {/* This here needs to be refactored ofc */}
-      <span
-        className={cn({
-          'text-gray-400 dark:text-gray-500': wip,
-        })}>
-        {title}
-      </span>
+      <div>
+        {title}{' '}
+        {canary && (
+          <IconCanary
+            title="This feature is available in the latest Canary"
+            className="ml-2 text-gray-30 dark:text-gray-60 inline-block w-4 h-4 align-[-3px]"
+          />
+        )}
+      </div>
+
       {isExpanded != null && !hideArrow && (
         <span
           className={cn('pr-1', {

src/components/Layout/Sidebar/SidebarRouteTree.tsx

@@ -82,7 +82,15 @@ export function SidebarRouteTree({
     <ul>
       {currentRoutes.map(
         (
-          {path, title, routes, wip, heading, hasSectionHeader, sectionHeader},
+          {
+            path,
+            title,
+            routes,
+            canary,
+            heading,
+            hasSectionHeader,
+            sectionHeader,
+          },
           index
         ) => {
           const selected = slug === path;
@@ -112,7 +120,7 @@ export function SidebarRouteTree({
                   selected={selected}
                   level={level}
                   title={title}
-                  wip={wip}
+                  canary={canary}
                   isExpanded={isExpanded}
                   hideArrow={isForceExpanded}
                 />
@@ -136,7 +144,7 @@ export function SidebarRouteTree({
                   selected={selected}
                   level={level}
                   title={title}
-                  wip={wip}
+                  canary={canary}
                 />
               </li>
             );

src/components/Layout/getRouteMeta.tsx

@@ -19,6 +19,8 @@ export type RouteTag =
 export interface RouteItem {
   /** Page title (for the sidebar) */
   title: string;
+  /** Optional canary flag for heading */
+  canary?: boolean;
   /** Optional page description for heading */
   description?: string;
   /* Additional meta info for page tagging */
@@ -27,8 +29,6 @@ export interface RouteItem {
   path?: string;
   /** Whether the entry is a heading */
   heading?: boolean;
-  /** Whether the page is under construction */
-  wip?: boolean;
   /** List of sub-routes */
   routes?: RouteItem[];
   /** Adds a section header above the route item */

src/components/MDX/ExpandableCallout.tsx

@@ -8,8 +8,9 @@ import cn from 'classnames';
 import {IconNote} from '../Icon/IconNote';
 import {IconWarning} from '../Icon/IconWarning';
 import {IconPitfall} from '../Icon/IconPitfall';
+import {IconCanary} from '../Icon/IconCanary';
 
-type CalloutVariants = 'deprecated' | 'pitfall' | 'note' | 'wip';
+type CalloutVariants = 'deprecated' | 'pitfall' | 'note' | 'wip' | 'canary';
 
 interface ExpandableCalloutProps {
   children: React.ReactNode;
@@ -34,6 +35,15 @@ const variantMap = {
     overlayGradient:
       'linear-gradient(rgba(245, 249, 248, 0), rgba(245, 249, 248, 1)',
   },
+  canary: {
+    title: 'Canary',
+    Icon: IconCanary,
+    containerClasses:
+      'bg-gray-5 dark:bg-gray-60 dark:bg-opacity-20 text-primary dark:text-primary-dark text-lg',
+    textColor: 'text-gray-60 dark:text-gray-30',
+    overlayGradient:
+      'linear-gradient(rgba(245, 249, 248, 0), rgba(245, 249, 248, 1)',
+  },
   pitfall: {
     title: '陷阱',
     Icon: IconPitfall,

src/components/MDX/MDXComponents.tsx

@@ -87,6 +87,10 @@ const Note = ({children}: {children: React.ReactNode}) => (
   <ExpandableCallout type="note">{children}</ExpandableCallout>
 );
 
+const Canary = ({children}: {children: React.ReactNode}) => (
+  <ExpandableCallout type="canary">{children}</ExpandableCallout>
+);
+
 const Blockquote = ({
   children,
   ...props
@@ -416,6 +420,7 @@ export const MDXComponents = {
   Math,
   MathI,
   Note,
+  Canary,
   PackageImport,
   ReadBlogPost,
   Recap,

src/components/MDX/TerminalBlock.tsx

@@ -70,7 +70,7 @@ function TerminalBlock({level = 'info', children}: TerminalBlockProps) {
           </div>
         </div>
       </div>
-      <div className="px-8 pt-4 pb-6 text-primary-dark dark:text-primary-dark font-mono text-code whitespace-pre">
+      <div className="px-8 pt-4 pb-6 text-primary-dark dark:text-primary-dark font-mono text-code whitespace-pre overflow-x-scroll">
         <LevelText type={level} />
         {message}
       </div>

src/components/PageHeading.tsx

@@ -6,9 +6,12 @@ import Breadcrumbs from 'components/Breadcrumbs';
 import Tag from 'components/Tag';
 import {H1} from './MDX/Heading';
 import type {RouteTag, RouteItem} from './Layout/getRouteMeta';
+import * as React from 'react';
+import {IconCanary} from './Icon/IconCanary';
 
 interface PageHeadingProps {
   title: string;
+  canary?: boolean;
   status?: string;
   description?: string;
   tags?: RouteTag[];
@@ -18,6 +21,7 @@ interface PageHeadingProps {
 function PageHeading({
   title,
   status,
+  canary,
   description,
   tags = [],
   breadcrumbs,
@@ -28,10 +32,16 @@ function PageHeading({
         {breadcrumbs ? <Breadcrumbs breadcrumbs={breadcrumbs} /> : null}
         <H1 className="mt-0 text-primary dark:text-primary-dark -mx-.5 break-words">
           {title}
+          {canary && (
+            <IconCanary
+              title="This feature is available in the latest Canary"
+              className="ml-4 mt-1 text-gray-50 dark:text-gray-40 inline-block w-6 h-6 align-[-1px]"
+            />
+          )}
           {status ? <em>—{status}</em> : ''}
         </H1>
         {description && (
-          <p className="mt-4 mb-6 text-primary dark:text-primary-dark text-xl text-gray-90 leading-large">
+          <p className="mt-4 mb-6 dark:text-primary-dark text-xl text-gray-90 leading-large">
             {description}
           </p>
         )}

src/content/reference/react-dom/components/progress.md

@@ -35,7 +35,7 @@ title: "<progress>"
 除此之外，`<progress>` 还支持以下属性：
 
 - [`max`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/progress#attr-max)：一个数字，表示指定的最大 `value`。默认值为 `1`。
-- [`value`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/progress#attr-value)：一个介于 `0` 至 `max` 之间的数字。如果不确定具体的进度，那么该值可以为 `null`。`value` 表示完成了多少进度。
+- [`value`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/progress#value)：一个介于 `0` 至 `max` 之间的数字。如果不确定具体的进度，那么该值可以为 `null`。`value` 表示完成了多少进度。
 
 ---
 

src/content/reference/react-dom/components/select.md

@@ -50,21 +50,21 @@ title: "<select>"
 
 以下 `<select>` 属性均可用于受控与非受控选择框组件：
 
-* [`autoComplete`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-autocomplete)：字符串，用于指定可能的 [自动完成行为](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/autocomplete#values) 之一。
-* [`autoFocus`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-autofocus)：布尔值。如果为 `true`，React 将在挂载时聚焦该元素。
+* [`autoComplete`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#autocomplete)：字符串，用于指定可能的 [自动完成行为](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/autocomplete#values) 之一。
+* [`autoFocus`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#autofocus)：布尔值。如果为 `true`，React 将在挂载时聚焦该元素。
 * `children`：`<select>` 接受 [`<option>`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/option)、[`<optgroup>`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/optgroup) 与 [`<datalist>`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/optgroup) 组件作为子元素。只要最终渲染的是其中之一，你也可以传递自己的组件。如果最终渲染的是 `<option>`，则每个 `<option>` 都必须具有 `value` 属性。
-* [`disabled`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-disabled)：布尔值。如果为 `true`，选择框将不会交互并展示为暗淡状态（dimmed）。
-* [`form`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-form)：字符串，表示此选择框所属的 `<form>` 的 `id`。如果未指定，则为最近的父表单。
-* [`multiple`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-multiple)：布尔值。如果为 `true`，则浏览器允许 [多选](#enabling-multiple-selection)。
-* [`name`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-name)：字符串，用于指定此选择框的名称，该名称将在 [提交表单时](#reading-the-select-box-value-when-submitting-a-form) 一起提交。
+* [`disabled`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#disabled)：布尔值。如果为 `true`，选择框将不会交互并展示为暗淡状态（dimmed）。
+* [`form`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#form)：字符串，表示此选择框所属的 `<form>` 的 `id`。如果未指定，则为最近的父表单。
+* [`multiple`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#multiple)：布尔值。如果为 `true`，则浏览器允许 [多选](#enabling-multiple-selection)。
+* [`name`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#name)：字符串，用于指定此选择框的名称，该名称将在 [提交表单时](#reading-the-select-box-value-when-submitting-a-form) 一起提交。
 * `onChange`：一个 [`Event` 处理函数](/reference/react-dom/components/common#event-handler)，其对于 [受控选择框](#controlling-a-select-box-with-a-state-variable) 是必需的。当用户选择不同的选项时立即触发。此行为类似于浏览器 [`input` 事件](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLElement/input_event)。
 * `onChangeCapture`：与 `onChange` 类似，但是是在 [捕获阶段](/learn/responding-to-events#capture-phase-events) 触发的。
 * [`onInput`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLElement/input_event)：一个 [`Event` 处理函数](/reference/react-dom/components/common#event-handler)。当用户更改值时立即触发。由于历史原因，在 React 习惯于使用 `onChange`，工作方式类似。
 * `onInputCapture`：与 `onInput` 类似，但是是在 [捕获阶段](/learn/responding-to-events#capture-phase-events) 触发的。
 * [`onInvalid`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLInputElement/invalid_event)：一个 [`Event` 处理函数](/reference/react-dom/components/common#event-handler)。如果输入的内容在表单提交时未通过验证，则会触发此事件。与内置的 `invalid` 事件不同，React 的 `onInvalid` 事件可以进行冒泡。
 * `onInvalidCapture`：与 `onInvalid` 类似，但是是在 [捕获阶段](/learn/responding-to-events#capture-phase-events) 触发的。
-* [`required`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-required)：布尔值。如果为 `true`，则必须提供值才能提交表单。
-* [`size`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#attr-size)：数字。当指定 `multiple={true}` 时可选，表示同时可见的项目数。
+* [`required`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#required)：布尔值。如果为 `true`，则必须提供值才能提交表单。
+* [`size`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/select#size)：数字。当指定 `multiple={true}` 时可选，表示同时可见的项目数。
 
 #### 注意 {/*caveats*/}