chore: add portal context

.changeset/cuddly-ads-behave.md

@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+
+chore: add PortalContext

packages/react/src/Portal/Portal.features.stories.tsx

@@ -1,6 +1,6 @@
-import React from 'react'
+import React, {useEffect} from 'react'
 import type {Meta} from '@storybook/react-vite'
-import {Portal, registerPortalRoot} from './Portal'
+import {Portal, PortalContext, registerPortalRoot} from './Portal'
 import classes from './Portal.stories.module.css'
 import {clsx} from 'clsx'
 
@@ -81,3 +81,70 @@ export const MultiplePortalRoots: React.FC<React.PropsWithChildren<Record<string
     </>
   )
 }
+
+export const WithPortalContext = () => {
+  const customContainerRef = React.useRef<HTMLDivElement>(null)
+  const overrideContainerRef = React.useRef<HTMLDivElement>(null)
+  const [mounted, setMounted] = React.useState(false)
+  useEffect(() => {
+    if (customContainerRef.current instanceof HTMLElement && overrideContainerRef.current instanceof HTMLElement) {
+      registerPortalRoot(customContainerRef.current, 'custom-portal')
+      registerPortalRoot(overrideContainerRef.current, 'override-portal')
+      setMounted(true)
+    }
+  }, [])
+
+  return (
+    <>
+      <div className={clsx(classes.PortalContainer, classes.OuterContainer)}>
+        <h3>Using PortalContext</h3>
+        <p>This story demonstrates how to use PortalContext to control where Portal content is rendered.</p>
+
+        {/* Default Portal */}
+        <div className={clsx(classes.PortalContainer, classes.DefaultSection)}>
+          <strong>Default Portal (no context):</strong>
+          {mounted ? (
+            <Portal>
+              <div className={classes.DefaultPortalContent}>Content in default portal</div>
+            </Portal>
+          ) : null}
+        </div>
+
+        {/* Portal with Context */}
+        <div className={clsx(classes.PortalContainer, classes.ContextSection)}>
+          <strong>Portal with PortalContext:</strong>
+          <PortalContext.Provider value={{portalContainerName: 'custom-portal'}}>
+            {mounted ? (
+              <Portal>
+                <div className={classes.ContextPortalContent}>Content in custom portal (via PortalContext)</div>
+              </Portal>
+            ) : null}
+          </PortalContext.Provider>
+        </div>
+
+        {/* Override context with containerName prop */}
+        <div className={clsx(classes.PortalContainer, classes.OverrideSection)}>
+          <strong>Context + containerName prop override:</strong>
+          <PortalContext.Provider value={{portalContainerName: 'custom-portal'}}>
+            {mounted ? (
+              <Portal containerName="override-portal">
+                <div className={classes.OverridePortalContent}>Content overriding context with containerName prop</div>
+              </Portal>
+            ) : null}
+          </PortalContext.Provider>
+        </div>
+      </div>
+
+      {/* Custom portal containers */}
+      <div className={classes.CustomPortalContainer}>
+        <strong>Custom Portal Container:</strong>
+        <div ref={customContainerRef} />
+      </div>
+
+      <div className={classes.OverridePortalContainer}>
+        <strong>Override Portal Container:</strong>
+        <div ref={overrideContainerRef} />
+      </div>
+    </>
+  )
+}

packages/react/src/Portal/Portal.stories.module.css

@@ -9,3 +9,65 @@
 .InnerContainer {
   background-color: var(--bgColor-success-muted);
 }
+
+/* Portal Context Story Styles */
+.DefaultSection {
+  background-color: var(--bgColor-accent-muted);
+  margin: var(--base-size-8);
+  padding: var(--base-size-8);
+}
+
+.ContextSection {
+  background-color: var(--bgColor-attention-muted);
+  margin: var(--base-size-8);
+  padding: var(--base-size-8);
+}
+
+.OverrideSection {
+  background-color: var(--bgColor-success-muted);
+  margin: var(--base-size-8);
+  padding: var(--base-size-8);
+}
+
+.DefaultPortalContent {
+  background-color: var(--bgColor-accent-emphasis);
+  padding: var(--base-size-4);
+  border: var(--borderWidth-thin) solid var(--borderColor-accent-emphasis);
+  color: var(--fgColor-onEmphasis);
+}
+
+.ContextPortalContent {
+  background-color: var(--bgColor-attention-emphasis);
+  padding: var(--base-size-4);
+  border: var(--borderWidth-thin) solid var(--borderColor-attention-emphasis);
+  color: var(--fgColor-onEmphasis);
+}
+
+.OverridePortalContent {
+  background-color: var(--bgColor-success-emphasis);
+  padding: var(--base-size-4);
+  border: var(--borderWidth-thin) solid var(--borderColor-success-emphasis);
+  color: var(--fgColor-onEmphasis);
+}
+
+.CustomPortalContainer {
+  position: fixed;
+  bottom: var(--base-size-8);
+  left: var(--base-size-8);
+  background-color: var(--bgColor-neutral-muted);
+  padding: var(--base-size-8);
+  border: var(--borderWidth-thick) solid var(--borderColor-attention-emphasis);
+  border-radius: var(--borderRadius-medium);
+  max-width: 200px;
+}
+
+.OverridePortalContainer {
+  position: fixed;
+  bottom: var(--base-size-8);
+  right: var(--base-size-8);
+  background-color: var(--bgColor-neutral-muted);
+  padding: var(--base-size-8);
+  border: var(--borderWidth-thick) solid var(--borderColor-success-emphasis);
+  border-radius: var(--borderRadius-medium);
+  max-width: 200px;
+}

packages/react/src/Portal/Portal.test.tsx

@@ -1,8 +1,9 @@
 import {describe, expect, it} from 'vitest'
-import Portal, {registerPortalRoot} from '../Portal/index'
+import Portal, {registerPortalRoot, PortalContext} from '../Portal/index'
 
 import {render} from '@testing-library/react'
 import BaseStyles from '../BaseStyles'
+import React from 'react'
 
 describe('Portal', () => {
   it('renders a default portal into document.body (no BaseStyles present)', () => {
@@ -100,4 +101,86 @@ describe('Portal', () => {
 
     baseElement.innerHTML = ''
   })
+
+  it('renders into custom portal when PortalContext is supplied with portalContainerName', () => {
+    // Create and register a custom portal root
+    const customPortalRoot = document.createElement('div')
+    customPortalRoot.id = 'customContextPortal'
+    document.body.appendChild(customPortalRoot)
+    registerPortalRoot(customPortalRoot, 'customContext')
+
+    const toRender = (
+      <PortalContext.Provider value={{portalContainerName: 'customContext'}}>
+        <Portal>context-portal-content</Portal>
+      </PortalContext.Provider>
+    )
+
+    render(toRender)
+
+    expect(customPortalRoot.textContent.trim()).toEqual('context-portal-content')
+
+    // Cleanup
+    document.body.removeChild(customPortalRoot)
+  })
+
+  it('renders into default portal when PortalContext does not specify portalContainerName', () => {
+    const toRender = (
+      <PortalContext.Provider value={{}}>
+        <Portal>default-portal-content</Portal>
+      </PortalContext.Provider>
+    )
+
+    const {baseElement} = render(toRender)
+    const generatedRoot = baseElement.querySelector('#__primerPortalRoot__')
+
+    expect(generatedRoot).toBeInstanceOf(HTMLElement)
+    expect(generatedRoot?.textContent.trim()).toEqual('default-portal-content')
+
+    baseElement.innerHTML = ''
+  })
+
+  it('renders into default portal when PortalContext portalContainerName is undefined', () => {
+    const toRender = (
+      <PortalContext.Provider value={{portalContainerName: undefined}}>
+        <Portal>undefined-context-content</Portal>
+      </PortalContext.Provider>
+    )
+
+    const {baseElement} = render(toRender)
+    const generatedRoot = baseElement.querySelector('#__primerPortalRoot__')
+
+    expect(generatedRoot).toBeInstanceOf(HTMLElement)
+    expect(generatedRoot?.textContent.trim()).toEqual('undefined-context-content')
+
+    baseElement.innerHTML = ''
+  })
+
+  it('containerName prop overrides PortalContext portalContainerName', () => {
+    // Create and register custom portal roots
+    const contextPortalRoot = document.createElement('div')
+    contextPortalRoot.id = 'contextPortal'
+    document.body.appendChild(contextPortalRoot)
+    registerPortalRoot(contextPortalRoot, 'contextPortal')
+
+    const propPortalRoot = document.createElement('div')
+    propPortalRoot.id = 'propPortal'
+    document.body.appendChild(propPortalRoot)
+    registerPortalRoot(propPortalRoot, 'propPortal')
+
+    const toRender = (
+      <PortalContext.Provider value={{portalContainerName: 'contextPortal'}}>
+        <Portal containerName="propPortal">prop-overrides-context</Portal>
+      </PortalContext.Provider>
+    )
+
+    render(toRender)
+
+    // Should render in the portal specified by the prop, not the context
+    expect(propPortalRoot.textContent.trim()).toEqual('prop-overrides-context')
+    expect(contextPortalRoot.textContent.trim()).toEqual('')
+
+    // Cleanup
+    document.body.removeChild(contextPortalRoot)
+    document.body.removeChild(propPortalRoot)
+  })
 })

packages/react/src/Portal/Portal.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, {useContext} from 'react'
 import {createPortal} from 'react-dom'
 import useLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 
@@ -43,6 +43,14 @@ function ensureDefaultPortal() {
   }
 }
 
+/**
+ * Provides the ability for component trees to override the portal root container for a sub-set of the experience.
+ * The portal will prioritize the context value unless overridden by their own `containerName` prop, and fallback to the default root if neither are specified
+ */
+export const PortalContext = React.createContext<{
+  portalContainerName?: string
+}>({})
+
 export interface PortalProps {
   /**
    * Called when this portal is added to the DOM
@@ -66,6 +74,7 @@ export const Portal: React.FC<React.PropsWithChildren<PortalProps>> = ({
   onMount,
   containerName: _containerName,
 }) => {
+  const {portalContainerName} = useContext(PortalContext)
   const elementRef = React.useRef<HTMLDivElement | null>(null)
   if (!elementRef.current) {
     const div = document.createElement('div')
@@ -80,7 +89,7 @@ export const Portal: React.FC<React.PropsWithChildren<PortalProps>> = ({
   const element = elementRef.current
 
   useLayoutEffect(() => {
-    let containerName = _containerName
+    let containerName = _containerName ?? portalContainerName
     if (containerName === undefined) {
       containerName = DEFAULT_PORTAL_CONTAINER_NAME
       ensureDefaultPortal()
@@ -89,7 +98,7 @@ export const Portal: React.FC<React.PropsWithChildren<PortalProps>> = ({
 
     if (!parentElement) {
       throw new Error(
-        `Portal container '${_containerName}' is not yet registered. Container must be registered with registerPortal before use.`,
+        `Portal container '${containerName}' is not yet registered. Container must be registered with registerPortalRoot before use.`,
       )
     }
     parentElement.appendChild(element)
@@ -100,7 +109,7 @@ export const Portal: React.FC<React.PropsWithChildren<PortalProps>> = ({
     }
     // eslint-disable-next-line react-compiler/react-compiler
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [element])
+  }, [element, _containerName, portalContainerName])
 
   return createPortal(children, element)
 }

packages/react/src/Portal/index.ts

@@ -1,6 +1,7 @@
 import type {PortalProps} from './Portal'
-import {Portal, registerPortalRoot} from './Portal'
+import {Portal, registerPortalRoot, PortalContext} from './Portal'
 
 export default Portal
 export {registerPortalRoot}
 export type {PortalProps}
+export {PortalContext}

packages/react/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -118,6 +118,7 @@ exports[`@primer/react > should not update exports without a semver change 1`] =
   "type PopoverContentProps",
   "type PopoverProps",
   "Portal",
+  "PortalContext",
   "type PortalProps",
   "ProgressBar",
   "type ProgressBarItemProps",

packages/react/src/index.ts

@@ -126,7 +126,7 @@ export {default as PointerBox} from './PointerBox'
 export type {PointerBoxProps} from './PointerBox'
 export {default as Popover} from './Popover'
 export type {PopoverProps, PopoverContentProps} from './Popover'
-export {default as Portal, registerPortalRoot} from './Portal'
+export {default as Portal, registerPortalRoot, PortalContext} from './Portal'
 export type {PortalProps} from './Portal'
 export {ProgressBar} from './ProgressBar'
 export type {ProgressBarProps, ProgressBarItemProps} from './ProgressBar'