[docs] Restore utility component docs from MUI Base to Material UI (#…

…45213)

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/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"}}

docs/data/material/pages.ts

@@ -120,18 +120,16 @@ const pages: MuiPage[] = [
           {
             pathname: '/material-ui/react-click-away-listener',
             title: 'Click-Away Listener',
-            deprecated: true,
           },
           { pathname: '/material-ui/react-css-baseline', title: 'CSS Baseline' },
           { pathname: '/material-ui/react-modal' },
-          { pathname: '/material-ui/react-no-ssr', title: 'No SSR', deprecated: true },
+          { pathname: '/material-ui/react-no-ssr', title: 'No SSR' },
           { pathname: '/material-ui/react-popover' },
           { pathname: '/material-ui/react-popper' },
-          { pathname: '/material-ui/react-portal', deprecated: true },
+          { pathname: '/material-ui/react-portal' },
           {
             pathname: '/material-ui/react-textarea-autosize',
             title: 'Textarea Autosize',
-            deprecated: true,
           },
           { pathname: '/material-ui/transitions' },
           { pathname: '/material-ui/react-use-media-query', title: 'useMediaQuery' },
@@ -142,7 +140,7 @@ const pages: MuiPage[] = [
         subheader: 'MUI X',
         children: [
           { pathname: '/x/react-data-grid', title: 'Data Grid' },
-          { pathname: '/x/react-date-pickers', title: 'Date & Time Pickers' },
+          { pathname: '/x/react-date-pickers', title: 'Date and Time Pickers' },
           { pathname: '/x/react-charts' },
           { pathname: '/x/react-tree-view', title: 'Tree View' },
         ],