feat: support custom slots (#6976)

Co-authored-by: Adam Dierkens <adierkens@users.noreply.github.com>

Author: francinelucca

.changeset/lucky-walls-jog.md

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

packages/react/src/ActionList/Description.tsx

@@ -3,6 +3,7 @@ import Truncate from '../Truncate'
 import {ItemContext} from './shared'
 import classes from './ActionList.module.css'
 import {clsx} from 'clsx'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
 
 export type ActionListDescriptionProps = {
   /**
@@ -21,7 +22,7 @@ export type ActionListDescriptionProps = {
   truncate?: boolean
 }
 
-export const Description: React.FC<React.PropsWithChildren<ActionListDescriptionProps>> = ({
+export const Description: FCWithSlotMarker<React.PropsWithChildren<ActionListDescriptionProps>> = ({
   variant = 'inline',
   className,
   truncate,
@@ -70,3 +71,5 @@ export const Description: React.FC<React.PropsWithChildren<ActionListDescription
     )
   }
 }
+
+Description.__SLOT__ = Symbol('ActionList.Description')

packages/react/src/ActionList/Divider.tsx

@@ -1,6 +1,7 @@
 import type React from 'react'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
 
 export type ActionListDividerProps = {
   className?: string
@@ -10,7 +11,7 @@ export type ActionListDividerProps = {
 /**
  * Visually separates `Items` or `Groups` in an `ActionList`.
  */
-export const Divider: React.FC<React.PropsWithChildren<ActionListDividerProps>> = ({className, style}) => {
+export const Divider: FCWithSlotMarker<React.PropsWithChildren<ActionListDividerProps>> = ({className, style}) => {
   return (
     <li
       className={clsx(className, classes.Divider)}
@@ -20,3 +21,5 @@ export const Divider: React.FC<React.PropsWithChildren<ActionListDividerProps>>
     />
   )
 }
+
+Divider.__SLOT__ = Symbol('ActionList.Divider')

packages/react/src/ActionList/Group.tsx

@@ -7,6 +7,7 @@ import {invariant} from '../utils/invariant'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
 import groupClasses from './Group.module.css'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
 
 type HeadingProps = {
   as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
@@ -67,7 +68,7 @@ export const GroupContext = React.createContext<ContextProps>({
   selectionVariant: undefined,
 })
 
-export const Group: React.FC<React.PropsWithChildren<ActionListGroupProps>> = ({
+export const Group: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupProps>> = ({
   title,
   variant = 'subtle',
   auxiliaryText,
@@ -138,7 +139,7 @@ export type ActionListGroupHeadingProps = Pick<ActionListGroupProps, 'variant' |
  * hidden from the accessibility tree due to the limitation of listbox children. https://w3c.github.io/aria/#listbox
  * groups under menu or listbox are labelled by `aria-label`
  */
-export const GroupHeading: React.FC<React.PropsWithChildren<ActionListGroupHeadingProps>> = ({
+export const GroupHeading: FCWithSlotMarker<React.PropsWithChildren<ActionListGroupHeadingProps>> = ({
   as,
   variant = 'subtle',
   // We are not recommending this prop to be used, it should only be used internally for incremental rollout.
@@ -210,3 +211,6 @@ export const GroupHeading: React.FC<React.PropsWithChildren<ActionListGroupHeadi
 
 GroupHeading.displayName = 'ActionList.GroupHeading'
 Group.displayName = 'ActionList.Group'
+
+Group.__SLOT__ = Symbol('ActionList.Group')
+GroupHeading.__SLOT__ = Symbol('ActionList.GroupHeading')

packages/react/src/ActionList/Heading.tsx

@@ -51,3 +51,5 @@ export const Heading = forwardRef(({as, size, children, visuallyHidden = false,
 }) as PolymorphicForwardRefComponent<HeadingLevels, ActionListHeadingProps>
 
 Heading.displayName = 'ActionList.Heading'
+
+Heading.__SLOT__ = Symbol('ActionList.Heading')

packages/react/src/ActionList/Item.tsx

@@ -314,8 +314,9 @@ const UnwrappedItem = <As extends React.ElementType = 'li'>(
   )
 }
 
-const Item = fixedForwardRef(UnwrappedItem)
-
-Object.assign(Item, {displayName: 'ActionList.Item'})
+const Item = Object.assign(fixedForwardRef(UnwrappedItem), {
+  displayName: 'ActionList.Item',
+  __SLOT__: Symbol('ActionList.Item'),
+})
 
 export {Item}

packages/react/src/ActionList/LinkItem.tsx

@@ -56,3 +56,5 @@ export const LinkItem = React.forwardRef(
 ) as PolymorphicForwardRefComponent<'a', ActionListLinkItemProps>
 
 LinkItem.displayName = 'ActionList.LinkItem'
+
+LinkItem.__SLOT__ = Symbol('ActionList.LinkItem')

packages/react/src/ActionList/TrailingAction.tsx

@@ -66,3 +66,5 @@ export const TrailingAction = forwardRef(
     )
   },
 ) as PolymorphicForwardRefComponent<'button' | 'a', ActionListTrailingActionProps>
+
+TrailingAction.__SLOT__ = Symbol('ActionList.TrailingAction')

packages/react/src/ActionList/Visuals.tsx

@@ -5,6 +5,7 @@ import {ItemContext} from './shared'
 import {Tooltip, type TooltipProps} from '../TooltipV2'
 import {clsx} from 'clsx'
 import classes from './ActionList.module.css'
+import type {FCWithSlotMarker} from '../utils/types/Slots'
 
 export type VisualProps = React.HTMLAttributes<HTMLSpanElement>
 
@@ -13,7 +14,7 @@ export const VisualContainer: React.FC<React.PropsWithChildren<VisualProps>> = (
 }
 
 export type ActionListLeadingVisualProps = VisualProps
-export const LeadingVisual: React.FC<React.PropsWithChildren<VisualProps>> = ({className, ...props}) => {
+export const LeadingVisual: FCWithSlotMarker<React.PropsWithChildren<VisualProps>> = ({className, ...props}) => {
   return (
     <VisualContainer className={clsx(className, classes.LeadingVisual)} {...props}>
       {props.children}
@@ -22,7 +23,7 @@ export const LeadingVisual: React.FC<React.PropsWithChildren<VisualProps>> = ({c
 }
 
 export type ActionListTrailingVisualProps = VisualProps
-export const TrailingVisual: React.FC<React.PropsWithChildren<VisualProps>> = ({className, ...props}) => {
+export const TrailingVisual: FCWithSlotMarker<React.PropsWithChildren<VisualProps>> = ({className, ...props}) => {
   const {trailingVisualId} = React.useContext(ItemContext)
   return (
     <VisualContainer className={clsx(className, classes.TrailingVisual)} id={trailingVisualId} {...props}>
@@ -78,3 +79,6 @@ export const VisualOrIndicator: React.FC<
 
 LeadingVisual.displayName = 'ActionList.LeadingVisual'
 TrailingVisual.displayName = 'ActionList.TrailingVisual'
+
+LeadingVisual.__SLOT__ = Symbol('ActionList.LeadingVisual')
+TrailingVisual.__SLOT__ = Symbol('ActionList.TrailingVisual')

packages/react/src/ActionMenu/ActionMenu.tsx

@@ -15,6 +15,8 @@ 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 {isSlot} from '../utils/is-slot'
+import type {FCWithSlotMarker, WithSlotMarker} from '../utils/types/Slots'
 
 export type MenuCloseHandler = (
   gesture: 'anchor-click' | 'click-outside' | 'escape' | 'tab' | 'item-select' | 'arrow-left' | 'close',
@@ -71,7 +73,7 @@ const mergeAnchorHandlers = (anchorProps: React.HTMLAttributes<HTMLElement>, but
   return mergedAnchorProps
 }
 
-const Menu: React.FC<React.PropsWithChildren<ActionMenuProps>> = ({
+const Menu: FCWithSlotMarker<React.PropsWithChildren<ActionMenuProps>> = ({
   anchorRef: externalAnchorRef,
   open,
   onOpenChange,
@@ -112,7 +114,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 || isSlot(child, Tooltip)) {
       // tooltip trigger
       const anchorChildren = child.props.children
       if (anchorChildren.type === MenuButton) {
@@ -129,7 +131,8 @@ 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 || isSlot(anchorChildren, Tooltip) : false
       if (isWrappedWithTooltip) {
         if (anchorChildren.props.children !== null) {
           renderAnchor = anchorProps => {
@@ -175,7 +178,15 @@ const Menu: React.FC<React.PropsWithChildren<ActionMenuProps>> = ({
 }
 
 export type ActionMenuAnchorProps = {children: React.ReactElement; id?: string} & React.HTMLAttributes<HTMLElement>
-const Anchor = React.forwardRef<HTMLElement, ActionMenuAnchorProps>(({children: child, ...anchorProps}, anchorRef) => {
+const Anchor: WithSlotMarker<
+  React.ForwardRefExoticComponent<
+    {
+      children: React.ReactElement
+      id?: string
+    } & React.HTMLAttributes<HTMLElement> &
+      React.RefAttributes<HTMLElement>
+  >
+> = React.forwardRef<HTMLElement, ActionMenuAnchorProps>(({children: child, ...anchorProps}, anchorRef) => {
   const {onOpen, isSubmenu} = React.useContext(MenuContext)
 
   const openSubmenuOnRightArrow: React.KeyboardEventHandler<HTMLElement> = useCallback(
@@ -247,7 +258,7 @@ type MenuOverlayProps = Partial<OverlayProps> &
     children: React.ReactNode
     onPositionChange?: ({position}: {position: AnchorPosition}) => void
   }
-const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({
+const Overlay: FCWithSlotMarker<React.PropsWithChildren<MenuOverlayProps>> = ({
   children,
   align = 'start',
   side,
@@ -323,4 +334,10 @@ const Overlay: React.FC<React.PropsWithChildren<MenuOverlayProps>> = ({
 }
 
 Menu.displayName = 'ActionMenu'
+
+Menu.__SLOT__ = Symbol('ActionMenu')
+MenuButton.__SLOT__ = Symbol('ActionMenu.Button')
+Anchor.__SLOT__ = Symbol('ActionMenu.Anchor')
+Overlay.__SLOT__ = Symbol('ActionMenu.Overlay')
+
 export const ActionMenu = Object.assign(Menu, {Button: MenuButton, Anchor, Overlay, Divider})