TextIntroduction -- Functional Dot Notation (#258)

Closes #260 

## Changes

- TextIntroduction is now more composable with subcomponents
- TextIntroduction story is updated (click on See Code)

## How to test this PR

1. View TextIntroduction Storybook story
2. Code Inspection
3. `yarn test TextIntroduction`

## Screenshots
<img width="666" alt="Screenshot 2023-12-05 at 9 56 55 AM"
src="https://github.com/cfpb/design-system-react/assets/13324863/6b4ee445-b690-49a7-ac4f-7ba706b188b3">

src/components/TextIntroduction/TextIntroduction.stories.tsx

@@ -1,6 +1,13 @@
-import type { Meta } from '@storybook/react';
-import { TextIntroduction } from '~/src/index';
-import placeholders from './testHelpers';
+import type { Meta, StoryObj } from '@storybook/react';
+import { cloneElement } from 'react';
+import { List, ListItem, TextIntroduction } from '~/src/index';
+import {
+  callToAction,
+  description,
+  heading,
+  placeholders,
+  subheading
+} from './testHelpers';
 
 const meta: Meta<typeof TextIntroduction> = {
   title: 'Components (Verified)/Text introductions',
@@ -10,9 +17,26 @@ const meta: Meta<typeof TextIntroduction> = {
 
 export default meta;
 
+type Story = StoryObj<typeof meta>;
+
 export const Standard = {
   name: 'Standard text introduction',
   args: {
     ...placeholders
   }
 };
+
+export const Flexible: Story = {
+  render: _arguments => (
+    <TextIntroduction.Container {..._arguments}>
+      <TextIntroduction.Heading>{heading}</TextIntroduction.Heading>
+      <TextIntroduction.Subheading>{subheading}</TextIntroduction.Subheading>
+      <TextIntroduction.Description>{description}</TextIntroduction.Description>
+      <List isLinks>
+        <ListItem>{cloneElement(callToAction, { type: 'list' })}</ListItem>
+      </List>
+    </TextIntroduction.Container>
+  ),
+  name: 'Flexible text introduction',
+  args: {}
+};

src/components/TextIntroduction/TextIntroduction.test.tsx

@@ -1,14 +1,43 @@
 import '@testing-library/jest-dom';
 import { render, screen } from '@testing-library/react';
-import { TextIntroduction } from '~/src/index';
-import placeholders from './testHelpers';
+import { cloneElement } from 'react';
+import { List, ListItem, TextIntroduction } from '~/src/index';
+import {
+  callToAction,
+  callToActionText,
+  description,
+  heading,
+  placeholders,
+  subheading
+} from './testHelpers';
 
 describe('<TextIntroduction />', () => {
   it('renders all elements when provided', () => {
     render(<TextIntroduction {...placeholders} />);
-    expect(screen.getByText(placeholders.heading)).toBeInTheDocument();
-    expect(screen.getByText(placeholders.subheading)).toBeInTheDocument();
-    expect(screen.getByText(placeholders.description)).toBeInTheDocument();
+    expect(screen.getByText(heading)).toBeInTheDocument();
+    expect(screen.getByText(subheading)).toBeInTheDocument();
+    expect(screen.getByText(description)).toBeInTheDocument();
     expect(screen.getByText('Call-to-action link')).toBeInTheDocument();
   });
 });
+
+describe('<TextIntroduction.Container />', () => {
+  it('renders all elements when provided', () => {
+    render(
+      <TextIntroduction.Container>
+        <TextIntroduction.Heading>{heading}</TextIntroduction.Heading>
+        <TextIntroduction.Subheading>{subheading}</TextIntroduction.Subheading>
+        <TextIntroduction.Description>
+          {description}
+        </TextIntroduction.Description>
+        <List isLinks>
+          <ListItem>{cloneElement(callToAction, { type: 'list' })}</ListItem>
+        </List>
+      </TextIntroduction.Container>
+    );
+    expect(screen.getByText(heading)).toBeInTheDocument();
+    expect(screen.getByText(subheading)).toBeInTheDocument();
+    expect(screen.getByText(description)).toBeInTheDocument();
+    expect(screen.getByText(callToActionText)).toBeInTheDocument();
+  });
+});

src/components/TextIntroduction/TextIntroduction.tsx

@@ -51,4 +51,49 @@ export const TextIntroduction = ({
   );
 };
 
+TextIntroduction.Container = ({
+  className,
+  children,
+  ...properties
+}: React.HTMLProps<HTMLDivElement>): JSX.Element => {
+  const cnames = ['o-text-introduction', className];
+
+  return (
+    <div
+      className={classnames(cnames)}
+      {...properties}
+      data-testid='text-introduction-wrapper'
+    >
+      {children}
+    </div>
+  );
+};
+
+export const TextIntroductionContainer = TextIntroduction.Container;
+interface TextIntroductionSubProperties {
+  children: ReactNode;
+}
+
+TextIntroduction.Heading = ({
+  children
+}: TextIntroductionSubProperties): JSX.Element => (
+  <Heading type='1'>{children}</Heading>
+);
+
+export const TextIntroductionHeading = TextIntroduction.Heading;
+
+TextIntroduction.Description = ({
+  children
+}: TextIntroductionSubProperties): JSX.Element => <p>{children}</p>;
+
+export const TextIntroductionDescription = TextIntroduction.Description;
+
+TextIntroduction.Subheading = ({
+  children
+}: TextIntroductionSubProperties): JSX.Element => (
+  <Paragraph isLead>{children}</Paragraph>
+);
+
+export const TextIntroductionSubheading = TextIntroduction.Subheading;
+
 export default TextIntroduction;

src/components/TextIntroduction/testHelpers.tsx

@@ -1,16 +1,28 @@
 import Link from '../Link/Link';
 
-const subheading =
+export const heading = 'Heading 1';
+
+export const subheading =
   'Lead paragraph lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.';
 
-const description =
+export const description =
   'Descriptive paragraph lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore.';
 
-const callToAction = <Link href='/'>Call-to-action link</Link>;
+export const callToActionText = 'Call-to-action link';
+
+export const callToAction = <Link href='/'>{callToActionText}</Link>;
+
+export const placeholders = {
+  heading,
+  subheading,
+  description,
+  callToAction
+};
 
 export default {
-  heading: 'Heading 1',
+  heading,
   description,
   subheading,
-  callToAction
+  callToAction,
+  callToActionText
 };

src/index.ts

@@ -44,5 +44,11 @@ export { RadioButton } from './components/RadioButton/RadioButton';
 export { Table } from './components/Table/Table';
 export { Tagline } from './components/Tagline/Tagline';
 export { TextInput } from './components/TextInput/TextInput';
-export { TextIntroduction } from './components/TextIntroduction/TextIntroduction';
+export {
+  TextIntroduction,
+  TextIntroductionContainer,
+  TextIntroductionDescription,
+  TextIntroductionHeading,
+  TextIntroductionSubheading
+} from './components/TextIntroduction/TextIntroduction';
 export { WellContainer, WellContent } from './components/Well/Well';