[Component] Text introduction

.storybook/main.js

@@ -6,8 +6,7 @@ module.exports = {
     '@storybook/addon-essentials',
     '@storybook/addon-interactions',
     '@storybook/addon-a11y',
-    'display-element-css',
-    'storybook-dark-mode'
+    'display-element-css'
   ],
   docs: {
     autodocs: true,

.storybook/manager-head.html

@@ -3,9 +3,22 @@
     font-size: 15px !important;
   }
 
-  div.sidebar-item[data-selected="false"]:hover,
+  /* Sidebar hover */
+  div.sidebar-item[data-selected='false']:hover,
   button.sidebar-item:hover {
     background-color: #5a5d61 !important;
     color: white !important;
   }
-</style>
+
+  /* Sidebar hover/selected icons */
+  div.sidebar-item[data-selected='false']:hover svg,
+  button.sidebar-item:hover svg {
+    color: white;
+  }
+
+  /* Sidebar icons */
+  .sidebar-item svg {
+    color: black;
+  }
+
+</style>

.storybook/manager.js

@@ -1,4 +1,5 @@
 import { addons } from '@storybook/manager-api';
+import themeCFPB from './themeCFPB';
 
 addons.setConfig({
   sidebar: {
@@ -11,5 +12,6 @@ addons.setConfig({
       }
       return name;
     }
-  }
+  },
+  theme: themeCFPB
 });

.storybook/preview.js

@@ -1,42 +1,26 @@
 import '@cfpb/cfpb-design-system/src/cfpb-design-system.less';
-import { themes } from '@storybook/theming';
-import CfpbLogo from '../src/assets/images/cfpb-logo-vertical.png';
 import '../src/assets/styles/_shared.less';
+import themeCFPB from './themeCFPB';
 
-const sharedThemeElements = {
-  brandTitle: 'CFPB Design System React',
-  brandImage: CfpbLogo,
-  brandUrl: 'https://cfpb.github.io/design-system/',
-  brandTarget: '_blank',
-  fontBase: '"Avenir Next", Arial ,sans-serif'
-};
-
-export const parameters = {
-  options: {
-    // Determines the display order of Stories in the sidebar
-    storySort: {
-      order: ['Guides', 'Components (Verified)', 'Components (Draft)', '*']
-    }
-  },
-  actions: { argTypesRegex: '^on[A-Z].*' },
-  controls: {
-    matchers: {
-      color: /(background|color)$/i,
-      date: /Date$/
-    }
-  },
-  darkMode: {
-    current: 'dark',
-    // Override the default dark theme
-    dark: {
-      ...themes.dark,
-      ...sharedThemeElements,
-      appBg: 'black'
+export const preview = {
+  parameters: {
+    options: {
+      // Determines the display order of Stories in the sidebar
+      storySort: {
+        order: ['Guides', 'Components (Verified)', 'Components (Draft)', '*']
+      }
+    },
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/
+      }
     },
-    // Override the default light theme
-    light: {
-      ...themes.normal,
-      ...sharedThemeElements
+    docs: {
+      theme: themeCFPB
     }
   }
 };
+
+export default preview;

.storybook/themeCFPB.js

@@ -0,0 +1,53 @@
+import { create } from '@storybook/theming/create';
+import CfpbLogo from '../src/assets/images/cfpb-logo-vertical.png';
+
+const colors = {
+  black: '#101820',
+  gray: '#5a5d61',
+  gray10: '#e7e8e9',
+  gray40: '#b4b5b6',
+  green10: '#f0f8eb',
+  teal: '#257675',
+  teal80: '#579695'
+};
+
+/**
+ * Note: Additional CSS customizations are implemented in
+ * - /.storybook/manager-head.html
+ * - /src/assets/styles/_shared.less
+ */
+export default create({
+  base: 'light',
+
+  brandTitle: 'CFPB Design System React',
+  brandImage: CfpbLogo,
+  brandUrl: 'https://cfpb.github.io/design-system/',
+  brandTarget: '_blank',
+
+  fontBase: '"Avenir Next", Arial ,sans-serif',
+
+  // App
+  appBorderColor: colors.gray,
+  appContentBg: 'white', // Story overview, tool panel
+
+  // Sidebar
+  appBg: 'white', // Background
+  textColor: colors.black, // Story names
+  textMutedColor: colors.black, // Group names
+
+  // Toolbars
+  // colorPrimary: 'color', // Purpose unknown
+  colorSecondary: colors.teal, // Selected (Controls, Actions, etc)
+  barTextColor: colors.black, // Text & icons
+  barSelectedColor: colors.teal,
+  barBg: colors.gray10,
+
+  // Form colors (Controls)
+  buttonBg: colors.gray10,
+  buttonBorder: colors.gray40,
+  booleanBg: colors.gray10,
+  booleanSelectedBg: colors.teal80,
+  inputBg: 'white',
+  inputBorder: colors.gray,
+  inputTextColor: colors.black
+});

package.json

@@ -117,7 +117,6 @@
     "prettier": "2.7.1",
     "start-server-and-test": "1.14.0",
     "storybook": "^7.0.6",
-    "storybook-dark-mode": "^3.0.1",
     "stylelint": "14.15.0",
     "stylelint-config-prettier": "9.0.4",
     "stylelint-config-standard": "29.0.0",

src/assets/styles/_shared.less

@@ -57,3 +57,10 @@ pre.prismjs,
 :where(p:not(.sb-story *, #storybook-root *)) {
   line-height: 22px !important;
 }
+
+/* 
+Apply a global line-height that doesn't interfere with component Stories that have their own line-height settings. 
+*/
+:where(p:not(.sb-story *, #storybook-root *)){
+  line-height: 22px !important;
+}

src/components/Paragraph/Paragraph.test.tsx

@@ -0,0 +1,19 @@
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import { Paragraph } from './Paragraph';
+
+describe('<Paragraph />', () => {
+  const helperText = 'helperText goes here';
+
+  it('renders Body text', () => {
+    render(<Paragraph>{helperText}</Paragraph>);
+    expect(screen.getByText(helperText)).toBeInTheDocument();
+  });
+
+  it('renders Lead paragraph', () => {
+    render(<Paragraph isLead>{helperText}</Paragraph>);
+    const element = screen.getByText(helperText);
+    expect(element).toBeInTheDocument();
+    expect(element.classList.contains('lead-paragraph')).toBe(true);
+  });
+});

src/components/Paragraph/Paragraph.tsx

@@ -0,0 +1,29 @@
+import classnames from 'classnames';
+
+interface ParagraphProperties extends React.HTMLProps<HTMLParagraphElement> {
+  isLead?: boolean;
+}
+
+/**
+ * Paragraph text should provide an efficient and pleasant experience on every viewport size. Readable text makes good use of alignment, spacing, line length and height, and contrast.
+ *
+ * Source: https://cfpb.github.io/design-system/foundation/paragraphs
+ */
+export function Paragraph({
+  children,
+  isLead,
+  className,
+  ...properties
+}: ParagraphProperties): JSX.Element {
+  const cnames = [className];
+
+  if (isLead) cnames.push('lead-paragraph');
+
+  return (
+    <p {...properties} className={classnames(cnames)}>
+      {children}
+    </p>
+  );
+}
+
+export default Paragraph;

src/components/Paragraph/Paragraphs.stories.tsx

@@ -0,0 +1,26 @@
+import type { Meta } from '@storybook/react';
+import { Paragraph } from './Paragraph';
+
+const meta: Meta<typeof Paragraph> = {
+  title: 'Components (Draft)/Paragraphs',
+  component: Paragraph
+};
+
+export default meta;
+
+export const Body = {
+  name: 'Body text',
+  args: {
+    children:
+      '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.'
+  }
+};
+
+export const Lead = {
+  name: 'Lead paragraph',
+  args: {
+    children:
+      '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.',
+    isLead: true
+  }
+};

src/components/TextIntroduction/TextIntroduction.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta } from '@storybook/react';
+import { TextIntroduction } from './TextIntroduction';
+import placeholders from './testHelpers';
+
+const meta: Meta<typeof TextIntroduction> = {
+  title: 'Components (Draft)/Text introductions',
+  component: TextIntroduction
+};
+
+export default meta;
+
+export const Standard = {
+  name: 'Standard text introduction',
+  args: {
+    ...placeholders
+  }
+};

src/components/TextIntroduction/TextIntroduction.test.tsx

@@ -0,0 +1,14 @@
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import { TextIntroduction } from './TextIntroduction';
+import placeholders 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('Call-to-action link')).toBeInTheDocument();
+  });
+});

src/components/TextIntroduction/TextIntroduction.tsx

@@ -0,0 +1,54 @@
+import classnames from 'classnames';
+import { cloneElement, type ReactNode } from 'react';
+import { Heading } from '../Headings/Heading';
+import List from '../List/List';
+import ListItem from '../List/ListItem';
+import { Paragraph } from '../Paragraph/Paragraph';
+
+interface TextIntroductionProperties extends React.HTMLProps<HTMLDivElement> {
+  // Page title
+  heading: string;
+  // Lead paragraph
+  subheading: string;
+  // Descriptive paragraph
+  description?: ReactNode;
+  // Call-to-action <Link>
+  callToAction?: JSX.Element;
+}
+
+/**
+ * The text introduction is the standard page introduction pattern used across all pages that do not have a <a href="https://cfpb.github.io/design-system/patterns/heroes">hero</a> or <a href="https://cfpb.github.io/design-system/patterns/item-introductions">item introduction</a>. They introduce a page, or collection of pages, with a brief description of the goals of that section.
+ *
+ * Source: https://cfpb.github.io/design-system/patterns/text-introductions
+ */
+export const TextIntroduction = ({
+  heading,
+  subheading,
+  description,
+  callToAction,
+  className,
+  ...properties
+}: TextIntroductionProperties): JSX.Element => {
+  const cnames = ['o-text-introduction', className];
+
+  const call2action = callToAction && (
+    <List isLinks>
+      <ListItem>{cloneElement(callToAction, { type: 'list' })}</ListItem>
+    </List>
+  );
+
+  return (
+    <div
+      className={classnames(cnames)}
+      {...properties}
+      data-testid='text-introduction-wrapper'
+    >
+      <Heading type='1'>{heading}</Heading>
+      <Paragraph isLead>{subheading}</Paragraph>
+      {description ? <p>{description}</p> : null}
+      {call2action}
+    </div>
+  );
+};
+
+export default TextIntroduction;

src/components/TextIntroduction/testHelpers.tsx

@@ -0,0 +1,16 @@
+import Link from '../Link/Link';
+
+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 =
+  '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 default {
+  heading: 'Heading 1',
+  description,
+  subheading,
+  callToAction
+};

src/index.ts

@@ -36,6 +36,7 @@ export { default as Navbar } from './components/Navbar/Navbar';
 export { Notification } from './components/Notification/Notification';
 export { default as PageHeader } from './components/PageHeader/PageHeader';
 export { Pagination } from './components/Pagination/Pagination';
+export { Paragraph } from './components/Paragraph/Paragraph';
 export { RadioButton } from './components/RadioButton/RadioButton';
 export {
   TableComplex,
@@ -44,5 +45,6 @@ export {
 } from './components/Table/Table';
 export { Tagline } from './components/Tagline/Tagline';
 export { TextInput } from './components/TextInput/TextInput';
+export { TextIntroduction } from './components/TextIntroduction/TextIntroduction';
 export { default as Well } from './components/Well/Well';