Premium Analytics: add a per-section header with title and date controls by retrofox · Pull Request #50894 · Automattic/jetpack

retrofox · 2026-07-29T08:16:30Z

Proposed changes

The SectionHeader component

A new SectionHeader in the internal ui package. The left half anchors the section: the title (heading-2xl, rendered as an h2 under the breadcrumb h1) plus an optional subtitle.

The right half is a slot. The consumer mounts the date controls there, so the component stays purely presentational and owns no date state.

Storybook stories cover the two instances from the design: rolling presets with comparison, and the year surface.

Before

After

Dashboard wiring

Each section panel now renders the header, with the title coming from the section registry's label. DateFiltersPanel moves from above the panels into the header's controls slot.

Only the active panel mounts, so there is still a single live instance of the filters.

The subtitle is intentionally absent for now. WOOA7S-1824 adds the formatter that derives it from the applied date configuration.

Scroll moves to the page content

The section panel no longer owns a scroll container. The page content scrolls instead, so the section tabs scroll away with it.

This is the groundwork for pinning the header below the page header, tracked in WOOA7S-1825.

A responsive fix on the way

The filters' responsive measurement now targets the full header row instead of a content-sized wrapper.

Before this change, the compact layout could latch on the first shrink and never disengage when space returned.

Related product discussion/links

Linear umbrella: WOOA7S-1793, consistent title and date selection component.

Follow-ups filed: WOOA7S-1824 (dynamic subtitle) and WOOA7S-1825 (sticky header).

Does this pull request change what data or activity we track or use?

No.

Testing instructions

Setup

Build the package with jetpack build packages/premium-analytics --deps, then open the dashboard at wp-admin/admin.php?page=jetpack-premium-analytics.

The header

Each section (Traffic, Insights, Subscribers) renders its title above the widgets, with the date filters aligned to the end of the same row.

The page header keeps the "Analytics" breadcrumb, and the previous page-level subtitle is gone. The section subtitle is absent until WOOA7S-1824 lands.

Scrolling

Scroll the page. The section tabs scroll away with the content, since the page content is the scroll container now.

Screen.Recording.2026-07-29.at.9.30.43.AM.mov

Responsive

Shrink the viewport below ~600px so the presets collapse into the compact select, then widen it again.

The preset pills must return. Before this PR, the compact layout could stay latched.

Storybook

Run cd projects/js-packages/storybook && pnpm run storybook:dev and check Packages/Premium Analytics/UI/SectionHeader.

the subtitle has no source until the date-config formatter lands

scroll moves to the page content so tabs scroll away with it

github-actions · 2026-07-29T08:17:39Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the add/pa-section-header branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack add/pa-section-header

bin/jetpack-downloader test jetpack-mu-wpcom-plugin add/pa-section-header

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2026-07-29T08:20:02Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

jp-launch-control · 2026-07-29T08:28:38Z

Code Coverage Summary

2 files are newly checked for coverage.

File	Coverage
projects/packages/premium-analytics/packages/ui/src/section-header/section-header.tsx	1/1 (100.00%) 💚
projects/packages/premium-analytics/packages/ui/src/section-header/index.ts	0/0 (—%) 🤷

Full summary · PHP report · JS report

chihsuan

Really like the shape of this! 👍

I just noticed a few things while poking at this, and most of them seems because the responsive measurement now that it lives inside the tab panels. I've added a few inline comments.

chihsuan · 2026-07-30T02:51:33Z

 								value={ section.slug }
 								className={ styles.content }
 							>
+								<div ref={ setContainerElement } className={ styles.sectionHeader }>


I wonder if we should make each panel have its own container state?

Right now, all panels share setContainerElement. When switching tabs, the old panel can clear the ref after the new panel sets it, leaving containerElement as null. The filters then measure document.body instead of the actual row. Since the body is much wider, the filters may incorrectly stay in the wide layout.

Screen.Recording.2026-07-30.at.10.49.24.AM.mov

I wonder if we should make each panel have its own container state?

This is a good question. The composition between SectionHeader and the tabs doesn't look very good. I'll take a look.

Confirmed, and it happens on every tab switch. Base UI defers the outgoing panel's unmount by a frame, so the incoming panel sets the ref and the old one nulls it right after. The filters then measure document.body, around 208px wider than the real row, which keeps the presets wide between roughly 600 and 810px.

#50906 removes containerElement altogether and has the panel measure its own root, so the shared ref stops existing. The two PRs already conflict in stage.tsx and that is the resolution. What it does not cover is that SectionHeader's controls slot is a shrink-to-fit flex item, so a self-measuring panel would read its own content instead of the row. Tracked in WOOA7S-1837.

chihsuan · 2026-07-30T02:53:06Z

+ */
+export function SectionHeader( { title, subtitle, children }: SectionHeaderProps ) {
+	return (
+		<Stack direction="row" align="flex-start" justify="space-between">


Worth adding a gap here? Stack doesn't set one, so a long translated title can end up right up against the date controls.

Yes, 👍 . This will be addressed in a follow-up.

chihsuan · 2026-07-30T02:57:23Z

 							>
+								<div ref={ setContainerElement } className={ styles.sectionHeader }>
+									<SectionHeader title={ section.label }>
+										<DateFiltersPanel { ...dateFilters } containerElement={ containerElement } />


The container used to mean "how much room do the filters have, but now the title also uses part of this container, so the filters may see 700px even though they only have 500px and incorrectly stay in the wide layout. Should the measured slot have a stable allocated width?

Same as before. Those controls will change soon, so I'd like to address that in a follow-up. For instance, this PR #50906

chihsuan · 2026-07-30T03:03:09Z

@@ -12,7 +12,7 @@
 .content {


I noticed that in mobile view, or on a tall screen, the sticky header may scroll away once we pass the first screen of widgets.

Screen.Recording.2026-07-30.at.10.46.01.AM.mov

yes, same comment as the previous ones. Let's address it in a follow-up. I don't want to introduce too many changes in this PR

chihsuan

Let's iterate on another PR. 🚢

retrofox · 2026-07-30T08:10:04Z

Thanks. We have a few issues that address these tasks.

covers title heading, subtitle branch, controls slot

retrofox added 6 commits July 28, 2026 16:14

add SectionHeader component to ui package

4076f90

add SectionHeader stories

e2cb2de

update DashboardSections props docblock

261e4c3

make SectionHeader subtitle optional

9776382

the subtitle has no source until the date-config formatter lands

render SectionHeader in dashboard sections

75b9406

scroll moves to the page content so tabs scroll away with it

add changelog entry for the section header

d247644

retrofox requested a review from a team July 29, 2026 08:16

retrofox requested a review from a team as a code owner July 29, 2026 08:16

retrofox added Enhancement Changes to an existing feature — removing, adding, or changing parts of it [Status] Needs Review This PR is ready for review. labels Jul 29, 2026

retrofox self-assigned this Jul 29, 2026

github-actions Bot added the [Package] Premium Analytics label Jul 29, 2026

Merge remote-tracking branch 'origin/trunk' into add/pa-section-header

d4d6ce2

retrofox mentioned this pull request Jul 29, 2026

Premium Analytics: describe the applied date configuration in the section header subtitle #50897

Merged

1 of 2 tasks

clean jsdoc comments

8c3c0cb

retrofox force-pushed the add/pa-section-header branch from b781db2 to 8c3c0cb Compare July 29, 2026 11:29

chihsuan reviewed Jul 30, 2026

View reviewed changes

chihsuan previously approved these changes Jul 30, 2026

View reviewed changes

retrofox requested a review from a team July 30, 2026 08:16

retrofox added 2 commits July 30, 2026 09:24

Merge remote-tracking branch 'origin/trunk' into add/pa-section-header

37fa494

add SectionHeader component tests

af67b86

covers title heading, subtitle branch, controls slot

retrofox dismissed chihsuan’s stale review via af67b86 July 30, 2026 10:57

Merge remote-tracking branch 'origin/trunk' into add/pa-section-header

e98e9f0

retrofox merged commit 23c627c into trunk Jul 30, 2026
80 checks passed

retrofox deleted the add/pa-section-header branch July 30, 2026 11:53

github-actions Bot removed the [Status] Needs Review This PR is ready for review. label Jul 30, 2026

github-actions Bot added the [Status] UI Changes Add this to PRs that change the UI so documentation can be updated. label Jul 30, 2026

louwie17 mentioned this pull request Jul 30, 2026

Premium Analytics: add a per-section all-time and yearly date selection #50930

Merged

retrofox mentioned this pull request Aug 13, 2026

Premium Analytics: pin the dashboard section header and condense it on scroll #51232

Merged

Conversation

retrofox commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes

The SectionHeader component

Dashboard wiring

Scroll moves to the page content

A responsive fix on the way

Related product discussion/links

Does this pull request change what data or activity we track or use?

Testing instructions

Setup

The header

Scrolling

Responsive

Storybook

Uh oh!

github-actions Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 29, 2026

Uh oh!

jp-launch-control Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

chihsuan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chihsuan left a comment

Choose a reason for hiding this comment

Uh oh!

retrofox commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

retrofox commented Jul 29, 2026 •

edited

Loading

github-actions Bot commented Jul 29, 2026 •

edited

Loading

jp-launch-control Bot commented Jul 29, 2026 •

edited

Loading