feat(Page): Add PageHeader component

PageHeader can be used to wrap masthead or hold a third-party custom header.

Fixes #12624

Assisted-by: Cursor

Author: rebeccaalpert

packages/react-core/src/components/Page/Page.tsx

@@ -28,7 +28,10 @@ export interface PageProps extends React.HTMLProps<HTMLDivElement> {
    * will handle toggling the visibility of the text in individual isDocked components.
    */
   isDockTextExpanded?: boolean;
-  /** The horizontal masthead content (e.g. <Masthead />). When using the docked variant, this content will only render at mobile viewports. */
+  /** The horizontal masthead content (e.g. <Masthead /> or <PageHeader />). PageHeader is an alternative to Masthead
+   * and can wrap a Masthead or custom header content. When using the docked variant, this content will only render at
+   * mobile viewports.
+   */
   masthead?: React.ReactNode;
   /** @beta Content to render in the vertical dock when variant of docked is used. At mobile viewports, this content will be replaced with the content passed to masthead. */
   dockContent?: React.ReactNode;

packages/react-core/src/components/Page/PageHeader.tsx

@@ -0,0 +1,28 @@
+import styles from '@patternfly/react-styles/css/components/Page/page';
+import { css } from '@patternfly/react-styles';
+
+export interface PageHeaderProps extends React.HTMLProps<HTMLElement> {
+  /** Content rendered inside the page header. This can be a Masthead or custom header content. */
+  children?: React.ReactNode;
+  /** Additional classes added to the page header */
+  className?: string;
+  /** Sets the base component to render. Defaults to div */
+  component?: keyof React.JSX.IntrinsicElements;
+}
+
+export const PageHeader: React.FunctionComponent<PageHeaderProps> = ({
+  className,
+  children,
+  component = 'div',
+  ...props
+}: PageHeaderProps) => {
+  const Component = component as any;
+
+  return (
+    <Component {...props} className={css(styles.pageHeader, className)}>
+      {children}
+    </Component>
+  );
+};
+
+PageHeader.displayName = 'PageHeader';

packages/react-core/src/components/Page/__tests__/Page.test.tsx

@@ -9,6 +9,7 @@ import { Nav, NavList, NavItem } from '../../Nav';
 import { SkipToContent } from '../../SkipToContent';
 import { PageBreadcrumb } from '../PageBreadcrumb';
 import { PageGroup } from '../PageGroup';
+import { PageHeader } from '../PageHeader';
 import { Masthead } from '../../Masthead';
 
 import styles from '@patternfly/react-styles/css/components/Page/page';
@@ -487,4 +488,33 @@ describe('Page docked variant', () => {
     const pageDockMain = screen.getByText('Dock content').closest(`.${styles.pageDockMain}`);
     expect(pageDockMain).toBeInTheDocument();
   });
+
+  test('Renders PageHeader when passed to the masthead prop', () => {
+    render(
+      <Page {...props} masthead={<PageHeader>Custom header</PageHeader>}>
+        <PageSection>Custom content</PageSection>
+      </Page>
+    );
+
+    const header = screen.getByText('Custom header');
+    expect(header).toHaveClass(styles.pageHeader);
+    expect(header.parentElement).toHaveClass(styles.page);
+  });
+
+  test('Renders Masthead inside PageHeader when passed to the masthead prop', () => {
+    render(
+      <Page
+        {...props}
+        masthead={
+          <PageHeader>
+            <Masthead>Logo</Masthead>
+          </PageHeader>
+        }
+      >
+        <PageSection>Custom content</PageSection>
+      </Page>
+    );
+
+    expect(screen.getByText('Logo').closest(`.${styles.pageHeader}`)).toBeInTheDocument();
+  });
 });

packages/react-core/src/components/Page/__tests__/PageHeader.test.tsx

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react';
+import styles from '@patternfly/react-styles/css/components/Page/page';
+import { PageHeader } from '../PageHeader';
+
+test('Renders children', () => {
+  render(<PageHeader>Header content</PageHeader>);
+  expect(screen.getByText('Header content')).toBeVisible();
+});
+
+test(`Renders with class ${styles.pageHeader} by default`, () => {
+  render(<PageHeader>Header content</PageHeader>);
+  expect(screen.getByText('Header content')).toHaveClass(styles.pageHeader);
+});
+
+test('Renders as a div by default', () => {
+  render(<PageHeader>Header content</PageHeader>);
+  expect(screen.getByText('Header content').tagName).toBe('DIV');
+});
+
+test('Renders as a custom component when component is passed', () => {
+  render(<PageHeader component="header">Header content</PageHeader>);
+  expect(screen.getByText('Header content').tagName).toBe('HEADER');
+});
+
+test('Renders with custom classes when className is passed', () => {
+  render(<PageHeader className="custom-class">Header content</PageHeader>);
+  expect(screen.getByText('Header content')).toHaveClass('custom-class');
+});
+
+test('Renders with spread props', () => {
+  render(<PageHeader id="custom-id">Header content</PageHeader>);
+  expect(screen.getByText('Header content')).toHaveAttribute('id', 'custom-id');
+});

packages/react-core/src/components/Page/examples/Page.md

@@ -3,7 +3,16 @@ id: Page
 section: components
 cssPrefix: pf-v6-c-page
 propComponents:
-  ['Page', 'PageSidebar', 'PageSidebarBody', 'PageSection', 'PageGroup', 'PageBreadcrumb', 'PageToggleButton']
+  [
+    'Page',
+    'PageHeader',
+    'PageSidebar',
+    'PageSidebarBody',
+    'PageSection',
+    'PageGroup',
+    'PageBreadcrumb',
+    'PageToggleButton'
+  ]
 ---
 
 import { useState, useLayoutEffect, useRef } from 'react';
@@ -16,14 +25,22 @@ import pageSectionWidthLimitMaxWidth from '@patternfly/react-tokens/dist/esm/c_p
 
 A page will typically contain the following components:
 
-- A `<Page>` with a `masthead` prop that often contains a [masthead](/components/masthead) component
+- A `<Page>` with a `masthead` prop that often contains a [masthead](/components/masthead) or a `<PageHeader>`
 
 The `<MastheadMain>` component includes the smaller area that typically contains the `<MastheadToggle>` and a `<MastheadLogo>`. `<MastheadContent>` represents the main portion of the masthead, and will typically contain a `<Toolbar>` or other menu-like components, like a `<Dropdown>`.
 
 - Mastheads contain a `<MastheadMain>` component, which includes the `<MastheadToggle>`, a `<MastheadLogo>`, and the page's toolbar (via `<MastheadContent>`.) The `<MastheadToggle>` component contains a `<PageToggleButton>`, and the `<MastheadLogo>` component contains a `<MastheadBrand>`.
 - 1 or more `<PageSidebarBody>` components inside `<PageSidebar>` for vertical navigation or other sidebar content
 - 1 or more `<PageSection>` components
 
+### Page header
+
+To use a page header instead of passing a [masthead](/components/masthead) directly, pass a `<PageHeader>` to the `masthead` property. `<PageHeader>` can wrap a `<Masthead>` or custom header content.
+
+```ts file="./PageHeaderContent.tsx"
+
+```
+
 ### Vertical navigation
 
 To add a vertical sidebar to a `<Page>`, pass a `<PageSidebar>` component into the `sidebar` property. To render navigation in the sidebar, pass a `<PageSidebarBody>` component to `<PageSidebar>`.

packages/react-core/src/components/Page/examples/PageHeaderContent.tsx

@@ -0,0 +1,52 @@
+import {
+  Page,
+  PageHeader,
+  Masthead,
+  MastheadMain,
+  MastheadBrand,
+  MastheadLogo,
+  MastheadContent,
+  PageSection,
+  Toolbar,
+  ToolbarContent,
+  ToolbarItem
+} from '@patternfly/react-core';
+
+export const PageHeaderContent: React.FunctionComponent = () => {
+  const headerToolbar = (
+    <Toolbar id="page-header-content-toolbar">
+      <ToolbarContent>
+        <ToolbarItem>header-tools</ToolbarItem>
+      </ToolbarContent>
+    </Toolbar>
+  );
+
+  const pageHeader = (
+    <PageHeader>
+      <Masthead>
+        <MastheadMain>
+          <MastheadBrand>
+            <MastheadLogo href="https://patternfly.org" target="_blank">
+              Logo
+            </MastheadLogo>
+          </MastheadBrand>
+        </MastheadMain>
+        <MastheadContent>{headerToolbar}</MastheadContent>
+      </Masthead>
+    </PageHeader>
+  );
+
+  return (
+    <Page masthead={pageHeader}>
+      <PageSection aria-labelledby="section-1">
+        <h2 id="section-1">Page header example section 1</h2>
+      </PageSection>
+      <PageSection variant="secondary" aria-labelledby="section-2">
+        <h2 id="section-2">Page header example section 2 with secondary variant styling</h2>
+      </PageSection>
+      <PageSection aria-labelledby="section-3">
+        <h2 id="section-3">Page header example section 3</h2>
+      </PageSection>
+    </Page>
+  );
+};

packages/react-core/src/components/Page/index.ts

@@ -2,6 +2,7 @@ export * from './Page';
 export * from './PageBody';
 export * from './PageBreadcrumb';
 export * from './PageGroup';
+export * from './PageHeader';
 export * from './PageSidebar';
 export * from './PageSidebarBody';
 export * from './PageSection';