Dashboard v2: Add SummaryButtonList and SectionHeader components

client/dashboard/app/view-transitions.scss

@@ -31,14 +31,14 @@ main div.dashboard-header-bar {
 }
 
 // Large and small must be separate so they don't cross-animate.
-.dashboard-page-layout.is-large .client-dashboard-components-page-header {
+.dashboard-page-layout.is-large .client-dashboard-components-section-header.is-level-1 {
 	view-transition-name: page-layout-header-large;
 }
-.dashboard-page-layout.is-small .client-dashboard-components-page-header {
+.dashboard-page-layout.is-small .client-dashboard-components-section-header.is-level-1 {
 	view-transition-name: page-layout-header-small;
 }
 
-.dashboard-page-layout.is-large .client-dashboard-components-page-header .components-button.is-primary {
+.dashboard-page-layout.is-large .client-dashboard-components-section-header.is-level-1 .components-button.is-primary {
 	view-transition-name: page-layout-header-large--button;
 }
 

client/dashboard/components/page-header/index.tsx

@@ -1,70 +1,15 @@
-import {
-	__experimentalVStack as VStack,
-	__experimentalHStack as HStack,
-	__experimentalText as Text,
-} from '@wordpress/components';
+import { SectionHeader } from '../section-header';
 import type { PageHeaderProps } from './types';
 
-import './style.scss';
-
 /**
  * The PageHeader component provides a structured introduction to a page or section,
- * combining a title, optional description, and contextual actions. It supports
- * varying levels of hierarchy through semantic heading levels, and can include
+ * combining a title, optional description, and contextual actions. It can include
  * visual decorations, navigational aids like breadcrumbs, and utility controls
  * such as buttons or dropdowns.
  *
- * ```jsx
- * import { PageHeader } from '@automattic/components';
- * import { Button } from '@wordpress/components';
- * import { cog } from '@wordpress/icons';
- *
- * function MyComponent() {
- * 	return (
- * 		<PageHeader
- * 			title="Settings"
- * 			description="Configure your application settings"
- * 			decoration={<Icon icon={cog} />}
- * 			actions={<Button variant="primary">Save Changes</Button>}
- * 		/>
- * 	);
- * }
- * ```
+ * It's a thin wrapper around the SectionHeader component, primarily used for
+ * semantic clarity.
  */
-export const PageHeader = ( {
-	title,
-	description,
-	actions,
-	decoration,
-	breadcrumbs,
-}: PageHeaderProps ) => {
-	return (
-		<VStack spacing={ 2 } className="client-dashboard-components-page-header">
-			{ breadcrumbs }
-			<HStack spacing={ 4 } justify="flex-start" alignment="flex-start">
-				{ decoration && (
-					<span className="client-dashboard-components-page-header__decoration">
-						{ decoration }
-					</span>
-				) }
-				<HStack spacing={ 3 } justify="space-between" alignment="flex-start">
-					<h1 className="client-dashboard-components-page-header__heading">{ title }</h1>
-					{ /* The wrapper is always needed for view transitions. */ }
-					<HStack
-						spacing={ 2 }
-						justify="flex-end"
-						expanded={ false }
-						className="client-dashboard-components-page-header__actions"
-					>
-						{ actions }
-					</HStack>
-				</HStack>
-			</HStack>
-			{ description && (
-				<Text variant="muted" className="client-dashboard-components-page-header__description">
-					{ description }
-				</Text>
-			) }
-		</VStack>
-	);
+export const PageHeader = ( { breadcrumbs, ...rest }: PageHeaderProps ) => {
+	return <SectionHeader level={ 1 } prefix={ breadcrumbs } { ...rest } />;
 };

client/dashboard/components/page-header/test/index.tsx

@@ -3,43 +3,9 @@
  */
 import { Breadcrumbs } from '@automattic/components/src/breadcrumbs';
 import { render, screen } from '@testing-library/react';
-import { Button, Icon } from '@wordpress/components';
-import { cog } from '@wordpress/icons';
 import { PageHeader } from '..';
 
 describe( 'PageHeader', () => {
-	test( 'should render with title', () => {
-		render( <PageHeader title="Test Title" /> );
-		expect( screen.getByRole( 'heading', { name: 'Test Title' } ) ).toBeVisible();
-	} );
-	test( 'should render with description', () => {
-		render( <PageHeader title="Test Title" description="Test Description" /> );
-		expect( screen.getByText( 'Test Description' ) ).toBeVisible();
-	} );
-	test( 'should render with action buttons', () => {
-		render(
-			<PageHeader
-				title="Test Title"
-				actions={
-					<>
-						<Button>Cancel</Button>
-						<Button>Save</Button>
-					</>
-				}
-			/>
-		);
-		expect( screen.getByRole( 'button', { name: 'Cancel' } ) ).toBeVisible();
-		expect( screen.getByRole( 'button', { name: 'Save' } ) ).toBeVisible();
-	} );
-	test( 'should render with decoration', () => {
-		render(
-			<PageHeader
-				title="Test Title"
-				decoration={ <Icon data-testid="decoration" icon={ cog } /> }
-			/>
-		);
-		expect( screen.getByTestId( 'decoration' ) ).toBeVisible();
-	} );
 	test( 'should render with breadcrumbs', () => {
 		render(
 			<PageHeader

client/dashboard/components/page-header/types.ts

@@ -1,25 +1,7 @@
 import React from 'react';
+import { SectionHeaderProps } from '../section-header/types';
 
-export interface PageHeaderProps {
-	/**
-	 * The main heading text that identifies the page or section.
-	 */
-	title: string;
-	/**
-	 * Optional supporting text that provides additional context or
-	 * guidance beneath the title.
-	 */
-	description?: React.ReactNode;
-	/**
-	 * A group of contextual controls, such as buttons, dropdowns,
-	 * or a search input, relevant to the page or section.
-	 */
-	actions?: React.ReactNode;
-	/**
-	 * An optional visual element like an icon or small illustration
-	 * to enhance recognition or provide visual interest.
-	 */
-	decoration?: React.ReactNode;
+export interface PageHeaderProps extends Omit< SectionHeaderProps, 'level' | 'prefix' > {
 	/**
 	 * An optional breadcrumbs component used to indicate the user's current position
 	 * in a complex navigational structure and allow quick access to parent levels.

client/dashboard/components/section-header/index.stories.tsx

@@ -0,0 +1,88 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { Button, Icon, DropdownMenu, MenuGroup, MenuItem } from '@wordpress/components';
+import { help, wordpress, moreVertical } from '@wordpress/icons';
+import { SectionHeader } from './index';
+
+const meta = {
+	title: 'client/dashboard/SectionHeader',
+	component: SectionHeader,
+	tags: [ 'autodocs' ],
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+	},
+} satisfies Meta< typeof SectionHeader >;
+
+export default meta;
+type Story = StoryObj< typeof meta >;
+
+export const Default: Story = {
+	args: {
+		title: 'Settings',
+		description: 'Configure your application settings',
+	},
+};
+
+export const WithActions: Story = {
+	args: {
+		title: 'Site Settings',
+		description: `Manage how your site works and appears. Configure your site's basic functionality,
+				appearance, and behavior. These settings control everything from your site title to how your
+				content is displayed to visitors.`,
+		actions: (
+			<>
+				<Button variant="secondary">Cancel</Button>
+				<Button variant="primary">Save Changes</Button>
+			</>
+		),
+	},
+};
+
+export const ImageDecoration: Story = {
+	args: {
+		title: 'Site Customization',
+		description: 'Make your site look exactly how you want it to',
+		decoration: <img src="https://placecats.com/300/200" alt="Cat" />,
+		actions: (
+			<>
+				<Button variant="secondary">Cancel</Button>
+				<Button variant="primary">Save Changes</Button>
+			</>
+		),
+	},
+};
+
+export const FullExample: Story = {
+	args: {
+		title: 'Site Customization',
+		description: 'Make your site look exactly how you want it to',
+		decoration: <Icon icon={ wordpress } />,
+		actions: (
+			<>
+				<Button icon={ help } variant="tertiary" __next40pxDefaultSize>
+					Help
+				</Button>
+				<Button variant="secondary" __next40pxDefaultSize>
+					Preview
+				</Button>
+				<DropdownMenu
+					icon={ moreVertical }
+					label="More actions"
+					toggleProps={ { __next40pxDefaultSize: true } }
+				>
+					{ () => (
+						<>
+							<MenuGroup>
+								<MenuItem>Import</MenuItem>
+								<MenuItem>Export</MenuItem>
+								<MenuItem>Settings</MenuItem>
+							</MenuGroup>
+							<MenuGroup>
+								<MenuItem>Help</MenuItem>
+							</MenuGroup>
+						</>
+					) }
+				</DropdownMenu>
+			</>
+		),
+	},
+};

client/dashboard/components/section-header/index.tsx

@@ -0,0 +1,59 @@
+import {
+	__experimentalVStack as VStack,
+	__experimentalHStack as HStack,
+	__experimentalText as Text,
+} from '@wordpress/components';
+import type { SectionHeaderProps } from './types';
+
+import './style.scss';
+
+/**
+ * The SectionHeader component provides a consistently structured introduction
+ * to a section of content, combining a title, optional description/decoration,
+ * and contextual actions. It is used to add hierarchy and clarity within page
+ * content or nested in composite components such as SummaryButtonList, or DataFormFields.
+ */
+export const SectionHeader = ( {
+	title,
+	description,
+	actions,
+	decoration,
+	level = 2,
+	prefix,
+}: SectionHeaderProps ) => {
+	const HeadingTag = `h${ level }` as keyof JSX.IntrinsicElements;
+	return (
+		<VStack
+			spacing={ 2 }
+			className={ `client-dashboard-components-section-header is-level-${ level }` }
+		>
+			{ prefix }
+			<HStack spacing={ 4 } justify="flex-start" alignment="flex-start">
+				{ decoration && (
+					<span className="client-dashboard-components-section-header__decoration">
+						{ decoration }
+					</span>
+				) }
+				<HStack spacing={ 3 } justify="space-between" alignment="flex-start">
+					<HeadingTag className="client-dashboard-components-section-header__heading">
+						{ title }
+					</HeadingTag>
+					{ /* The wrapper is always needed for view transitions. */ }
+					<HStack
+						spacing={ 2 }
+						justify="flex-end"
+						expanded={ false }
+						className="client-dashboard-components-section-header__actions"
+					>
+						{ actions }
+					</HStack>
+				</HStack>
+			</HStack>
+			{ description && (
+				<Text variant="muted" className="client-dashboard-components-section-header__description">
+					{ description }
+				</Text>
+			) }
+		</VStack>
+	);
+};