Add leadingComponent slot to section intro component (#878)

Author: rezrah

.changeset/early-roses-pump.md

@@ -0,0 +1,15 @@
+---
+'@primer/react-brand': patch
+---
+
+Added `leadingComponent` slot to `SectionIntro` for inserting arbitrary visuals and JSX above the heading.
+
+```jsx
+<SectionIntro leadingComponent={() => <img src="leading-visual.png" alt="description of your leading visual" />}>
+  <SectionIntro.Heading>...</SectionIntro.Heading>
+  <SectionIntro.Description>...</SectionIntro.Description>
+  <SectionIntro.Link>...</SectionIntro.Link>
+</SectionIntro>
+```
+
+🔗 [See Storybook example](https://primer.style/brand/storybook?path=/story/components-sectionintro-features--leading-component)

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

@@ -1,6 +1,7 @@
 import React from 'react'
 import {Meta} from '@storybook/react'
 import {SectionIntro} from '.'
+import {CopilotIcon} from '@primer/octicons-react'
 
 export default {
   title: 'Components/SectionIntro/Features',
@@ -84,3 +85,15 @@ export const FullWidth = () => (
     </SectionIntro.Heading>
   </SectionIntro>
 )
+
+export const LeadingComponent = () => {
+  const Image = () => <CopilotIcon size={40} />
+
+  return (
+    <SectionIntro leadingComponent={Image} align="center">
+      <SectionIntro.Heading>
+        <b>Expressive headline</b> about an exclusive set of features.
+      </SectionIntro.Heading>
+    </SectionIntro>
+  )
+}

packages/react/src/SectionIntro/SectionIntro.test.tsx

@@ -214,4 +214,23 @@ describe('SectionIntro', () => {
 
     expect(results).toHaveNoViolations()
   })
+
+  it('accepts a leading component that renders in the correct location', () => {
+    const mockImage = 'mockImage.png'
+
+    const {getByRole, container} = render(
+      <SectionIntro leadingComponent={() => <img src={mockImage} alt="mock" />}>
+        <SectionIntro.Heading>{mockHeading}</SectionIntro.Heading>
+        <SectionIntro.Description>{mockDescription}</SectionIntro.Description>
+        <SectionIntro.Link href="#">{mockLinkText}</SectionIntro.Link>
+      </SectionIntro>,
+    )
+
+    const imgEl = getByRole('img')
+    expect(imgEl).toBeInTheDocument()
+    expect(imgEl).toHaveAttribute('src', mockImage)
+
+    const sectionIntroEl = container.firstChild
+    expect(sectionIntroEl?.firstChild).toBe(imgEl)
+  })
 })

packages/react/src/SectionIntro/SectionIntro.tsx

@@ -13,11 +13,30 @@ import type {BaseProps} from '../component-helpers'
 export type SectionIntroProps = {
   align?: 'start' | 'center'
   fullWidth?: boolean
+  /**
+   * Escape-hatch for inserting custom React components.
+   * Warning:
+   *   This prop isn't advertised in our docs but remains part of the public API for edge-cases.
+   *   Need to use this prop? Please check in with #primer-brand first to confirm correct usage.
+   */
+  leadingComponent?: React.FunctionComponent
 } & React.HTMLAttributes<HTMLHeadingElement> &
   BaseProps<HTMLHeadingElement>
 
 const Root = forwardRef<HTMLHeadingElement, PropsWithChildren<SectionIntroProps>>(
-  ({align = 'start', animate, className, children, fullWidth = false, style, ...props}, ref) => {
+  (
+    {
+      align = 'start',
+      animate,
+      className,
+      children,
+      fullWidth = false,
+      leadingComponent: LeadingComponent,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
     const {classes: animationClasses, styles: animationInlineStyles} = useAnimation(animate)
 
     return (
@@ -33,6 +52,7 @@ const Root = forwardRef<HTMLHeadingElement, PropsWithChildren<SectionIntroProps>
         {...props}
         style={{...animationInlineStyles, ...style}}
       >
+        {LeadingComponent && <LeadingComponent />}
         {children}
       </header>
     )

packages/react/src/SectionIntro/SectionIntro.visual.spec.ts

@@ -92,4 +92,13 @@ test.describe('Visual Comparison: SectionIntro', () => {
     await page.waitForTimeout(500)
     expect(await page.screenshot({fullPage: true})).toMatchSnapshot()
   })
+
+  test('SectionIntro / Leading Component', async ({page}) => {
+    await page.goto(
+      'http://localhost:6006/iframe.html?args=&id=components-sectionintro-features--leading-component&viewMode=story',
+    )
+
+    await page.waitForTimeout(500)
+    expect(await page.screenshot({fullPage: true})).toMatchSnapshot()
+  })
 })