Normalize admin page headers with unified AdminHeader wrapping @wordpress/admin-ui

projects/js-packages/components/changelog/centralize-admin-ui-css-bundling

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Replace admin-ui CSS proxy file with direct import, now that webpack-config handles bundling centrally.

projects/js-packages/components/changelog/pr-47345

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+AdminPage: Remove admin-ui header border via scoped CSS to support unified admin-ui Page layout.

projects/js-packages/components/changelog/pr-47361

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+AdminPage: Remove header border-bottom for a cleaner unified header appearance.

projects/js-packages/components/changelog/pr-47388

@@ -0,0 +1,4 @@
+Significance: patch
+Type: fixed
+
+Admin page: Fix Hello Dolly banner display and clear floats on Jetpack admin pages.

projects/js-packages/components/changelog/update-admin-header-normalization-css-override

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+AdminPage: override admin-ui header position so it's not sticky

projects/js-packages/components/changelog/update-normalize-admin-page-headers

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Add AdminHeader component wrapping @wordpress/admin-ui Page for unified admin page headers.

projects/js-packages/components/components/admin-page/index.tsx

@@ -1,4 +1,10 @@
 import restApi from '@automattic/jetpack-api';
+import { Page } from '@wordpress/admin-ui';
+import '@wordpress/admin-ui/build-style/style.css';
+import {
+	__experimentalHeading as Heading, // eslint-disable-line @wordpress/no-unsafe-wp-apis
+	__experimentalHStack as HStack, // eslint-disable-line @wordpress/no-unsafe-wp-apis
+} from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
 import clsx from 'clsx';
 import { useEffect, useCallback } from 'react';
@@ -21,7 +27,7 @@ import type { FC, ReactNode } from 'react';
 const AdminPage: FC< AdminPageProps > = ( {
 	children,
 	className,
-	moduleName = __( 'Jetpack', 'jetpack-components' ),
+	moduleName = 'Jetpack' /** "Jetpack" is a product name, do not translate. */,
 	moduleNameHref,
 	showHeader = true,
 	showFooter = true,
@@ -32,6 +38,11 @@ const AdminPage: FC< AdminPageProps > = ( {
 	apiNonce = '',
 	optionalMenuItems,
 	header,
+	title,
+	subTitle,
+	logo,
+	actions,
+	tabs,
 } ) => {
 	useEffect( () => {
 		restApi.setApiRoot( apiRoot );
@@ -60,6 +71,55 @@ const AdminPage: FC< AdminPageProps > = ( {
 		}
 	}, [] );
 
+	// Compose the title with logo for the admin-ui Page header.
+	// Note: The inner Heading causes a double h2 wrapping because Page's Header
+	// also wraps title in a Heading. This is a known issue — the inner Heading is
+	// needed until https://github.com/WordPress/gutenberg/pull/75899 fixes
+	// non-string title rendering in admin-ui. Once that lands, remove the Heading
+	// here and pass the plain HStack with a string child.
+	const composedTitle = title ? (
+		<HStack spacing={ 2 } justify="left">
+			{ logo || <JetpackLogo showText={ false } height={ 20 } /> }
+			<Heading as="h2" level={ 3 } weight={ 500 } truncate>
+				{ title }
+			</Heading>
+		</HStack>
+	) : undefined;
+
+	const footer = showFooter && (
+		<Container horizontalSpacing={ 5 }>
+			<Col>
+				<JetpackFooter
+					moduleName={ moduleName }
+					moduleNameHref={ moduleNameHref }
+					menu={ optionalMenuItems }
+					useInternalLinks={ useInternalLinks }
+				/>
+			</Col>
+		</Container>
+	);
+
+	// When title is provided, use admin-ui Page for the full page layout.
+	if ( showHeader && composedTitle ) {
+		return (
+			<div className={ rootClassName }>
+				<Page
+					title={ composedTitle }
+					subTitle={ subTitle }
+					actions={ actions }
+					showSidebarToggle={ false }
+				>
+					{ tabs }
+					<Container fluid horizontalSpacing={ 0 }>
+						<Col>{ children }</Col>
+					</Container>
+					{ footer }
+				</Page>
+			</div>
+		);
+	}
+
+	// Legacy path: no title provided, render the classic header.
 	return (
 		<div className={ rootClassName }>
 			{ showHeader && (
@@ -85,18 +145,7 @@ const AdminPage: FC< AdminPageProps > = ( {
 			<Container fluid horizontalSpacing={ 0 }>
 				<Col>{ children }</Col>
 			</Container>
-			{ showFooter && (
-				<Container horizontalSpacing={ 5 }>
-					<Col>
-						<JetpackFooter
-							moduleName={ moduleName }
-							moduleNameHref={ moduleNameHref }
-							menu={ optionalMenuItems }
-							useInternalLinks={ useInternalLinks }
-						/>
-					</Col>
-				</Container>
-			) }
+			{ footer }
 		</div>
 	);
 };

projects/js-packages/components/components/admin-page/style.module.scss

@@ -9,6 +9,20 @@
 		background-color: var(--jp-white);
 	}
 
+	// Remove the admin-ui header border. Scoped to .admin-page so this only
+	// applies within our component. Ideally admin-ui would expose a prop or
+	// CSS custom property for this — revisit if the upstream API changes.
+	:global(.admin-ui-page__header) {
+		border-bottom: none;
+		position: relative;
+	}
+
+	// Normalize admin headers: implementation of admin-ui needs to
+	// comprehend old wp-admin floating containers, such as Hello Dolly.
+	:global(.admin-ui-page) {
+		clear: both;
+	}
+
 	.admin-page-header {
 		display: flex;
 		align-items: center;
@@ -26,3 +40,8 @@
 		color: #fff;
 	}
 }
+
+// Make Hello Dolly background white for Jetpack admin pages.
+:global(.jetpack-admin-page #dolly) {
+	background-color: #fff;
+}

projects/js-packages/components/components/admin-page/types.ts

@@ -18,10 +18,37 @@ export type AdminPageProps = {
 	showHeader?: boolean;
 
 	/**
-	 * Custom header. Optional
+	 * Custom header. Optional.
+	 * @deprecated Use `title` and `subTitle` props instead for the unified header.
 	 */
 	header?: ReactNode;
 
+	/**
+	 * Product title displayed in the unified header (e.g. "Social", "Backup").
+	 * When provided, renders the admin-ui Page header instead of the legacy header slot.
+	 */
+	title?: string;
+
+	/**
+	 * Optional tagline displayed below the title in the unified header.
+	 */
+	subTitle?: string;
+
+	/**
+	 * Custom logo element for the unified header. Defaults to JetpackLogo icon.
+	 */
+	logo?: ReactNode;
+
+	/**
+	 * Action elements displayed on the right side of the unified header.
+	 */
+	actions?: ReactNode;
+
+	/**
+	 * Tab navigation displayed below the title/tagline in the unified header.
+	 */
+	tabs?: ReactNode;
+
 	/**
 	 * Whether or not to display the Footer
 	 */

projects/js-packages/components/components/jetpack-footer/index.tsx

@@ -33,7 +33,7 @@ const ExternalIcon: FC = () => (
  * @return {ReactNode} JetpackFooter component.
  */
 const JetpackFooter: FC< JetpackFooterProps > = ( {
-	moduleName = __( 'Jetpack', 'jetpack-components' ),
+	moduleName = 'Jetpack' /** "Jetpack" is a product name, do not translate. */,
 	className,
 	moduleNameHref = 'https://jetpack.com',
 	menu,

projects/js-packages/components/package.json

@@ -53,6 +53,7 @@
 		"@automattic/jetpack-script-data": "workspace:*",
 		"@automattic/number-formatters": "workspace:*",
 		"@babel/runtime": "^7",
+		"@wordpress/admin-ui": "1.8.0",
 		"@wordpress/browserslist-config": "6.40.0",
 		"@wordpress/components": "32.2.0",
 		"@wordpress/compose": "7.40.0",

projects/js-packages/components/tools/copy-scss-to-build.mjs

@@ -50,7 +50,7 @@ async function main() {
 		return;
 	}
 
-	for await ( const filePath of fs.glob( '**/*.scss', {
+	for await ( const filePath of fs.glob( '**/*.{scss,css}', {
 		cwd: packageRoot,
 		exclude: Array.from( IGNORED_DIRS, dir => `**/${ dir }/**` ),
 	} ) ) {

projects/js-packages/webpack-config/changelog/centralize-admin-ui-css-bundling

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Centralize admin-ui CSS bundling: add subpath to defaultRequestMap and mark CSS imports as sideEffects to prevent incorrect externalization and tree-shaking.

projects/js-packages/webpack-config/src/webpack.js

@@ -143,6 +143,12 @@ const defaultRequestMap = {
 		external: 'JetpackConnection',
 		handle: 'jetpack-connection',
 	},
+	// Bundle admin-ui CSS with our assets. The JS side is already handled by the
+	// DependencyExtractionPlugin's BUNDLED_PACKAGES list, but the CSS subpath import
+	// doesn't match that exact-match check and would be incorrectly externalized.
+	'@wordpress/admin-ui/build-style/style.css': {
+		external: false,
+	},
 };
 
 const DependencyExtractionPlugin = ( { requestMap, ...options } = {} ) => {

projects/js-packages/webpack-config/src/webpack/css-rule.js

@@ -27,6 +27,9 @@ const CssRule = ( options = {} ) => {
 			'\\.(?:' + exts.map( ext => ext.replace( /[.*+?^${}()|[\]\\]/g, '\\$&' ) ).join( '|' ) + ')$',
 			'i'
 		),
+		// CSS imports are always side effects (they inject styles into the DOM),
+		// so override any package.json "sideEffects: false" declarations.
+		sideEffects: true,
 		use: [
 			MiniCssExtractLoader( options.MiniCssExtractLoader ),
 			CssLoader( {

projects/packages/backup/changelog/update-normalize-backup-admin-header

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Migrate admin page header to use unified AdminHeader component from jetpack-components.