hero component cleanup (#597)

Addresses: #596 

Hero work:
- aligned with cfpb heroes pattern docs
- dropped headingLevel subheadingLevel textColor props
- heading and subheading typed as strings
- use DSR Heading type 1 with m-hero__heading not raw h1
- subheading still p.m-hero__subhead
- root is section not div
- backgroundColor on wrapper normally, on section for knockout
- fixed useBackgroundImage clearing wrapper backgroundColor
- HeroProperties omits children and color from html attrs
- only render heading/subheading when provided
- Added mobileImage option for photograph heroes
- updated stories to point to images from DS github page

Author: flacoman91

src/components/Hero/hero-image.tsx

@@ -1,30 +1,47 @@
+import type { CSSProperties } from 'react';
 import type { JSXElement } from '../../types/jsx-element';
 
 interface HeroImageProperties {
   image?: string;
+  mobileImage?: string;
   altText?: string;
 }
 
+type HeroImageStyle = CSSProperties & {
+  '--m-hero-image'?: string;
+  '--m-hero-mobile-image'?: string;
+};
+
+const createBackgroundImageValue = (image: string): string =>
+  `url(${JSON.stringify(image)})`;
+
 /**
  * DS pattern: empty `.m-hero__image` with `background-image` (not `<img>`), so
  * `background-size: contain` and aspect ratio control the slot height.
  * https://cfpb.github.io/design-system/patterns/heroes
  */
 export const HeroImage = ({
   image,
+  mobileImage,
   altText,
 }: HeroImageProperties): JSXElement => {
-  if (!image) return null;
+  if (!image && !mobileImage) return null;
+
+  const imageStyle: HeroImageStyle = {};
+
+  if (image) imageStyle['--m-hero-image'] = createBackgroundImageValue(image);
+  if (mobileImage) {
+    imageStyle['--m-hero-mobile-image'] =
+      createBackgroundImageValue(mobileImage);
+  }
 
   return (
     <div className='m-hero__image-wrapper'>
       <div
         className='m-hero__image'
         role='img'
         aria-label={altText}
-        style={{
-          backgroundImage: `url(${JSON.stringify(image)})`,
-        }}
+        style={imageStyle}
       />
     </div>
   );

src/components/Hero/hero.scss

@@ -4,6 +4,24 @@
   background-color: var(--gray-30);
 }
 
+.m-hero__image {
+  background-image: var(--m-hero-mobile-image, var(--m-hero-image));
+}
+
+.m-hero--overlay .m-hero__wrapper {
+  background-image: none;
+}
+
+@media screen and (min-width: 37.5625em) {
+  .m-hero__image {
+    background-image: var(--m-hero-image, var(--m-hero-mobile-image));
+  }
+
+  .m-hero--overlay .m-hero__wrapper {
+    background-image: var(--m-hero-wrapper-image);
+  }
+}
+
 // Illustration slot: match common DS hero artwork (940×390).
 //
 // Production DS/Jinja pages often set this on an empty `.m-hero__image` with `background-image`,

src/components/Hero/hero.stories.tsx

@@ -32,7 +32,7 @@ export const WithIllustration: Story = {
   args: {
     heading: '41 characters max for a one-line heading',
     image:
-      'https://cfpb.github.io/design-system/images/uploads/hero_illustration_example_keys.png',
+      'https://cfpb.github.io/design-system/images/uploads/design_system_illustration_hero_example.png',
     subheading:
       'This text has a recommended count of 165-186 characters (three lines at 1230px) following a one-line heading and 108-124 characters (two lines at 1230px) following a two-line heading.',
     backgroundColor: '#d4e7e6',
@@ -44,7 +44,10 @@ export const WithPhotograph: Story = {
   args: {
     ...WithIllustration.args,
     imageIsPhoto: true,
-    image: 'https://files.consumerfinance.gov/f/images/PC_hero.original.jpg',
+    image:
+      'https://cfpb.github.io/design-system/images/uploads/design_system_photo_hero_example.png',
+    mobileImage:
+      'https://cfpb.github.io/design-system/images/uploads/design_system_photo_hero_sm_example.jpg',
     backgroundColor: '#f7f8f9',
   },
 };
@@ -59,6 +62,6 @@ export const WithKnockoutText: Story = {
     backgroundColor: '#207676',
     isKnockout: true,
     image:
-      'https://cfpb.github.io/design-system/images/uploads/design_system_hero_example.png',
+      'https://cfpb.github.io/design-system/images/uploads/design_system_knockout_hero_example.png',
   },
 };

src/components/Hero/hero.test.tsx

@@ -1,8 +1,9 @@
+import '@testing-library/jest-dom';
 import { render, screen } from '@testing-library/react';
 import Hero from './hero';
 
 describe('Hero', () => {
-  it('Renders all elements: heading, subheading, image', () => {
+  it('renders heading, subheading, and image with DS classes', () => {
     const heading = 'heading';
     const subheading = 'subheading';
     const image = '../../assets/images/credit-card-hero.png';
@@ -17,69 +18,117 @@ describe('Hero', () => {
       />,
     );
 
-    expect(screen.getByText(heading).className).toMatch(/m-hero__heading/g);
-    expect(screen.getByText(subheading).className).toMatch(/m-hero__subhead/g);
-    expect(screen.getByRole('img', { name: imageText }).className).toMatch(
-      /m-hero__image/g,
+    const headingElement = screen.getByRole('heading', { level: 1 });
+    expect(headingElement).toHaveClass('m-hero__heading');
+    expect(headingElement).toHaveTextContent(heading);
+
+    const subheadingElement = screen.getByText(subheading);
+    expect(subheadingElement.tagName).toBe('P');
+    expect(subheadingElement).toHaveClass('m-hero__subhead');
+
+    expect(screen.getByRole('img', { name: imageText })).toHaveClass(
+      'm-hero__image',
     );
   });
 
-  it('Derives CSS classes for component variations', () => {
+  it('derives CSS classes for component variations', () => {
     const isKnockout = 'm-hero--knockout';
     const imageIsPhoto = 'm-hero--overlay';
 
     render(<Hero isKnockout data-testid={isKnockout} />);
-    expect(screen.getByTestId(isKnockout).className).toMatch(isKnockout);
+    expect(screen.getByTestId(isKnockout)).toHaveClass(isKnockout);
 
-    render(<Hero imageIsPhoto data-testid={imageIsPhoto} />);
-    expect(screen.getByTestId(imageIsPhoto).className).toMatch(imageIsPhoto);
+    render(
+      <Hero
+        imageIsPhoto
+        mobileImage='/mobile-photo.jpg'
+        data-testid={imageIsPhoto}
+      />,
+    );
+    expect(screen.getByTestId(imageIsPhoto)).toHaveClass(imageIsPhoto);
   });
 
-  it('Applies direct color settings', () => {
-    const textColor = 'orange';
-    const backgroundColor = 'purple';
-    const wrapperSelector = 'wrapper';
-    const textId = 'hero-text';
+  it('applies background color on the section for standard heroes', () => {
+    render(
+      <Hero backgroundColor='#800080' heading='test' data-testid='hero' />,
+    );
+
+    expect(screen.getByTestId('hero')).toHaveStyle({
+      backgroundColor: 'rgb(128, 0, 128)',
+    });
+    expect(screen.getByTestId('hero-wrapper')).not.toHaveAttribute('style');
+  });
 
+  it('applies background color on the section for knockout heroes', () => {
     render(
       <Hero
-        data-testid='wrapper'
-        textColor={textColor}
-        backgroundColor={backgroundColor}
+        isKnockout
+        backgroundColor='#207676'
         heading='test'
+        data-testid='hero'
       />,
     );
 
-    // Background color
-    const wrapper = screen.getByTestId(wrapperSelector);
-    expect(wrapper.style.backgroundColor).toMatch(backgroundColor);
+    expect(screen.getByTestId('hero')).toHaveStyle({
+      backgroundColor: '#207676',
+    });
+  });
 
-    // Text color
-    const text = screen.getByTestId(textId);
-    expect(text.style.color).toMatch(textColor);
+  it('does not set inline text color (knockout uses DS styles)', () => {
+    render(
+      <Hero isKnockout heading='test' subheading='sub' data-testid='hero' />,
+    );
+
+    expect(screen.getByTestId('hero-text')).not.toHaveAttribute('style');
   });
 
-  it('Applies heading levels', () => {
-    const headingLevel = 2;
-    const headingText = 'Heading text';
-    const subheadingLevel = 3;
-    const subheadingText = 'Subheading text';
+  it('uses the mobile image in the image slot for photo heroes', () => {
+    render(
+      <Hero
+        imageIsPhoto
+        image='/desktop-photo.png'
+        mobileImage='/mobile-photo.jpg'
+        imageAltText='photo hero'
+      />,
+    );
+
+    const heroImage = screen.getByRole('img', { name: 'photo hero' });
+    expect(heroImage.style.getPropertyValue('--m-hero-image')).toBe(
+      'url("/desktop-photo.png")',
+    );
+    expect(heroImage.style.getPropertyValue('--m-hero-mobile-image')).toBe(
+      'url("/mobile-photo.jpg")',
+    );
+  });
 
+  it('supports a mobile image in the image slot for non-photo heroes', () => {
     render(
       <Hero
-        heading='Heading text'
-        headingLevel={`h${headingLevel}`}
-        subheading='Subheading text'
-        subheadingLevel={`h${subheadingLevel}`}
+        image='/illustration.png'
+        mobileImage='/mobile-photo.jpg'
+        imageAltText='illustration hero'
       />,
     );
 
-    // Heading
-    const header = screen.getByRole('heading', { level: headingLevel });
-    expect(header).toHaveProperty('textContent', headingText);
+    const heroImage = screen.getByRole('img', { name: 'illustration hero' });
+    expect(heroImage.style.getPropertyValue('--m-hero-image')).toBe(
+      'url("/illustration.png")',
+    );
+    expect(heroImage.style.getPropertyValue('--m-hero-mobile-image')).toBe(
+      'url("/mobile-photo.jpg")',
+    );
+  });
 
-    // Subheading
-    const subheading = screen.getByRole('heading', { level: subheadingLevel });
-    expect(subheading).toHaveProperty('textContent', subheadingText);
+  it('requires a mobile image for photo heroes', () => {
+    expect(() =>
+      render(
+        // @ts-expect-error mobileImage is required when imageIsPhoto is true.
+        <Hero
+          imageIsPhoto
+          image='/desktop-photo.png'
+          imageAltText='photo hero'
+        />,
+      ),
+    ).toThrow('Hero requires mobileImage when imageIsPhoto is true.');
   });
 });