add rough docs

Author: LFDanLu

packages/@react-aria/overlays/docs/PortalProvider.mdx

@@ -0,0 +1,120 @@
+{/* Copyright 2025 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License. */}
+
+import {Layout} from '@react-spectrum/docs';
+export default Layout;
+
+import docs from 'docs:@react-aria/overlays';
+import {HeaderInfo, PropTable, FunctionAPI, PageDescription} from '@react-spectrum/docs';
+import packageData from '@react-aria/overlays/package.json';
+
+---
+category: Utilities
+keywords: [overlays, portals]
+---
+
+# PortalProvider
+
+<PageDescription>{docs.exports.UNSTABLE_PortalProvider.description}</PageDescription>
+
+<HeaderInfo
+  packageData={packageData}
+  componentNames={['UNSTABLE_PortalProvider', 'useUNSTABLE_PortalContext']} />
+
+## Introduction
+
+`UNSTABLE_PortalProvider` is a utility wrapper component that can be used to set where components like
+Modals, Popovers, Toasts, and Tooltips will portal their overlay element to. This is typically used when
+your app is already portalling other elements to a location other than the `document.body` and thus requires
+your React Aria components to send their overlays to the same container.
+
+## Props
+
+<PropTable links={docs.links} component={docs.exports.UNSTABLE_PortalProvider} />
+
+## Example
+
+The example below shows how you can use `UNSTABLE_PortalProvider` to portal your Toasts to an arbitrary container. Note that
+the Toast in this example is taken directly from the [React Aria Components Toast documentation](Toast.html#example), please visit that page for
+a detailed explanation of its implementation.
+
+```tsx example
+import {UNSTABLE_PortalProvider} from '@react-aria/overlays';
+///- begin collapse -///
+import {UNSTABLE_ToastRegion as ToastRegion, UNSTABLE_Toast as Toast, UNSTABLE_ToastQueue as ToastQueue, UNSTABLE_ToastContent as ToastContent, Button, Text} from 'react-aria-components';
+
+
+// Define the type for your toast content.
+interface MyToastContent {
+  title: string,
+  description?: string
+}
+
+// Create a global ToastQueue.
+const queue = new ToastQueue<MyToastContent>();
+
+function MyToastRegion() {
+  return (
+    <ToastRegion queue={queue}>
+      {({toast}) => (
+        <Toast toast={toast}>
+          <ToastContent>
+            <Text slot="title">{toast.content.title}</Text>
+            <Text slot="description">{toast.content.description}</Text>
+          </ToastContent>
+          <Button slot="close">x</Button>
+        </Toast>
+      )}
+    </ToastRegion>
+
+  );
+}
+///- end collapse -///
+
+// See the above Toast docs link for the ToastRegion implementation
+function App() {
+  let container = React.useRef(null);
+  return (
+    <>
+      <UNSTABLE_PortalProvider getContainer={() => container.current}>
+        <MyToastRegion />
+        <Button
+          onPress={() => queue.add({
+            title: 'Toast complete!',
+            description: 'Great success.'
+          })}>
+          Toast
+        </Button>
+      </UNSTABLE_PortalProvider>
+      <div ref={container} style={{height: '70px', width: '200px',  overflow: 'auto'}}>
+        Toasts are portalled here!
+      </div>
+    </>
+  );
+}
+
+<App />
+```
+
+## Contexts
+
+The `getContainer` set by the nearest PortalProvider can be accessed by calling `useUNSTABLE_PortalContext`. This can be
+used by custom overlay components to ensure that they are also being consistently portalled throughout your app.
+
+<FunctionAPI links={docs.links} function={docs.exports.useUNSTABLE_PortalContext} />
+
+```tsx
+import {useUNSTABLE_PortalContext} from '@react-aria/overlays';
+
+function MyOverlay(props) {
+  let {children} = props;
+  let {getContainer} = useUNSTABLE_PortalContext();
+  return ReactDOM.createPortal(children, getContainer());
+}
+```

packages/@react-aria/overlays/src/PortalProvider.tsx

@@ -13,13 +13,20 @@
 import React, {createContext, ReactNode, useContext} from 'react';
 
 export interface PortalProviderProps {
-  /* Should return the element where we should portal to. Can clear the context by passing null. */
-  getContainer?: () => HTMLElement | null
+  /** Should return the element where we should portal to. Can clear the context by passing null. */
+  getContainer?: () => HTMLElement | null,
+  /** The content of the PortalProvider. Should contain all children that want to portal their overlays to the element returned by the provided getContainer(). */
+  children: ReactNode
 }
 
-export const PortalContext = createContext<PortalProviderProps>({});
+export interface PortalProviderContextValue extends Omit<PortalProviderProps, 'children'>{};
 
-export function UNSTABLE_PortalProvider(props: PortalProviderProps & {children: ReactNode}): ReactNode {
+export const PortalContext = createContext<PortalProviderContextValue>({});
+
+/**
+ * Sets the portal container for all overlay elements rendered by its children.
+ */
+export function UNSTABLE_PortalProvider(props: PortalProviderProps): ReactNode {
   let {getContainer} = props;
   let {getContainer: ctxGetContainer} = useUNSTABLE_PortalContext();
   return (
@@ -29,6 +36,6 @@ export function UNSTABLE_PortalProvider(props: PortalProviderProps & {children:
   );
 }
 
-export function useUNSTABLE_PortalContext(): PortalProviderProps {
+export function useUNSTABLE_PortalContext(): PortalProviderContextValue {
   return useContext(PortalContext) ?? {};
 }

packages/@react-aria/overlays/src/index.ts

@@ -30,3 +30,4 @@ export type {AriaPopoverProps, PopoverAria} from './usePopover';
 export type {AriaModalOverlayProps, ModalOverlayAria} from './useModalOverlay';
 export type {OverlayProps} from './Overlay';
 export type {Placement, PlacementAxis, PositionProps} from '@react-types/overlays';
+export type {PortalProviderProps, PortalProviderContextValue} from './PortalProvider';