Merge branch 'master' into fix-x-links

docs/data/material/components/click-away-listener/click-away-listener.md

@@ -9,11 +9,60 @@ githubLabel: 'component: ClickAwayListener'
 
 <p class="description">The Click-Away Listener component detects when a click event happens outside of its child element.</p>
 
-## This document has moved
+{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
 
-:::warning
-Please refer to the [Click-Away Listener](/base-ui/react-click-away-listener/) component page in the MUI Base docs for demos and details on usage.
+## Introduction
+
+Click-Away Listener is a utility component that listens for click events outside of its child.
+(Note that it only accepts _one_ child element.)
+This is useful for components like the [Popper](/material-ui/react-popper/) which should close when the user clicks anywhere else in the document.
+Click-Away Listener also supports the [Portal](/material-ui/react-portal/) component.
+
+The demo below shows how to hide a menu dropdown when users click anywhere else on the page:
+
+{{"demo": "ClickAway.js"}}
+
+## Basics
+
+### Import
+
+```jsx
+import ClickAwayListener from '@mui/material/ClickAwayListener';
+```
+
+## Customization
+
+### Use with Portal
+
+The following demo uses the [Portal](/material-ui/react-portal/) component to render the dropdown into a new subtree outside of the current DOM hierarchy:
+
+{{"demo": "PortalClickAway.js"}}
 
-Click-Away Listener is a part of the standalone MUI Base component library.
-It is currently re-exported from `@mui/material` for your convenience, but it will be removed from this package in a future major version after MUI Base gets a stable release.
+### Listening for leading events
+
+By default, the Click-Away Listener component responds to **trailing events**—the _end_ of a click or touch.
+
+You can set the component to listen for **leading events** (the start of a click or touch) using the `mouseEvent` and `touchEvent` props, as shown in the following demo:
+
+:::warning
+When the component is set to listen for leading events, interactions with the scrollbar are ignored.
 :::
+
+{{"demo": "LeadingClickAway.js"}}
+
+## Accessibility
+
+By default, Click-Away Listener adds an `onClick` handler to its child.
+This can result in screen readers announcing that the child is clickable, even though this `onClick` handler has no effect on the child itself.
+
+To prevent this behavior, add `role="presentation"` to the child element:
+
+```tsx
+<ClickAwayListener>
+  <div role="presentation">
+    <h1>non-interactive heading</h1>
+  </div>
+</ClickAwayListener>
+```
+
+This is also required to fix a known issue in NVDA when using Firefox that prevents the announcement of alert messages—see [this GitHub issue](https://github.com/mui/material-ui/issues/29080) for details.

docs/data/material/components/material-icons/synonyms.js

@@ -141,6 +141,8 @@ const synonyms = {
     'all applications circles collection components dots grid interface squares ui ux',
   Architecture: 'art compass design drawing engineering geometric tool',
   Archive: 'inbox mail store',
+  AreaChart:
+    'analytics data diagram infographic measure metrics statistics tracking',
   ArrowBack:
     'DISABLE_IOS application components direction disable_ios interface left navigation previous screen ui ux website',
   ArrowBackIos:
@@ -749,8 +751,8 @@ const synonyms = {
     'approve checkmark complete finished layers multiple ok select stack success tick validate verified yes',
   DoneOutline:
     'all approve checkmark complete finished ok select success tick validate verified yes',
-  DoNotDisturb: 'cancel close denied deny remove silence slash stop',
-  DoNotDisturbAlt: 'cancel close denied deny remove silence slash stop',
+  DoNotDisturb: 'cancel close denied deny neutral remove silence slash stop',
+  DoNotDisturbAlt: 'cancel close denied deny neutral remove silence slash stop',
   DoNotDisturbOff:
     'cancel close dash denied deny disabled enabled on remove silence slash stop',
   DoNotDisturbOn:
@@ -1161,7 +1163,7 @@ const synonyms = {
   GasMeter: 'droplet energy measure nest usage water',
   Gavel:
     'agreement contract court document government hammer judge law mallet official police rules terms',
-  Gesture: 'doodle drawing finger gestures hand line motion string thread',
+  Gesture: 'doodle drawing finger gestures hand line motion scribble string thread',
   GetApp: 'arrows downloads export install play pointing retrieve upload',
   Gif: 'alphabet animated animation bitmap character font format graphics interchange letters symbol text type',
   GifBox:
@@ -1334,7 +1336,7 @@ const synonyms = {
     'Android cell computer desktop hardware iOS mobile monitor phone star tablet web',
   ImportContacts: 'address book friends information magazine open',
   ImportExport: 'arrows direction down explort up',
-  Inbox: 'archive email incoming message',
+  Inbox: 'archive category email incoming message',
   IndeterminateCheckBox:
     'application button components control design form interface minus screen selected selection square toggle ui undetermined ux website',
   Info: 'about alert announcement announcment assistance bubble circle details help information service support',
@@ -1411,7 +1413,7 @@ const synonyms = {
     'athlete athletic beach body entertainment exercise hobby human people person social sports travel water',
   Label: 'badge favorite indent item library mail remember save stamp sticker tag',
   LabelImportant:
-    'badge favorite important. indent item library mail remember save stamp sticker tag wing',
+    'badge chevron favorite flag important. indent item library mail remember right save stamp sticker tag wing',
   LabelOff:
     'disabled enabled favorite indent library mail on remember save slash stamp sticker tag wing',
   Lan: 'computer connection data internet network service',
@@ -3015,10 +3017,10 @@ const synonyms = {
     'arrow backwards find glass history inprogress loading look magnifying refresh renew restore reverse rotate see yt',
   ZoomIn:
     'bigger find glass grow look magnifier magnifying plus scale search see size',
-  ZoomInMap: 'arrows destination location maps move place stop',
+  ZoomInMap: 'arrows center destination location maps middle move place stop',
   ZoomOut:
     'find glass look magnifier magnifying minus negative scale search see size smaller',
-  ZoomOutMap: 'arrows destination location maps move place stop',
+  ZoomOutMap: 'arrows center destination location maps middle move place stop',
 };
 
 export default synonyms;

docs/data/material/components/no-ssr/no-ssr.md

@@ -8,11 +8,41 @@ components: NoSsr
 
 <p class="description">The No-SSR component defers the rendering of children components from the server to the client.</p>
 
-## This document has moved
+{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
 
-:::warning
-Please refer to the [No-SSR](/base-ui/react-no-ssr/) component page in the MUI Base docs for demos and details on usage.
+## Introduction
+
+No-SSR is a utility component that prevents its children from being rendered on the server, deferring their rendering to the client instead.
+This can be useful in a variety of situations, including:
+
+- To create an escape hatch for broken dependencies that don't support server-side rendering (SSR)
+- To improve the time to first paint by only rendering above the fold
+- To reduce the rendering time on the server
+- To turn on service degradation when the server load is too heavy
+- To improve the Time to Interactive (TTI) by only rendering what's important (using the `defer` prop)
+
+The demo below illustrates how this component works:
+
+{{"demo": "SimpleNoSsr.js"}}
+
+## Basics
+
+### Import
 
-No-SSR is a part of the standalone MUI Base component library.
-It is currently re-exported from `@mui/material` for your convenience, but it will be removed from this package in a future major version after MUI Base gets a stable release.
+```jsx
+import NoSsr from '@mui/material/NoSsr';
+```
+
+## Customization
+
+### Delay client-side rendering
+
+You can also use No-SSR to delay the rendering of specific components on the client-side—for example, to let the rest of the application load before an especially complex or data-heavy component.
+
+The following demo shows how to use the `defer` prop to prioritize rendering the rest of the app outside of what is nested within No-SSR:
+
+{{"demo": "FrameDeferring.js"}}
+
+:::warning
+When using No-SSR in this way, React applies [two commits](https://react.dev/learn/render-and-commit) instead of one.
 :::

docs/data/material/components/portal/SimplePortal.js

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import Portal from '@mui/material/Portal';
+import { Box } from '@mui/system';
+
+export default function SimplePortal() {
+  const [show, setShow] = React.useState(false);
+  const container = React.useRef(null);
+
+  const handleClick = () => {
+    setShow(!show);
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleClick}>
+        {show ? 'Unmount children' : 'Mount children'}
+      </button>
+      <Box sx={{ p: 1, my: 1, border: '1px solid' }}>
+        It looks like I will render here.
+        {show ? (
+          <Portal container={() => container.current}>
+            <span>But I actually render here!</span>
+          </Portal>
+        ) : null}
+      </Box>
+      <Box sx={{ p: 1, my: 1, border: '1px solid' }} ref={container} />
+    </div>
+  );
+}

docs/data/material/components/portal/SimplePortal.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import Portal from '@mui/material/Portal';
+import { Box } from '@mui/system';
+
+export default function SimplePortal() {
+  const [show, setShow] = React.useState(false);
+  const container = React.useRef(null);
+
+  const handleClick = () => {
+    setShow(!show);
+  };
+
+  return (
+    <div>
+      <button type="button" onClick={handleClick}>
+        {show ? 'Unmount children' : 'Mount children'}
+      </button>
+      <Box sx={{ p: 1, my: 1, border: '1px solid' }}>
+        It looks like I will render here.
+        {show ? (
+          <Portal container={() => container.current!}>
+            <span>But I actually render here!</span>
+          </Portal>
+        ) : null}
+      </Box>
+      <Box sx={{ p: 1, my: 1, border: '1px solid' }} ref={container} />
+    </div>
+  );
+}

docs/data/material/components/portal/SimplePortal.tsx.preview

@@ -0,0 +1,12 @@
+<button type="button" onClick={handleClick}>
+  {show ? 'Unmount children' : 'Mount children'}
+</button>
+<Box sx={{ p: 1, my: 1, border: '1px solid' }}>
+  It looks like I will render here.
+  {show ? (
+    <Portal container={() => container.current!}>
+      <span>But I actually render here!</span>
+    </Portal>
+  ) : null}
+</Box>
+<Box sx={{ p: 1, my: 1, border: '1px solid' }} ref={container} />

docs/data/material/components/portal/portal.md

@@ -9,11 +9,49 @@ githubLabel: 'component: Portal'
 
 <p class="description">The Portal component lets you render its children into a DOM node that exists outside of the Portal's own DOM hierarchy.</p>
 
-## This document has moved
+{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
 
-:::warning
-Please refer to the [Portal](/base-ui/react-portal/) component page in the MUI Base docs for demos and details on usage.
+## Introduction
 
-Portal is a part of the standalone MUI Base component library.
-It is currently re-exported from `@mui/material` for your convenience, but it will be removed from this package in a future major version after MUI Base gets a stable release.
+Portal is a utility component built around [React's `createPortal()` API](https://react.dev/reference/react-dom/createPortal).
+It gives you the functionality of `createPortal()` in a convenient component form.
+It's used internally by the [Modal](/base-ui/react-modal/) and [Popper](/base-ui/react-popper/) components.
+
+:::info
+According to [the React docs](https://react.dev/reference/react-dom/createPortal), portals are useful when "you need the child element to visually 'break out' of its container"—for instance, modals and tooltips, which need to exist outside of the normal flow of the document.
+:::
+
+Normally, children of a component are rendered within that component's DOM tree.
+But sometimes it's necessary to mount a child at a different location in the DOM.
+The Portal component accepts a `container` prop that passes a `ref` to the DOM node where its children will be mounted.
+
+The following demo shows how a `<span>` nested within a Portal can be appended to a node outside of the Portal's DOM hierarchy—click **Mount children** to see how it behaves:
+
+{{"demo": "SimplePortal.js"}}
+
+## Basics
+
+### Import
+
+```jsx
+import Portal from '@mui/material/Portal';
+```
+
+## Customization
+
+### Server-side Portals
+
+The DOM API isn't available on the server, so you need to use the `container` prop callback.
+This callback is called during a React layout effect:
+
+```jsx
+<Portal container={() => document.getElementById('filter-panel')!}>
+  <Child />
+</Portal>
+```
+
+:::error
+The Portal component cannot be used to render child elements on the server—client-side hydration is necessary.
+This is because React doesn't support the [`createPortal()` API](https://react.dev/reference/react-dom/createPortal) on the server.
+See [this GitHub issue](https://github.com/facebook/react/issues/13097) for details.
 :::

docs/data/material/components/textarea-autosize/textarea-autosize.md

@@ -7,13 +7,35 @@ githubLabel: 'component: TextareaAutosize'
 
 # Textarea Autosize
 
-<p class="description">The Textarea Autosize component gives you a textarea HTML element that automatically adjusts its height to match the length of the content within.</p>
+<p class="description">The Textarea Autosize component automatically adjusts its height to match the length of the content within.</p>
 
-## This document has moved
+{{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
 
-:::warning
-Please refer to the [Textarea Autosize](/base-ui/react-textarea-autosize/) component page in the MUI Base docs for demos and details on usage.
+## Introduction
 
-Textarea Autosize is a part of the standalone MUI Base component library.
-It is currently re-exported from `@mui/material` for your convenience, but it will be removed from this package in a future major version after MUI Base gets a stable release.
-:::
+Textarea Autosize is a utility component that replaces the native `<textarea>` HTML.
+Its height automatically adjusts as a response to keyboard inputs and window resizing events.
+
+By default, an empty Textarea Autosize component renders as a single row, as shown in the following demo:
+
+{{"demo": "EmptyTextarea.js", "defaultCodeOpen": false}}
+
+## Basics
+
+### Import
+
+```jsx
+import TextareaAutosize from '@mui/material/TextareaAutosize';
+```
+
+### Minimum height
+
+Use the `minRows` prop to define the minimum height of the component:
+
+{{"demo": "MinHeightTextarea.js"}}
+
+### Maximum height
+
+Use the `maxRows` prop to define the maximum height of the component:
+
+{{"demo": "MaxHeightTextarea.js"}}