feat(Compass): updated mainheader structure to be composable

thatblindgeye · thatblindgeye · commit 0fec3f9f7d9b · 2025-11-11T08:57:42.000-05:00
diff --git a/packages/react-core/package.json b/packages/react-core/package.json
@@ -54,7 +54,7 @@
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@patternfly/patternfly": "6.5.0-prerelease.19",
+    "@patternfly/patternfly": "6.5.0-prerelease.22",
     "case-anything": "^3.1.2",
     "css": "^3.0.0",
     "fs-extra": "^11.3.0"
diff --git a/packages/react-core/src/components/Compass/CompassHero.tsx b/packages/react-core/src/components/Compass/CompassHero.tsx
@@ -1,15 +1,6 @@
 import styles from '@patternfly/react-styles/css/components/Compass/compass';
 import { css } from '@patternfly/react-styles';
 
-import compassHeroBackgroundImageLight from '@patternfly/react-tokens/dist/esm/c_compass__hero_BackgroundImage_light';
-import compassHeroBackgroundImageDark from '@patternfly/react-tokens/dist/esm/c_compass__hero_BackgroundImage_dark';
-import compassHeroGradientStop1Light from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_1_light';
-import compassHeroGradientStop2Light from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_2_light';
-import compassHeroGradientStop3Light from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_3_light';
-import compassHeroGradientStop1Dark from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_1_dark';
-import compassHeroGradientStop2Dark from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_2_dark';
-import compassHeroGradientStop3Dark from '@patternfly/react-tokens/dist/esm/c_compass__hero_gradient_stop_3_dark';
-
 interface CompassHeroProps extends Omit<React.HTMLProps<HTMLDivElement>, 'content'> {
   /** Content of the hero */
   children?: React.ReactNode;
@@ -33,53 +24,16 @@ interface CompassHeroProps extends Omit<React.HTMLProps<HTMLDivElement>, 'conten
   };
 }
 
-export const CompassHero: React.FunctionComponent<CompassHeroProps> = ({
-  className,
-  children,
-  backgroundSrcLight,
-  backgroundSrcDark,
-  gradientLight,
-  gradientDark,
-  ...props
-}) => {
+export const CompassHero: React.FunctionComponent<CompassHeroProps> = ({ className, children, ...props }) => {
   const backgroundImageStyles: { [key: string]: string } = {};
-  if (backgroundSrcLight) {
-    backgroundImageStyles[compassHeroBackgroundImageLight.name] = `url(${backgroundSrcLight})`;
-  }
-  if (backgroundSrcDark) {
-    backgroundImageStyles[compassHeroBackgroundImageDark.name] = `url(${backgroundSrcDark})`;
-  }
-
-  if (gradientLight) {
-    if (gradientLight.stop1) {
-      backgroundImageStyles[compassHeroGradientStop1Light.name] = gradientLight.stop1;
-    }
-    if (gradientLight.stop2) {
-      backgroundImageStyles[compassHeroGradientStop2Light.name] = gradientLight.stop2;
-    }
-    if (gradientLight.stop3) {
-      backgroundImageStyles[compassHeroGradientStop3Light.name] = gradientLight.stop3;
-    }
-  }
-  if (gradientDark) {
-    if (gradientDark.stop1) {
-      backgroundImageStyles[compassHeroGradientStop1Dark.name] = gradientDark.stop1;
-    }
-    if (gradientDark.stop2) {
-      backgroundImageStyles[compassHeroGradientStop2Dark.name] = gradientDark.stop2;
-    }
-    if (gradientDark.stop3) {
-      backgroundImageStyles[compassHeroGradientStop3Dark.name] = gradientDark.stop3;
-    }
-  }
 
   return (
     <div
-      className={css(styles.compassPanel, styles.compassHero, className)}
+      className={css(styles.compassPanel, className)}
       style={{ ...props.style, ...backgroundImageStyles }}
       {...props}
     >
-      <div className={css(styles.compassHeroBody)}>{children}</div>
+      <div className={css()}>{children}</div>
     </div>
   );
 };
diff --git a/packages/react-core/src/components/Compass/CompassMainHeader.tsx b/packages/react-core/src/components/Compass/CompassMainHeader.tsx
@@ -1,33 +1,41 @@
-import { Flex, FlexItem } from '../../layouts/Flex';
-import { CompassPanel } from './CompassPanel';
+import { CompassPanel, CompassPanelProps } from './CompassPanel';
 import styles from '@patternfly/react-styles/css/components/Compass/compass';
 import { css } from '@patternfly/react-styles';
 
+/** The wrapper component for header content in the main compass area. When building out a custom implementation,
+ * you should ensure any content within the main header is rendered inside a compass panel and main header content wrappers.
+ */
+
 interface CompassMainHeaderProps extends Omit<React.HTMLProps<HTMLDivElement>, 'title'> {
+  /** Custom main header content. To opt into a default styling, use the title and toolbar props instead. */
+  children?: React.ReactNode;
   /** Additional classes added to the main header */
   className?: string;
   /** Styled title. If title or toolbar is provided, the children will be ignored. */
   title?: React.ReactNode;
   /** Styled toolbar. If title or toolbar is provided, the children will be ignored. */
   toolbar?: React.ReactNode;
-  /** Custom main header content. To opt into a default styling, use the title and toolbar props instead. */
-  children?: React.ReactNode;
+  /** Additional props passed to the compass panel that wraps the main header content when using the title or toolbar props. When using the
+   * children prop, you should pass your own compass panel.
+   */
+  compassPanelProps?: Omit<CompassPanelProps, 'children'>;
 }
 
 export const CompassMainHeader: React.FunctionComponent<CompassMainHeaderProps> = ({
   className,
   title,
   toolbar,
   children,
+  compassPanelProps,
   ...props
 }) => {
   const _content =
     title !== undefined || toolbar !== undefined ? (
-      <CompassPanel>
-        <Flex alignItems={{ default: 'alignItemsCenter' }}>
-          <FlexItem grow={{ default: 'grow' }}>{title}</FlexItem>
-          {toolbar && <FlexItem>{toolbar}</FlexItem>}
-        </Flex>
+      <CompassPanel {...compassPanelProps}>
+        <div className={css(`${styles.compass}__main-header-content`)}>
+          {title && <div className={css(`${styles.compass}__main-header-title`)}>{title}</div>}
+          {toolbar && <div className={css(`${styles.compass}__main-header-toolbar`)}>{toolbar}</div>}
+        </div>
       </CompassPanel>
     ) : (
       children
diff --git a/packages/react-core/src/components/Compass/CompassMainHeaderContent.tsx b/packages/react-core/src/components/Compass/CompassMainHeaderContent.tsx
@@ -0,0 +1,25 @@
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+import { css } from '@patternfly/react-styles';
+
+/** A wrapper component to be passed as custom content for the compass main header. This should also be wrapped
+ * in a compass panel component.
+ */
+
+export interface CompassMainHeaderContentProps extends React.HTMLProps<HTMLDivElement> {
+  /** Content of the main header content. */
+  children: React.ReactNode;
+  /** Additional classes added to the main header content. */
+  className?: string;
+}
+
+export const CompassMainHeaderContent: React.FunctionComponent<CompassMainHeaderContentProps> = ({
+  children,
+  className,
+  ...props
+}) => (
+  <div className={css(styles.compassMainHeaderContent, className)} {...props}>
+    {children}
+  </div>
+);
+
+CompassMainHeaderContent.displayName = 'CompassMainHeaderContent';
diff --git a/packages/react-core/src/components/Compass/CompassMainHeaderTitle.tsx b/packages/react-core/src/components/Compass/CompassMainHeaderTitle.tsx
@@ -0,0 +1,25 @@
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+import { css } from '@patternfly/react-styles';
+
+/** A wrapper component for custom title content to be passed into a compass main header. This should also be wrapped
+ * by a compass main header content component.
+ */
+
+export interface CompassMainHeaderTitleProps extends React.HTMLProps<HTMLDivElement> {
+  /** Content of the main header title. */
+  children: React.ReactNode;
+  /** Additional classes added to the main header title. */
+  className?: string;
+}
+
+export const CompassMainHeaderTitle: React.FunctionComponent<CompassMainHeaderTitleProps> = ({
+  children,
+  className,
+  ...props
+}) => (
+  <div className={css(`${styles.compass}__main-header-title`, className)} {...props}>
+    {children}
+  </div>
+);
+
+CompassMainHeaderTitle.displayName = 'CompassMainHeaderTitle';
diff --git a/packages/react-core/src/components/Compass/CompassMainHeaderToolbar.tsx b/packages/react-core/src/components/Compass/CompassMainHeaderToolbar.tsx
@@ -0,0 +1,25 @@
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+import { css } from '@patternfly/react-styles';
+
+/** A wrapper component for custom toolbar content to be passed into a compass main header. This should also be wrapped
+ * by a compass main header content component.
+ */
+
+export interface CompassMainHeaderToolbarProps extends React.HTMLProps<HTMLDivElement> {
+  /** Content of the main header toolbar. */
+  children: React.ReactNode;
+  /** Additional classes added to the main header toolbar. */
+  className?: string;
+}
+
+export const CompassMainHeaderToolbar: React.FunctionComponent<CompassMainHeaderToolbarProps> = ({
+  children,
+  className,
+  ...props
+}) => (
+  <div className={css(`${styles.compass}__main-header-toolbar`, className)} {...props}>
+    {children}
+  </div>
+);
+
+CompassMainHeaderToolbar.displayName = 'CompassMainHeaderToolbar';
diff --git a/packages/react-core/src/components/Compass/CompassPanel.tsx b/packages/react-core/src/components/Compass/CompassPanel.tsx
@@ -1,7 +1,7 @@
 import styles from '@patternfly/react-styles/css/components/Compass/compass';
 import { css } from '@patternfly/react-styles';
 
-interface CompassPanelProps extends React.HTMLProps<HTMLDivElement> {
+export interface CompassPanelProps extends React.HTMLProps<HTMLDivElement> {
   /** Content of the panel. */
   children: React.ReactNode;
   /** Additional classes added to the panel. */
diff --git a/packages/react-core/src/components/Compass/__tests__/CompassMainHeader.test.tsx b/packages/react-core/src/components/Compass/__tests__/CompassMainHeader.test.tsx
@@ -75,8 +75,8 @@ test('Renders children when neither title nor toolbar are provided', () => {
 });
 
 test('Renders with additional props spread to the component', () => {
-  render(<CompassMainHeader aria-label="Test label">Test</CompassMainHeader>);
-  expect(screen.getByText('Test')).toHaveAccessibleName('Test label');
+  render(<CompassMainHeader id="custom-id">Test</CompassMainHeader>);
+  expect(screen.getByText('Test')).toHaveAttribute('id', 'custom-id');
 });
 
 test('Matches the snapshot with both title and toolbar', () => {
diff --git a/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderContent.test.tsx b/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderContent.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react';
+import { CompassMainHeaderContent } from '../CompassMainHeaderContent';
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+
+test('Renders with children', () => {
+  render(<CompassMainHeaderContent>Custom content</CompassMainHeaderContent>);
+  expect(screen.getByText('Custom content')).toBeVisible();
+});
+
+test(`Renders with default ${styles.compass}__main-header-content class`, () => {
+  render(<CompassMainHeaderContent>Test</CompassMainHeaderContent>);
+  expect(screen.getByText('Test')).toHaveClass(`${styles.compass}__main-header-content`);
+});
+
+test('Renders with custom class name when className prop is provided', () => {
+  render(<CompassMainHeaderContent className="custom-class">Test</CompassMainHeaderContent>);
+  expect(screen.getByText('Test')).toHaveClass('custom-class');
+});
+
+test('Renders with additional props spread to the component', () => {
+  render(<CompassMainHeaderContent id="custom-id">Test</CompassMainHeaderContent>);
+  expect(screen.getByText('Test')).toHaveAttribute('id', 'custom-id');
+});
+
+test('Matches the snapshot', () => {
+  const { asFragment } = render(<CompassMainHeaderContent>Content</CompassMainHeaderContent>);
+  expect(asFragment()).toMatchSnapshot();
+});
diff --git a/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderTitle.test.tsx b/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderTitle.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react';
+import { CompassMainHeaderTitle } from '../CompassMainHeaderTitle';
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+
+test('Renders with children', () => {
+  render(<CompassMainHeaderTitle>Custom content</CompassMainHeaderTitle>);
+  expect(screen.getByText('Custom content')).toBeVisible();
+});
+
+test(`Renders with default ${styles.compass}__main-header-title class`, () => {
+  render(<CompassMainHeaderTitle>Test</CompassMainHeaderTitle>);
+  expect(screen.getByText('Test')).toHaveClass(`${styles.compass}__main-header-title`);
+});
+
+test('Renders with custom class name when className prop is provided', () => {
+  render(<CompassMainHeaderTitle className="custom-class">Test</CompassMainHeaderTitle>);
+  expect(screen.getByText('Test')).toHaveClass('custom-class');
+});
+
+test('Renders with additional props spread to the component', () => {
+  render(<CompassMainHeaderTitle id="custom-id">Test</CompassMainHeaderTitle>);
+  expect(screen.getByText('Test')).toHaveAttribute('id', 'custom-id');
+});
+
+test('Matches the snapshot', () => {
+  const { asFragment } = render(<CompassMainHeaderTitle>Content</CompassMainHeaderTitle>);
+  expect(asFragment()).toMatchSnapshot();
+});
diff --git a/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderToolbar.test.tsx b/packages/react-core/src/components/Compass/__tests__/CompassMainHeaderToolbar.test.tsx
@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react';
+import { CompassMainHeaderToolbar } from '../CompassMainHeaderToolbar';
+import styles from '@patternfly/react-styles/css/components/Compass/compass';
+
+test('Renders with children', () => {
+  render(<CompassMainHeaderToolbar>Custom content</CompassMainHeaderToolbar>);
+  expect(screen.getByText('Custom content')).toBeVisible();
+});
+
+test(`Renders with default ${styles.compass}__main-header-toolbar class`, () => {
+  render(<CompassMainHeaderToolbar>Test</CompassMainHeaderToolbar>);
+  expect(screen.getByText('Test')).toHaveClass(`${styles.compass}__main-header-toolbar`);
+});
+
+test('Renders with custom class name when className prop is provided', () => {
+  render(<CompassMainHeaderToolbar className="custom-class">Test</CompassMainHeaderToolbar>);
+  expect(screen.getByText('Test')).toHaveClass('custom-class');
+});
+
+test('Renders with additional props spread to the component', () => {
+  render(<CompassMainHeaderToolbar id="custom-id">Test</CompassMainHeaderToolbar>);
+  expect(screen.getByText('Test')).toHaveAttribute('id', 'custom-id');
+});
+
+test('Matches the snapshot', () => {
+  const { asFragment } = render(<CompassMainHeaderToolbar>Content</CompassMainHeaderToolbar>);
+  expect(asFragment()).toMatchSnapshot();
+});
diff --git a/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeader.test.tsx.snap b/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeader.test.tsx.snap
@@ -9,17 +9,17 @@ exports[`Matches the snapshot with both title and toolbar 1`] = `
       class="pf-v6-c-compass__panel"
     >
       <div
-        class="pf-v6-l-flex pf-m-align-items-center"
+        class="pf-v6-c-compass__main-header-content"
       >
         <div
-          class="pf-m-grow"
+          class="pf-v6-c-compass__main-header-title"
         >
           <div>
             Title
           </div>
         </div>
         <div
-          class=""
+          class="pf-v6-c-compass__main-header-toolbar"
         >
           <div>
             Toolbar
diff --git a/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderContent.test.tsx.snap b/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderContent.test.tsx.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Matches the snapshot 1`] = `
+<DocumentFragment>
+  <div
+    class="pf-v6-c-compass__main-header-content"
+  >
+    Content
+  </div>
+</DocumentFragment>
+`;
diff --git a/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderTitle.test.tsx.snap b/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderTitle.test.tsx.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Matches the snapshot 1`] = `
+<DocumentFragment>
+  <div
+    class="pf-v6-c-compass__main-header-title"
+  >
+    Content
+  </div>
+</DocumentFragment>
+`;
diff --git a/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderToolbar.test.tsx.snap b/packages/react-core/src/components/Compass/__tests__/__snapshots__/CompassMainHeaderToolbar.test.tsx.snap
@@ -0,0 +1,11 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Matches the snapshot 1`] = `
+<DocumentFragment>
+  <div
+    class="pf-v6-c-compass__main-header-toolbar"
+  >
+    Content
+  </div>
+</DocumentFragment>
+`;
diff --git a/packages/react-core/src/components/Compass/examples/Compass.md b/packages/react-core/src/components/Compass/examples/Compass.md
@@ -46,3 +46,21 @@ The background image of the `Compass` and `CompassHero` may be customized by usi
 ```ts isFullscreen file="CompassDemo.tsx"
 
 ```
+
+## Composable structure
+
+When building a more custom implementation using Compass components, there are some intended or expected structures that must be present.
+
+### CompassMainHeader structure
+
+When using the `children` property in the `<CompassMainHeader>` component, you should ensure that the expected sub-components are used. The following code block shows a general structure to follow.
+
+```noLive
+<CompassMainHeader>
+  <CompassPanel>
+    <CompassMainHeaderContent>
+      {Your custom content goes here, which can include the CompassMainHeaderTitle and/or CompassMainHeaderToolbar sub-components}
+    </CompassMainHeaderContent>
+  </CompassPanel>
+</CompassMainHeader>
+```
diff --git a/packages/react-core/src/components/Compass/examples/CompassBasic.tsx b/packages/react-core/src/components/Compass/examples/CompassBasic.tsx
diff --git a/packages/react-core/src/components/Compass/index.ts b/packages/react-core/src/components/Compass/index.ts
diff --git a/packages/react-docs/package.json b/packages/react-docs/package.json
diff --git a/packages/react-icons/package.json b/packages/react-icons/package.json
diff --git a/packages/react-styles/package.json b/packages/react-styles/package.json
diff --git a/packages/react-tokens/package.json b/packages/react-tokens/package.json
diff --git a/yarn.lock b/yarn.lock
