feat: support custom slots

.changeset/lucky-walls-jog.md

@@ -0,0 +1,6 @@
+---
+"@primer/react": minor
+"@primer/styled-react": patch
+---
+
+feat: support custom slots

packages/react/src/ActionList/Group.tsx

@@ -81,7 +81,7 @@ export const Group: React.FC<React.PropsWithChildren<ActionListGroupProps>> = ({
   const {role: listRole} = React.useContext(ListContext)
 
   const [slots, childrenWithoutSlots] = useSlots(props.children, {
-    groupHeading: GroupHeading,
+    groupHeading: {type: GroupHeading, slot: 'ActionList.GroupHeading'},
   })
 
   let groupHeadingId = undefined

packages/react/src/ActionList/Item.tsx

@@ -70,13 +70,16 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
   forwardedRef: React.Ref<any>,
 ): JSX.Element => {
   const baseSlots = {
-    leadingVisual: LeadingVisual,
-    trailingVisual: TrailingVisual,
-    trailingAction: TrailingAction,
-    subItem: SubItem,
+    leadingVisual: {type: LeadingVisual, slot: 'ActionList.LeadingVisual'},
+    trailingVisual: {type: TrailingVisual, slot: 'ActionList.TrailingVisual'},
+    trailingAction: {type: TrailingAction, slot: 'ActionList.TrailingAction'},
+    subItem: {type: SubItem, slot: 'ActionList.SubItem'},
   }
 
-  const [partialSlots, childrenWithoutSlots] = useSlots(props.children, {...baseSlots, description: Description})
+  const [partialSlots, childrenWithoutSlots] = useSlots(props.children, {
+    ...baseSlots,
+    description: {type: Description, slot: 'ActionList.Description'},
+  })
 
   const slots = {description: undefined, ...partialSlots}
 

packages/react/src/ActionList/List.tsx

@@ -25,7 +25,7 @@ const UnwrappedList = <As extends React.ElementType = 'ul'>(
     ...restProps
   } = props
   const [slots, childrenWithoutSlots] = useSlots(restProps.children, {
-    heading: Heading,
+    heading: {type: Heading, slot: 'ActionList.Heading'},
   })
 
   const headingId = useId()

packages/react/src/ActionMenu/ActionMenu.tsx

@@ -15,6 +15,7 @@ import type {ForwardRefComponent as PolymorphicForwardRefComponent} from '../uti
 import {Tooltip} from '../TooltipV2/Tooltip'
 import styles from './ActionMenu.module.css'
 import {useResponsiveValue, type ResponsiveValue} from '../hooks/useResponsiveValue'
+import {getSlotName} from '../utils/get-slot-name'
 
 export type MenuCloseHandler = (
   gesture: 'anchor-click' | 'click-outside' | 'escape' | 'tab' | 'item-select' | 'arrow-left' | 'close',
@@ -112,7 +113,7 @@ const Menu: React.FC<React.PropsWithChildren<ActionMenuProps>> = ({
   // 🚨 Accounting for Tooltip wrapping ActionMenu.Button or being a direct child of ActionMenu.Anchor.
   const contents = React.Children.map(children, child => {
     // Is ActionMenu.Button wrapped with Tooltip? If this is the case, our anchor is the tooltip's trigger (ActionMenu.Button's grandchild)
-    if (child.type === Tooltip) {
+    if (child.type === Tooltip || getSlotName(child) === 'Tooltip') {
       // tooltip trigger
       const anchorChildren = child.props.children
       if (anchorChildren.type === MenuButton) {
@@ -129,7 +130,10 @@ const Menu: React.FC<React.PropsWithChildren<ActionMenuProps>> = ({
       return null
     } else if (child.type === Anchor) {
       const anchorChildren = child.props.children
-      const isWrappedWithTooltip = anchorChildren !== undefined ? anchorChildren.type === Tooltip : false
+      const isWrappedWithTooltip =
+        anchorChildren !== undefined
+          ? anchorChildren.type === Tooltip || getSlotName(anchorChildren) === 'Tooltip'
+          : false
       if (isWrappedWithTooltip) {
         if (anchorChildren.props.children !== null) {
           renderAnchor = anchorProps => {

packages/react/src/CheckboxGroup/CheckboxGroup.tsx

@@ -9,6 +9,7 @@ import {useRenderForcingRef} from '../hooks'
 import FormControl from '../FormControl'
 import Checkbox from '../Checkbox/Checkbox'
 import {CheckboxGroupContext} from './CheckboxGroupContext'
+import {getSlotName} from '../utils/get-slot-name'
 
 export type CheckboxGroupProps = {
   /**
@@ -19,14 +20,16 @@ export type CheckboxGroupProps = {
 
 const CheckboxGroup: FC<React.PropsWithChildren<CheckboxGroupProps>> = ({children, disabled, onChange, ...rest}) => {
   const formControlComponentChildren = React.Children.toArray(children)
-    .filter(child => React.isValidElement(child) && child.type === FormControl)
+    .filter(
+      child => React.isValidElement(child) && (child.type === FormControl || getSlotName(child) === 'FormControl'),
+    )
     .map(formControlComponent =>
       React.isValidElement(formControlComponent) ? formControlComponent.props.children : [],
     )
     .flat()
 
   const checkedCheckboxes = React.Children.toArray(formControlComponentChildren)
-    .filter(child => React.isValidElement(child) && child.type === Checkbox)
+    .filter(child => React.isValidElement(child) && (child.type === Checkbox || getSlotName(child) === 'Checkbox'))
     .map(
       checkbox =>
         React.isValidElement(checkbox) &&

packages/react/src/FormControl/FormControl.tsx

@@ -21,6 +21,7 @@ import {FormControlContextProvider} from './_FormControlContext'
 import {warning} from '../utils/warning'
 import classes from './FormControl.module.css'
 import {BoxWithFallback} from '../internal/components/BoxWithFallback'
+import {getSlotName} from '../utils/get-slot-name'
 
 export type FormControlProps = {
   children?: React.ReactNode
@@ -48,10 +49,10 @@ export type FormControlProps = {
 const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
   ({children, disabled: disabledProp, layout = 'vertical', id: idProp, required, sx, className, style}, ref) => {
     const [slots, childrenWithoutSlots] = useSlots(children, {
-      caption: FormControlCaption,
-      label: FormControlLabel,
-      leadingVisual: FormControlLeadingVisual,
-      validation: FormControlValidation,
+      caption: {type: FormControlCaption, slot: 'FormControl.Caption'},
+      label: {type: FormControlLabel, slot: 'FormControl.Label'},
+      leadingVisual: {type: FormControlLeadingVisual, slot: 'FormControl.LeadingVisual'},
+      validation: {type: FormControlValidation, slot: 'FormControl.Validation'},
     })
     const expectedInputComponents = [
       Autocomplete,
@@ -63,19 +64,36 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
       Textarea,
       SelectPanel,
     ]
+    const expectedInputSlots = [
+      'Autocomplete',
+      'Checkbox',
+      'Radio',
+      'Select',
+      'TextInput',
+      'TextInputWithTokens',
+      'Textarea',
+      'SelectPanel',
+    ]
     const choiceGroupContext = useContext(CheckboxOrRadioGroupContext)
     const disabled = choiceGroupContext.disabled || disabledProp
     const id = useId(idProp)
     const validationMessageId = slots.validation ? `${id}-validationMessage` : undefined
     const captionId = slots.caption ? `${id}-caption` : undefined
     const validationStatus = slots.validation?.props.variant
-    const InputComponent = childrenWithoutSlots.find(child =>
-      expectedInputComponents.some(inputComponent => React.isValidElement(child) && child.type === inputComponent),
+    const InputComponent = childrenWithoutSlots.find(
+      child =>
+        expectedInputComponents.some(inputComponent => React.isValidElement(child) && child.type === inputComponent) ||
+        expectedInputSlots.includes(getSlotName(child)),
     )
     const inputProps = React.isValidElement(InputComponent) && InputComponent.props
     const isChoiceInput =
-      React.isValidElement(InputComponent) && (InputComponent.type === Checkbox || InputComponent.type === Radio)
-    const isRadioInput = React.isValidElement(InputComponent) && InputComponent.type === Radio
+      React.isValidElement(InputComponent) &&
+      (InputComponent.type === Checkbox ||
+        InputComponent.type === Radio ||
+        getSlotName(InputComponent) === 'Checkbox' ||
+        getSlotName(InputComponent) === 'Radio')
+    const isRadioInput =
+      React.isValidElement(InputComponent) && (InputComponent.type === Radio || getSlotName(InputComponent) === 'Radio')
 
     if (InputComponent) {
       warning(
@@ -139,7 +157,9 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
             : null}
           {childrenWithoutSlots.filter(
             child =>
-              React.isValidElement(child) && ![Checkbox, Radio].some(inputComponent => child.type === inputComponent),
+              React.isValidElement(child) &&
+              ![Checkbox, Radio].some(inputComponent => child.type === inputComponent) &&
+              !['Checkbox', 'Radio'].includes(getSlotName(child)),
           )}
         </div>
         {slots.leadingVisual ? (
@@ -204,7 +224,8 @@ const FormControl = React.forwardRef<HTMLDivElement, FormControlProps>(
             {childrenWithoutSlots.filter(
               child =>
                 React.isValidElement(child) &&
-                !expectedInputComponents.some(inputComponent => child.type === inputComponent),
+                !expectedInputComponents.some(inputComponent => child.type === inputComponent) &&
+                !expectedInputSlots.includes(getSlotName(child)),
             )}
             {slots.validation ? (
               <ValidationAnimationContainer show>{slots.validation}</ValidationAnimationContainer>

packages/react/src/FormControl/FormControlLabel.tsx

@@ -54,4 +54,7 @@ const FormControlLabel: React.FC<
   return <InputLabel {...labelProps}>{children}</InputLabel>
 }
 
+// @ts-ignore -- TypeScript doesn't know about the __SLOT__ property
+FormControlLabel.__SLOT__ = Symbol('FormControl.Label')
+
 export default FormControlLabel

packages/react/src/FormControl/__tests__/FormControl.test.tsx

@@ -15,6 +15,43 @@
 const CAPTION_TEXT = 'Hint text'
 const ERROR_TEXT = 'This field is invalid'
 
+const WrappedLabelComponent = () => (
+  <div>
+    {/* eslint-disable-next-line primer-react/direct-slot-children */}
+    <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
+  </div>
+)
+
+WrappedLabelComponent.__SLOT__ = Symbol('FormControl.Label')
+
+const WrappedCaptionComponent = () => (
+  <div>
+    {/* eslint-disable-next-line primer-react/direct-slot-children */}
+    <FormControl.Caption>{CAPTION_TEXT}</FormControl.Caption>
+  </div>
+)
+
+WrappedCaptionComponent.__SLOT__ = Symbol('FormControl.Caption')
+
+const WrappedLeadingVisualComponent = () => (
+  <div>
+    {/* eslint-disable-next-line primer-react/direct-slot-children */}
+    <FormControl.LeadingVisual>
+      <MarkGithubIcon aria-label="Icon label" />
+    </FormControl.LeadingVisual>
+  </div>
+)
+
+WrappedLeadingVisualComponent.__SLOT__ = Symbol('FormControl.LeadingVisual')
+
+const WrappedValidationComponent = () => (
+  <div>
+    <FormControl.Validation variant="error">{ERROR_TEXT}</FormControl.Validation>
+  </div>
+)
+
+WrappedValidationComponent.__SLOT__ = Symbol('FormControl.Validation')
+
 describe('FormControl', () => {
   describe('vertically stacked layout (default)', () => {
     describe('rendering', () => {
@@ -326,6 +363,107 @@
         spy.mockRestore()
       })
     })
+
+    describe('slot identification', () => {
+      it('should correctly identify a label wrapped in a div using __SLOT__ property', () => {
+        const spy = vi.spyOn(console, 'error').mockImplementationOnce(() => {})
+
+        const {container, getByLabelText} = render(
+          <FormControl>
+            <WrappedLabelComponent />
+            <TextInput />
+          </FormControl>,
+        )
+
+        // The label should be found as a slot because of the __SLOT__ property
+        // This should NOT trigger the error about missing FormControl.Label
+        expect(spy).toHaveBeenCalledTimes(0)
+
+        // The label should function properly - input should be labeled correctly
+        const input = getByLabelText(LABEL_TEXT)
+        expect(input).toBeDefined()
+        expect(container.textContent).toContain(LABEL_TEXT)
+
+        spy.mockRestore()
+      })
+
+      it('should correctly identify a caption wrapped in a div using __SLOT__ property', () => {
+        const {container} = render(
+          <FormControl id="test-caption">
+            <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
+            <TextInput />
+            <WrappedCaptionComponent />
+          </FormControl>,
+        )
+
+        // The caption should be found as a slot because of the __SLOT__ property
+        // We can verify this by checking that aria-describedby includes the caption ID
+        const input = container.querySelector('input')
+        const ariaDescribedBy = input?.getAttribute('aria-describedby') || ''
+        expect(ariaDescribedBy).toContain('test-caption-caption')
+
+        // The caption text should be rendered and functional
+        expect(container.textContent).toContain(CAPTION_TEXT)
+      })
+
+      it('should correctly identify a validation wrapped in a div using __SLOT__ property', () => {
+        const {container} = render(
+          <FormControl id="test-validation">
+            <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
+            <TextInput />
+            <WrappedValidationComponent />
+          </FormControl>,
+        )
+
+        // The validation should be found as a slot because of the __SLOT__ property
+        // We can verify this by checking that aria-describedby includes the validation ID
+        const input = container.querySelector('input')
+        const ariaDescribedBy = input?.getAttribute('aria-describedby') || ''
+        expect(ariaDescribedBy).toContain('test-validation-validationMessage')
+
+        // The validation text should be rendered and functional
+        expect(container.textContent).toContain(ERROR_TEXT)
+      })
+
+      it('should correctly identify a leading visual wrapped in a div using __SLOT__ property for non-choice inputs', () => {
+        const spy = vi.spyOn(console, 'warn').mockImplementationOnce(() => {})
+
+        const {container} = render(
+          <FormControl>
+            <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
+            <TextInput />
+            <WrappedLeadingVisualComponent />
+          </FormControl>,
+        )
+
+        // The leading visual should be found as a slot because of the __SLOT__ property
+        // This should trigger a warning since leading visuals are only for choice inputs
+        expect(spy).toHaveBeenCalledTimes(1)
+
+        // The icon should be rendered in the DOM
+        expect(container.querySelector('svg')).toBeDefined()
+
+        spy.mockRestore()
+      })
+      it('should correctly identify a leading visual wrapped in a div using __SLOT__ property for choice inputs', () => {
+        const {container, getByLabelText} = render(
+          <FormControl>
+            <FormControl.Label>{LABEL_TEXT}</FormControl.Label>
+            <Checkbox />
+            <WrappedLeadingVisualComponent />
+          </FormControl>,
+        )
+
+        // The leading visual should be found as a slot because of the __SLOT__ property
+        // We can verify this by checking that the leading visual container is present
+        const leadingVisualContainer = container.querySelector('[data-has-leading-visual]')
+        expect(leadingVisualContainer).toBeDefined()
+
+        // The icon should be rendered and functional
+        expect(getByLabelText('Icon label')).toBeDefined()
+        expect(container.querySelector('svg')).toBeDefined()
+      })
+    })
   })
 
   describe('checkbox and radio layout', () => {

packages/react/src/NavList/NavList.tsx

@@ -17,6 +17,7 @@ import useIsomorphicLayoutEffect from '../utils/useIsomorphicLayoutEffect'
 import classes from '../ActionList/ActionList.module.css'
 import navListClasses from './NavList.module.css'
 import {flushSync} from 'react-dom'
+import {getSlotName} from '../utils/get-slot-name'
 
 // ----------------------------------------------------------------------------
 // NavList
@@ -57,7 +58,9 @@ const Item = React.forwardRef<HTMLAnchorElement, NavListItemProps>(
     const {depth} = React.useContext(SubNavContext)
 
     // Get SubNav from children
-    const subNav = React.Children.toArray(children).find(child => isValidElement(child) && child.type === SubNav)
+    const subNav = React.Children.toArray(children).find(
+      child => isValidElement(child) && (child.type === SubNav || getSlotName(child) === 'SubNav'),
+    )
 
     // Get children without SubNav or TrailingAction
     const childrenWithoutSubNavOrTrailingAction = React.Children.toArray(children).filter(child =>

packages/react/src/PageLayout/PageLayout.tsx

@@ -50,7 +50,7 @@ export type PageLayoutProps = {
   columnGap?: keyof typeof SPACING_MAP
 
   /** Private prop to allow SplitPageLayout to customize slot components */
-  _slotsConfig?: Record<'header' | 'footer', React.ElementType>
+  _slotsConfig?: Record<'header' | 'footer', {type: React.ElementType}>
   className?: string
   style?: React.CSSProperties
 }
@@ -76,7 +76,13 @@ const Root: React.FC<React.PropsWithChildren<PageLayoutProps>> = ({
 }) => {
   const paneRef = useRef<HTMLDivElement>(null)
 
-  const [slots, rest] = useSlots(children, slotsConfig ?? {header: Header, footer: Footer})
+  const [slots, rest] = useSlots(
+    children,
+    slotsConfig ?? {
+      header: {type: Header, slot: 'PageLayout.Header'},
+      footer: {type: Footer, slot: 'PageLayout.Footer'},
+    },
+  )
 
   const memoizedContextValue = React.useMemo(() => {
     return {