feat: add secondaryContent to Header

Author: gethinwebster

pages/header/permutations.page.tsx

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import React from 'react';
 
-import { Button, Link, Spinner } from '~components';
+import { Button, Link, Select, Spinner } from '~components';
 import Header, { HeaderProps } from '~components/header';
 
 import createPermutations from '../utils/permutations';
@@ -30,6 +30,29 @@ const permutations = createPermutations<HeaderProps>([
       null,
     ],
   },
+  {
+    variant: ['h1', 'h2', 'h3'],
+    secondaryContent: [
+      <Select
+        key="select"
+        ariaLabel="Time range"
+        selectedOption={{ value: '1h', label: 'Last hour' }}
+        options={[{ value: '1h', label: 'Last hour' }]}
+        onChange={() => {}}
+      />,
+    ],
+    counter: ['(1/10)', undefined],
+    description: [
+      'A description text with some content to simulate a text shown below the title of this header.',
+      null,
+    ],
+    actions: [
+      <Button key="button" variant="primary">
+        Create Resource
+      </Button>,
+      null,
+    ],
+  },
 ]);
 
 export default function HeaderPermutations() {

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -16319,6 +16319,11 @@ to display resource counters in table and cards components.",
       "isDefault": false,
       "name": "info",
     },
+    {
+      "description": "Secondary content displayed next to the header text.",
+      "isDefault": false,
+      "name": "secondaryContent",
+    },
   ],
   "releaseStatus": "stable",
 }
@@ -43632,6 +43637,19 @@ The dismiss button is only rendered when the \`dismissible\` property is set to
             ],
           },
         },
+        {
+          "name": "findSecondaryContent",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "ElementWrapper",
+            "typeArguments": [
+              {
+                "name": "HTMLElement",
+              },
+            ],
+          },
+        },
       ],
       "name": "HeaderWrapper",
     },
@@ -55065,6 +55083,14 @@ The dismiss button is only rendered when the \`dismissible\` property is set to
             "name": "ElementWrapper",
           },
         },
+        {
+          "name": "findSecondaryContent",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "ElementWrapper",
+          },
+        },
       ],
       "name": "HeaderWrapper",
     },

src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap

@@ -378,6 +378,7 @@ exports[`test-utils selectors 1`] = `
     "awsui_heading-text_2qdw9",
     "awsui_info_2qdw9",
     "awsui_root_2qdw9",
+    "awsui_secondary-content_2qdw9",
   ],
   "help-panel": [
     "awsui_content_1d237",

src/expandable-section/expandable-section-header.tsx

@@ -410,7 +410,7 @@ const ExpandableHeaderTextWrapper = ({
             actions={actions}
             headingTagOverride={hideText ? 'div' : headingTagOverride}
             __inExpandableSection={true}
-            __additionalTitleContent={secondaryContent ? <span id={describedById}>{secondaryContent}</span> : undefined}
+            secondaryContent={secondaryContent ? <span id={describedById}>{secondaryContent}</span> : undefined}
           >
             {headerButton}
           </InternalHeader>

src/header/__tests__/header.test.tsx

@@ -42,6 +42,37 @@ test('renders everything provided', () => {
   expect(wrapper.findActions()!.find('button')!.getElement()).toHaveTextContent('Click me');
 });
 
+describe('secondary content', () => {
+  test('is not rendered by default', () => {
+    const { wrapper } = renderHeader(<Header>Test title</Header>);
+    expect(wrapper.findSecondaryContent()).toBeNull();
+  });
+
+  test.each(['h1', 'h2', 'h3', 'awsui-h1-sticky'] as const)('renders outside the heading element for %s', variant => {
+    const { wrapper } = renderHeader(
+      <Header variant={variant} secondaryContent={<button>Filter</button>}>
+        Test title
+      </Header>
+    );
+    const secondaryContent = wrapper.findSecondaryContent()!.getElement();
+    expect(secondaryContent).toHaveTextContent('Filter');
+    expect(secondaryContent.closest('h1,h2,h3,h4,h5,h6')).toBeNull();
+  });
+
+  test('renders between the title and the actions', () => {
+    const { wrapper } = renderHeader(
+      <Header info="Info" secondaryContent={<button>Filter</button>} actions={<button>Create</button>}>
+        Test title
+      </Header>
+    );
+    const info = wrapper.findInfo()!.getElement();
+    const secondaryContent = wrapper.findSecondaryContent()!.getElement();
+    const actions = wrapper.findActions()!.getElement();
+    expect(info.compareDocumentPosition(secondaryContent) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    expect(secondaryContent.compareDocumentPosition(actions) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+});
+
 test('renders arbitrary counter content', () => {
   const { wrapper } = renderHeader(<Header counter={<Spinner />} />);
   expect(wrapper.findCounter()).not.toBeNull();

src/header/interfaces.ts

@@ -43,6 +43,10 @@ export interface HeaderProps extends BaseComponentProps {
    * Area next to the heading to display an Info link.
    */
   info?: React.ReactNode;
+  /**
+   * Secondary content displayed next to the header text.
+   */
+  secondaryContent?: React.ReactNode;
 }
 
 export namespace HeaderProps {

src/header/internal.tsx

@@ -27,11 +27,6 @@ interface InternalHeaderProps extends SomeRequired<HeaderProps, 'variant'>, Inte
   __headingTagRef?: MutableRefObject<HTMLHeadingElement | null>;
   __headingTagTabIndex?: number;
   __inExpandableSection?: boolean;
-  /**
-   * Rendered in the title row but outside the heading tag, so content beside the title is not
-   * nested inside the heading element.
-   */
-  __additionalTitleContent?: React.ReactNode;
 }
 
 export default function InternalHeader({
@@ -42,12 +37,12 @@ export default function InternalHeader({
   counter,
   description,
   info,
+  secondaryContent,
   __internalRootRef,
   __disableActionsWrapping,
   __headingTagRef,
   __headingTagTabIndex,
   __inExpandableSection,
-  __additionalTitleContent,
   ...restProps
 }: InternalHeaderProps) {
   const isMobile = useMobile();
@@ -124,9 +119,7 @@ export default function InternalHeader({
             </InfoLinkLabelContext.Provider>
           )}
         </div>
-        {__additionalTitleContent && (
-          <div className={styles['additional-title-content']}>{__additionalTitleContent}</div>
-        )}
+        {secondaryContent && <div className={styles['secondary-content']}>{secondaryContent}</div>}
         {actions && (
           <div
             className={clsx(

src/header/styles.scss

@@ -130,7 +130,7 @@
   }
 }
 
-.additional-title-content {
+.secondary-content {
   display: inline-flex;
   align-items: center;
   flex-shrink: 0;
@@ -189,7 +189,7 @@
 
 // With secondary content beside the heading, center both against a constant-height line so their
 // alignment no longer shifts when actions wrap to a second row.
-.main:has(> .additional-title-content) > .title-variant-h2.title-in-expandable-section.refresh {
+.main:has(> .secondary-content) > .title-variant-h2.title-in-expandable-section.refresh {
   padding-block-start: 0;
   min-block-size: awsui.$size-vertical-input;
   display: flex;

src/test-utils/dom/header/index.ts

@@ -26,4 +26,8 @@ export default class HeaderWrapper extends ComponentWrapper {
   findActions(): ElementWrapper | null {
     return this.findByClassName(styles.actions);
   }
+
+  findSecondaryContent(): ElementWrapper | null {
+    return this.findByClassName(styles['secondary-content']);
+  }
 }