Admin pages: unify layout under jetpack-admin-page-layout mixin (#48109)

* base-styles: Add jetpack-admin-page-layout mixin

Introduces @automattic/jetpack-base-styles/admin-page-layout, a SCSS mixin
that standardizes Jetpack wp-admin pages: a viewport-pinned content column
with the Jetpack header pinned at the top, a middle that scrolls internally,
and JetpackFooter pinned at the bottom. No window-level scroll.

Key mechanics:

- Override WP core's "#wpbody-content { width: 100% }" (common.css) with
  "width: auto" so position: fixed + left + right: 0 can size the column
  correctly. Without this, width: 100% resolves to 100vw under fixed
  positioning and pushes the column past the viewport.
- Honor the .folded body class unconditionally (user's persistent
  "Collapse menu" preference) and gate .auto-fold to (max-width: 960px),
  mirroring WP's own wp-admin.css scoping. This keeps a stale auto-fold
  class from mis-offsetting the column after a narrow to wide viewport
  resize.
- The mobile media query matches #wpbody-content, .folded #wpbody-content,
  and .auto-fold #wpbody-content explicitly so "left: 0" wins via
  equal-specificity source order over the desktop fold rules.
- Sidebar widths and viewport breakpoints live in SCSS variables; the
  admin-bar height stays as var(--wp-admin-bar-height, default) to keep
  the documented runtime-override path open.

Exports the mixin via package.json so consumers can

    @use "@automattic/jetpack-base-styles/admin-page-layout" as *;

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* jetpack-components: Add stable jp-admin-page class to AdminPage

Adds "jp-admin-page" as a second, non-CSS-Modules-hashed className on
the AdminPage root in addition to the existing hashed styles["admin-page"]
token. This gives global stylesheets and shared mixins (notably
jetpack-admin-page-layout from @automattic/jetpack-base-styles) a stable
selector to target without coupling to the hashed module name.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Protect: Adopt jetpack-admin-page-layout mixin

Scopes the shared admin-page layout to body.jetpack_page_jetpack-protect
so Protect uses the standard header-pinned / middle-scrolling /
footer-pinned layout. No other visual changes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Publicize: Adopt jetpack-admin-page-layout mixin

Scopes the shared admin-page layout to body.jetpack_page_jetpack-social
(the Social menu page is served by the Publicize package) so Social uses
the standard header-pinned / middle-scrolling / footer-pinned layout.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* VideoPress: Adopt jetpack-admin-page-layout mixin

Scopes the shared admin-page layout to body.jetpack_page_jetpack-videopress.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Backup: Adopt jetpack-admin-page-layout mixin

Scopes the shared admin-page layout to body.jetpack_page_jetpack-backup.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Newsletter: Adopt jetpack-admin-page-layout mixin

Adds @automattic/jetpack-base-styles as a workspace dep and scopes the
shared admin-page layout to body.jetpack_page_jetpack-newsletter. Keeps
the existing dataviews imports in place.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Search: Drop inline JetpackFooter, adopt jetpack-admin-page-layout mixin

Search rendered JetpackFooter twice: once via AdminPage's built-in slot,
once as a sibling inside the dashboard. It suppressed the built-in slot
with showFooter={false}, which conflicted with the shared mixin's
footer-pinning rules.

Drops the showFooter={false} flag and the inline <JetpackFooter /> so
the footer lives inside AdminPage's flex column where the mixin can pin
it. Adds dashboard/scss/admin-layout.scss to scope the mixin to
body.jetpack_page_jetpack-search and imports it from dashboard/index.jsx.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Boost: Drop inline JetpackFooters, adopt jetpack-admin-page-layout mixin

Boost rendered JetpackFooter directly inside each page (BoostAdminPage,
card-page, settings-page, cache-debug-log, getting-started) and
suppressed AdminPage's built-in footer with showFooter={false}. That
left the footer outside AdminPage's flex column, so the shared mixin
could not pin it.

Drops the inline <JetpackFooter /> imports/renders and removes
showFooter={false} so the footer lives inside AdminPage where the mixin
pins it. Adds the body.jetpack_page_jetpack-boost scope in
admin-style.scss.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Jetpack: Adopt jetpack-admin-page-layout mixin for network admin

Scopes the shared admin-page layout to both network-admin body classes:

  toplevel_page_jetpack-network-sites    (Sites, the default view)
  jp-network_page_jetpack-network-settings   (Settings submenu)

Both share #jp-network-admin-root and branch on data-page.

The Settings class prefix is derived from the menu *title* ("JP Network")
sanitized to "jp-network", so it does NOT follow the usual
"toplevel_page_*" convention — see the
admin_print_scripts-jp-network_page_jetpack-network-settings hook in
tools/docker/mu-plugins/0-sandbox.php for the canonical reference.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* changelog: Add entries for admin-page-layout work

Covers all ten projects touched by the admin-page-layout mixin
introduction and per-page adoption:

- base-styles     (new public mixin + export — minor, added)
- components      (AdminPage stable class — patch, changed)
- protect         (patch, changed)
- publicize       (patch, changed)
- videopress      (patch, changed)
- backup          (patch, changed)
- newsletter      (patch, changed; also adds workspace dep)
- search          (patch, changed; drops inline footer)
- boost           (patch, changed; drops inline footers)
- jetpack         (patch, enhancement — network admin)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: CGastrell

pnpm-lock.yaml

@@ -0,0 +1,196 @@
+// Jetpack admin-page layout mixin.
+
+// Standardizes the layout of a Jetpack wp-admin page so <AdminPage> controls
+// the full content area: fixed Jetpack header at the top, the middle section
+// scrolls internally, JetpackFooter pinned at the bottom. No window-level
+// scroll; nothing leaks outside the scope.
+
+// Usage:
+
+//   @use "@automattic/jetpack-base-styles/admin-page-layout" as *;
+//   :global {
+//     body.jetpack_page_my-jetpack { @include jetpack-admin-page-layout; }
+//   }
+
+// Selector hooks this mixin relies on (all stable, not CSS-Modules hashed):
+
+//   wp-admin shell:          #wpcontent, #wpbody-content, #wpfooter
+//   <AdminPage> root:        .jp-admin-page   (added unconditionally by the
+//                                              <AdminPage> component from
+//                                              @automattic/jetpack-components)
+//   @wordpress/admin-ui:     .admin-ui-page, .admin-ui-page__header
+//   <JetpackFooter>:         .jetpack-footer
+
+// Implementation note — `postcss-custom-properties` with `preserve: false`:
+// several consumer packages in this monorepo (publicize, videopress, search,
+// jetpack plugin) resolve `var()` to its fallback at build time. That rules
+// out *runtime-toggled* custom properties (you can't use a CSS var to flip
+// `<AdminPage>`'s margin between the legacy and the new layout, because the
+// fallback wins before the override can reach it). It does NOT rule out
+// `var(--name, <fallback>)` used purely for readability and forward-
+// compatibility on size values — the compiled output is identical to
+// inlining the fallback. This mixin uses `var(--wp-admin-bar-height, …)`
+// (mirroring `projects/packages/forms/src/dashboard/inbox/style.scss`) so
+// the intent stays legible, and so packages that don't run the `preserve:
+// false` plugin can override the var at runtime. Immutable sizes (sidebar
+// widths, viewport breakpoints) use SCSS variables — they can't change at
+// runtime and there's no need to pay the custom-property indirection.
+
+// wp-admin chrome constants (see wp-admin.css).
+$jp-sidebar-width-expanded: 160px;     // default sidebar
+$jp-sidebar-width-folded: 36px;        // .folded preference OR .auto-fold class
+$jp-admin-bar-height-desktop: 32px;
+$jp-admin-bar-height-mobile: 46px;
+
+// Viewport breakpoints WP itself uses:
+//   ≤ 960px → WP toggles `.auto-fold` on <body>, narrows the sidebar to 36px
+//   ≤ 782px → sidebar goes off-canvas (0) regardless of .folded/.auto-fold
+// We mirror these breakpoints because WP's body-class state is not always
+// in sync with the rendered viewport (the `auto-fold` class can stay stale
+// after a narrow → wide window resize).
+$jp-breakpoint-auto-fold: 960px;
+$jp-breakpoint-mobile: 782px;
+
+@mixin jetpack-admin-page-layout {
+	// ── wp-admin chrome resets ────────────────────────────────────────
+	#wpcontent {
+		padding-left: 0;
+	}
+
+	// wp-admin's footer floats at the very bottom via `position: absolute`;
+	// we replace it with a pinned JetpackFooter inside the scope.
+	#wpfooter {
+		display: none;
+	}
+
+	// ── Viewport-pinned content column ────────────────────────────────
+	// `position: fixed` pins the content column to the viewport. The
+	// sidebar (`#adminmenumain`) is left untouched — it can grow past
+	// viewport; the window will scroll for it without disturbing the
+	// fixed content column. This is the pattern Calypso adopted in
+	// wp-calypso#109899 for its own admin pages.
+
+	// We intentionally do NOT constrain `#adminmenuwrap` with
+	// `overflow-y: auto` here: any overflow on a sidebar ancestor clips
+	// the absolutely-positioned `.wp-submenu` flyouts that appear on
+	// hover in both folded AND expanded modes (for parent menus whose
+	// submenu isn't auto-expanded). Letting the window scroll for a tall
+	// sidebar is the acceptable tradeoff.
+	#wpbody-content {
+		box-sizing: border-box;
+		position: fixed;
+		top: var(--wp-admin-bar-height, #{$jp-admin-bar-height-desktop});
+		left: $jp-sidebar-width-expanded;
+		right: 0;
+		bottom: 0;
+		// wp-admin core sets `width: 100%` on #wpbody-content (common.css).
+		// With `position: fixed`, that resolves to 100% of the viewport and
+		// overrides `right: 0`, making the column extend past the viewport
+		// by the sidebar width. `width: auto` lets left+right size it.
+		width: auto;
+		padding-bottom: 0;          // wp-admin default is 65px (clears #wpfooter).
+		overflow: hidden;
+		display: flex;
+		flex-direction: column;
+	}
+
+	// `.folded` is the user's persistent "Collapse menu" preference; WP
+	// keeps it set at every viewport width, so we match it unconditionally.
+	&.folded #wpbody-content {
+		left: $jp-sidebar-width-folded;
+	}
+
+	// `.auto-fold` is WP JS state, gated to narrow-desktop widths. Scope
+	// our match to the same media range WP uses in wp-admin.css, otherwise
+	// a stale `.auto-fold` class (WP doesn't always remove it on resize)
+	// would mis-offset the column at wide viewports where the sidebar has
+	// rebounded to 160px.
+	@media (max-width: #{$jp-breakpoint-auto-fold}) {
+
+		&.auto-fold #wpbody-content {
+			left: $jp-sidebar-width-folded;
+		}
+	}
+
+	// Every ancestor of <AdminPage> inside #wpbody-content must participate
+	// in the flex chain, or the column collapses at the first non-flex
+	// wrapper. Some pages mount their React tree with an extra wrapper in
+	// between (e.g. ThemeProvider from @automattic/jetpack-components adds
+	// a `display: block` div); `:has()` targets the whole chain regardless
+	// of depth. `min-width: 0` + `min-height: 0` let flex items shrink on
+	// both axes (defaults to content size which can cause overflow).
+	#wpbody-content :has(.jp-admin-page) {
+		flex: 1 1 auto;
+		min-height: 0;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+	}
+
+	// ── <AdminPage> root ──────────────────────────────────────────────
+	// Neutralize the legacy -20px shift and make AdminPage a flex child
+	// that fills its parent column.
+	.jp-admin-page {
+		margin-left: 0;
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 auto;
+		min-height: 0;
+		min-width: 0;
+	}
+
+	// ── admin-ui Page internals ───────────────────────────────────────
+	// admin-ui ships `.admin-ui-page` with `height: 100%`, which fills its
+	// parent's computed height. Paired with our flex chain, the element
+	// becomes a viewport-fitted flex column.
+	.admin-ui-page {
+		flex: 1 1 auto;
+		min-height: 0;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+	}
+
+	.admin-ui-page__header {
+		flex-shrink: 0;              // pinned at top of the flex column.
+	}
+
+	// The scrollable middle. <AdminPage> does not pass `hasPadding` to
+	// admin-ui's <Page>, so `.admin-ui-page__content` is not rendered —
+	// children drop in as direct descendants of `.admin-ui-page`. Target
+	// anything that isn't the header or the footer.
+
+	// `overflow: auto` (both axes) lets any child wider than the column
+	// (dashboard grids with fixed column widths, wide tables, `100vw`
+	// descendants) scroll horizontally inside the middle instead of
+	// dragging the whole window into a horizontal scrollbar.
+	.admin-ui-page > :not(.admin-ui-page__header):not(.jetpack-footer) {
+		flex: 1 1 auto;
+		min-height: 0;
+		min-width: 0;
+		overflow: auto;
+	}
+
+	// ── <JetpackFooter> pinned at the bottom ─────────────────────────
+	.jetpack-footer {
+		flex-shrink: 0;
+	}
+
+	// ── Mobile: admin bar grows to 46px; sidebar goes off-canvas ─────
+	// Match `.folded` and `.auto-fold` explicitly: both outrank the bare
+	// `#wpbody-content` selector on specificity, so the media query needs
+	// equal specificity for `left: 0` to win over the desktop fold rules.
+	@media (max-width: #{$jp-breakpoint-mobile}) {
+
+		#wpbody-content,
+		&.folded #wpbody-content,
+		&.auto-fold #wpbody-content {
+			top: var(--wp-admin-bar-height, #{$jp-admin-bar-height-mobile});
+			left: 0;                 // sidebar slides out of flow at this width.
+		}
+
+		.jp-admin-page {
+			margin-left: 0;          // override legacy -10px @ ≤782px too.
+		}
+	}
+}

projects/js-packages/base-styles/admin-page-layout.scss

@@ -0,0 +1,4 @@
+Significance: minor
+Type: added
+
+Added admin-page-layout mixin: a shared SCSS mixin that standardizes Jetpack wp-admin pages with a viewport-pinned content column (pinned header, scrolling middle, pinned footer). Consumed as `@use "@automattic/jetpack-base-styles/admin-page-layout"`.

projects/js-packages/base-styles/changelog/add-admin-page-layout-mixin

@@ -19,6 +19,7 @@
 		"build-production-js": "echo 'Not implemented.'"
 	},
 	"exports": {
+		"./admin-page-layout": "./admin-page-layout.scss",
 		"./gutenberg-base-styles": "./gutenberg-base-styles.scss",
 		"./package.json": "./package.json",
 		"./root-variables": "./root-variables.scss",

projects/js-packages/base-styles/package.json

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+AdminPage: added a stable, non-hashed `jp-admin-page` class on the component root so shared SCSS mixins and global stylesheets can target AdminPage without coupling to the hashed CSS-Modules className.

projects/js-packages/components/changelog/adminpage-stable-class

@@ -47,7 +47,10 @@ const AdminPage: FC< AdminPageProps > = ( {
 		restApi.setApiNonce( apiNonce );
 	}, [ apiRoot, apiNonce ] );
 
-	const rootClassName = clsx( styles[ 'admin-page' ], className, {
+	// `jp-admin-page` is a stable, non-hashed hook for global stylesheets and
+	// shared SCSS mixins (notably `jetpack-admin-page-layout` in
+	// @automattic/jetpack-base-styles). Do not rename.
+	const rootClassName = clsx( styles[ 'admin-page' ], 'jp-admin-page', className, {
 		[ styles.background ]: showBackground,
 		[ styles[ 'without-bottom-border' ] ]: tabs || ! showBottomBorder,
 	} );

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

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Adopt the shared Jetpack admin-page-layout mixin on the Backup admin page: pinned header, scrolling middle, pinned footer, no window-level scroll.

projects/packages/backup/changelog/adopt-admin-page-layout

@@ -1,6 +1,12 @@
 @use "@automattic/jetpack-base-styles/style" as jpbs;
+@use "@automattic/jetpack-base-styles/admin-page-layout" as *;
 @use "../masthead/calypso-mixins";
 
+body.jetpack_page_jetpack-backup {
+
+	@include jetpack-admin-page-layout;
+}
+
 .jp-header,
 .jp-footer {
 	padding: 20px 0;

projects/packages/backup/src/js/components/Admin/style.scss

@@ -0,0 +1,4 @@
+Significance: patch
+Type: changed
+
+Adopt the shared Jetpack admin-page-layout mixin on the Newsletter admin page: pinned header, scrolling middle, pinned footer, no window-level scroll. Adds @automattic/jetpack-base-styles as a workspace dependency.

projects/packages/newsletter/changelog/adopt-admin-page-layout

@@ -34,6 +34,7 @@
 	"dependencies": {
 		"@automattic/jetpack-analytics": "workspace:*",
 		"@automattic/jetpack-api": "workspace:*",
+		"@automattic/jetpack-base-styles": "workspace:*",
 		"@automattic/jetpack-components": "workspace:*",
 		"@automattic/jetpack-connection": "workspace:*",
 		"@automattic/jetpack-script-data": "workspace:*",