feat: add secondaryContent to Header

Author: gethinwebster

pages/header/secondary-content.page.tsx

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import { Button, Container, Link, Select, SpaceBetween } from '~components';
+import Header, { HeaderProps } from '~components/header';
+
+import ScreenshotArea from '../utils/screenshot-area';
+
+const variants: HeaderProps.Variant[] = ['h1', 'h2', 'h3', 'awsui-h1-sticky'];
+
+const secondaryContent = (
+  <Select
+    ariaLabel="Time range"
+    selectedOption={{ value: '1h', label: 'Last hour' }}
+    options={[{ value: '1h', label: 'Last hour' }]}
+    onChange={() => {}}
+  />
+);
+
+const actions = (
+  <SpaceBetween direction="horizontal" size="xs">
+    <Button>Refresh</Button>
+    <Button variant="primary">Create resource</Button>
+  </SpaceBetween>
+);
+
+function Row({ variant }: { variant: HeaderProps.Variant }) {
+  return (
+    <SpaceBetween size="m">
+      <Header variant={variant} secondaryContent={secondaryContent}>
+        Title only
+      </Header>
+      <Header variant={variant} secondaryContent={secondaryContent} actions={actions}>
+        With actions
+      </Header>
+      <Header
+        variant={variant}
+        counter="(12)"
+        info={<Link variant="info">Info</Link>}
+        description="A description shown below the title of this header."
+        secondaryContent={secondaryContent}
+        actions={actions}
+      >
+        Counter, info and description
+      </Header>
+      <Header variant={variant} secondaryContent={secondaryContent} actions={actions}>
+        A much longer title that is likely to wrap onto a second line in narrower layouts
+      </Header>
+    </SpaceBetween>
+  );
+}
+
+export default function HeaderSecondaryContentPage() {
+  return (
+    <article>
+      <h1>Header - secondary content</h1>
+      <ScreenshotArea disableAnimations={true}>
+        <SpaceBetween size="xl">
+          {variants.map(variant => (
+            <Container key={variant} header={<Header variant="h3">{`variant="${variant}"`}</Header>}>
+              <Row variant={variant} />
+            </Container>
+          ))}
+          <Container
+            header={
+              <Header variant="h2" secondaryContent={secondaryContent} actions={actions}>
+                As a container header
+              </Header>
+            }
+          >
+            Container content
+          </Container>
+        </SpaceBetween>
+      </ScreenshotArea>
+    </article>
+  );
+}

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

@@ -16319,6 +16319,12 @@ to display resource counters in table and cards components.",
       "isDefault": false,
       "name": "info",
     },
+    {
+      "description": "Content displayed next to the heading, before the actions. For example, a control that
+changes what the section shows.",
+      "isDefault": false,
+      "name": "secondaryContent",
+    },
   ],
   "releaseStatus": "stable",
 }
@@ -43632,6 +43638,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 +55084,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,11 @@ export interface HeaderProps extends BaseComponentProps {
    * Area next to the heading to display an Info link.
    */
   info?: React.ReactNode;
+  /**
+   * Content displayed next to the heading, before the actions. For example, a control that
+   * changes what the section shows.
+   */
+  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,8 +119,16 @@ export default function InternalHeader({
             </InfoLinkLabelContext.Provider>
           )}
         </div>
-        {__additionalTitleContent && (
-          <div className={styles['additional-title-content']}>{__additionalTitleContent}</div>
+        {secondaryContent && (
+          <div
+            className={clsx(
+              styles['secondary-content'],
+              styles[`secondary-content-variant-${variantOverride}`],
+              isRefresh && styles.refresh
+            )}
+          >
+            {secondaryContent}
+          </div>
         )}
         {actions && (
           <div

src/header/styles.scss

@@ -130,13 +130,28 @@
   }
 }
 
-.additional-title-content {
+.secondary-content {
   display: inline-flex;
   align-items: center;
   flex-shrink: 0;
   min-inline-size: 0;
   max-inline-size: 100%;
   margin-inline-end: auto;
+
+  // In classic, mirror the .actions box so content lines up with the heading text the way buttons do.
+  &-variant-h1:not(.refresh),
+  &-variant-h2:not(.refresh),
+  &-variant-h3:not(.refresh) {
+    align-self: flex-start;
+    min-block-size: awsui.$size-vertical-input;
+  }
+  &-variant-h1:not(.refresh) {
+    padding-block: awsui.$space-scaled-xs;
+  }
+  &-variant-h2:not(.refresh),
+  &-variant-h3:not(.refresh) {
+    padding-block: awsui.$space-scaled-xxs;
+  }
 }
 
 .title {
@@ -189,7 +204,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']);
+  }
 }