Premium Analytics: port Stats File Downloads widget by dognose24 · Pull Request #50050 · Automattic/jetpack

dognose24 · 2026-06-29T14:15:48Z

Fixes WOOA7S-1498

Proposed changes

Ports the Jetpack Stats File Downloads module into Premium Analytics as the jpa/file-downloads widget.

Adds the File Downloads widget as a self-contained registered widget.
Renders file-download stats with the shared leaderboard UI.
Supports previous-period comparison row deltas when comparison is enabled.
Includes loading, empty, and error states aligned with the current widget guidelines.
Shows a Jetpack-sites-specific message when file-download stats are unavailable.
Adds Storybook stats mocks for primary and comparison file-download data.
Adds Default, WithComparison, and WidgetDashboardWithWidget Storybook stories.
Seeds jpa/file-downloads into the default dashboard layout at 1x2.
Adds a changelog entry for the new widget.

Related product discussion/links

WOOA7S-1498

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

No. This reads existing Jetpack Stats file-download data through the existing Premium Analytics stats data layer.

Testing instructions

Run:

pnpm --dir projects/packages/premium-analytics run typecheck
pnpm --dir projects/packages/premium-analytics run build:wp-build

In Storybook:

Open Packages/Premium Analytics/Widgets/FileDownloads.
Confirm Default, WithComparison, and WidgetDashboardWithWidget render correctly.
Confirm comparison deltas appear in WithComparison.

On a Jetpack-connected test site with file-download stats:

Open Premium Analytics.
Confirm File Downloads appears in the dashboard widget picker.
Add the widget and confirm downloaded files render as ranked rows with download counts.
Enable a comparison date range and confirm row deltas are shown.
Select a date range with no file-download data and confirm the empty state appears.
On a Jetpack site where file-download stats are unavailable, confirm the widget shows "File download stats are not available for Jetpack sites."

github-actions · 2026-06-29T14:17:37Z

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!

Premium Analytics plugin:

No scheduled milestone found for this plugin.

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

jp-launch-control · 2026-06-29T15:00:12Z

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/src/dashboard-layout.php	64/105 (60.95%)	5.52%	0 💚

Full summary · PHP report

dognose24 · 2026-06-29T15:57:12Z

🤖 Review-cycle summary — `d9e9c18` → `18b56ca`

4 rounds; CI green; 0 inline threads; 1 AI reviewer (claude[bot]) addressed.

What changed during the cycle

Commits added:

18b56ca112 — Address review: fix category to stats, document no-comparison intent
48899fd10a — Fix CI: Storybook tests — wrap LeaderboardChart stories in GlobalChartsProvider
feb3ad6e9c — Premium Analytics: changelog for file-downloads widget

Diff summary: 3 files changed, 16 insertions(+), 3 deletions(-)

Review actions taken:

Source	Item	Resolution
CI	Storybook tests failing — LeaderboardChart needs GlobalChartsProvider	Added `withChartTheme` decorator to `EmptyState` + `WithMockRows` stories (commit `48899fd`)
claude[bot]	category "traffic" should match sibling Stats widgets	Fixed `widget.json` category `"traffic"` → `"stats"` (commit `18b56ca`)
claude[bot]	WithComparison story renders identically to Default	Added docs note explaining file downloads has no PoP comparison view by design (commit `18b56ca`)
claude[bot]	storyWidgetType trimmed object vs widgetDefinition	Acknowledged — current pattern avoids TS friction; devices widget uses same approach
claude[bot]	currentShare relative to max row, not total	Acknowledged — intentional, matches Calypso leaderboard behavior
claude[bot]	empty Stats mock fallback shape	Noted for future additions; no code change needed

Unaddressed human comments: None.

CI: all required checks passing on commit 18b56ca.

chihsuan

Thanks @dognose24

I noticed that the focus style doesn't looks good. The focus outline gets clipped but I think this would need a general solution instead of fixing it in the widget so we can create a follow-up for it.

Also left a few inline comments but overall looks good.

kangzj

This looks good to me!

It seems the existing pattern hide most of these details in widget-toolkit, where it's env agnostic and keep only the essential scafolding in top level widgets. Should we do that?

cc/ @chihsuan

chihsuan · 2026-07-01T04:21:10Z

It seems the existing pattern hide most of these details in widget-toolkit, where it's env agnostic and keep only the essential scafolding in top level widgets. Should we do that?

Thanks! Worth separating the two patterns here, since they're intentionally different:

Woo ports: (e.g. SalesByDeviceWidget) live fully inside widgets-toolkit because they're genuinely env-agnostic reports shared by more than one registered widget.
Stats module ports (File Downloads, top-posts, visitors-over-time): Follow a different, documented pattern - pull data via the packages/data/ Stats hooks, compose toolkit primitives like LeaderboardChart, and map comparison rows in the widget itself. None of the existing Stats widgets push their logic into widgets-toolkit/src/widgets/. The visitors-over-time keeps its logic in a local components/ folder too.

This also lines up with the direction called out (p1782509121752509-slack-C06FSDTSN82) The goal is to move widget-specific code out of widgets-toolkit and keep only genuinely shared pieces there. the toolkit is flagged as an interim layer expected to shrink over time (folding into @automattic/charts), so moving more into it goes against that grain.

That said. if the leaderboard + comparison-mapping here ends up largely duplicating in many widgets, that's a real signal that we should extract as a toolkit primitive/helper.

dognose24 · 2026-07-01T04:48:28Z

That said. if the leaderboard + comparison-mapping here ends up largely duplicating in many widgets, that's a real signal that we should extract as a toolkit primitive/helper.

Agree with this. @kangzj @chihsuan Thanks for the feedback!

…-stats-module-file-downloads # Conflicts: # projects/packages/premium-analytics/packages/widgets-toolkit/src/stories/mocks/register-stats-mocks.ts

…-stats-module-file-downloads # Conflicts: # projects/packages/premium-analytics/src/dashboard-layout.php

chihsuan · 2026-07-02T04:01:26Z

+			<span>{ __( 'File downloads', 'jetpack-premium-analytics' ) }</span>
+		</span>
+	);
+}


Should we change the value ofpresentation and remove this so host owns the title/header?

I would keep this as-is for now. This widget intentionally uses presentation: "full-bleed" and owns its title/header, matching the direction we have been aligning with Locations/UTM/etc. Having these Stats widgets follow the same composition also gives us better control over consistent spacing, title/icon treatment, and state layouts. If we move title/header ownership back to the host, I think that should be a broader widget-root/guideline change rather than changing only File Downloads here.

One extra note: I also expect Top Posts to move toward this same full-bleed/title-owned pattern when we align the remaining Stats widgets. So the intent here is consistent header/title/icon control across Stats widgets rather than File Downloads being a one-off.

IMO, It feels a bit fragile to define a custom title/header here rather than reusing the widget's built-in header. If the core widget header ever changes, these custom header widgets could end up with inconsistent styles.

That said, no worries for now! This looks like an upstream issue that @retrofox is already working on over in WordPress/gutenberg#79246, so we should be in good hands.

That said, no worries for now! This looks like an upstream issue that @retrofox is already working on over in WordPress/gutenberg#79246, so we should be in good hands.

Yeah, it should be, and we will figure out a better way to handle it all together.

I think It's fragile as well. Using the title to represent the local state doesn't align with the API's design.

WordPress/gutenberg#79735 is the first step in this

chihsuan · 2026-07-02T04:03:22Z

+		.join( ' ' );
+}
+
+function getFileDownloadsErrorMessage( error: unknown ) {


No other Stats widget carries this error-parsing cluster (toStatusNumber/getErrorStatus/getErrorText). Is this specific required for file downloads widget? Or I'm curious if we should handle this in data level so it can be reused for all Stats widget (maybe a follow-up).

Yes, this is currently File Downloads-specific. The API returns a 404 for Jetpack sites where file download stats are not available, and we need to surface a more precise message than the generic load failure. I agree this would be better as a reusable data-layer error reason if/when more Stats widgets need it. UTM, Devices, and other advanced Stats features can also have API-side permission/availability controls, so normalizing this in the data layer sounds like a good follow-up.

Opened a separate Premium Analytics follow-up for normalizing API availability/permission error reasons in the data layer. That should let widgets like File Downloads, UTM, Devices, and Top Platforms render consistent unavailable/error states without each widget parsing raw status/message fields.

chihsuan · 2026-07-02T04:04:17Z

+					rows={ rows }
+					isLoading={ showLoading }
+					isError={ isError }
+					withComparison={ hasComparison }


top-posts gates on hasComparison && primaryRows.some(row => previousViewsByHref.has(row.href)), but here it's withComparison={ hasComparison } unconditionally.

When the comparison report has no overlapping rows, every previousValue falls back to 0 and calculateDelta(value, 0) returns 100 , so each row shows a fabricated +100%.

Should this defer comparison the way top-posts does when nothing overlaps?

Good catch. I updated this to mirror top-posts: the comparison UI is now enabled only when at least one primary row has a matching comparison row, so missing comparison rows are no longer treated as real 0 values. I also checked nearby widgets: top-posts already has this guard, while UTM/Search Terms/Locations appear to have the same missing-comparison-as-zero pattern and should be aligned in their own PRs/follow-up rather than bundled into this File Downloads PR.

Opened a Premium Analytics follow-up to audit and align this across the remaining Stats widgets. Keeping this PR scoped to File Downloads: Top Posts already has this guard, and the follow-up will cover the other row-level comparison widgets so they do not treat missing comparison rows as real zero values.

…-stats-module-file-downloads # Conflicts: # projects/packages/premium-analytics/packages/widgets-toolkit/src/stories/mocks/register-stats-mocks.ts # projects/packages/premium-analytics/src/dashboard-layout.php # projects/packages/premium-analytics/tests/php/Dashboard_Layout_Test.php

chihsuan

Thanks @dognose24 Looks good. Let's keep iterate this.

github-actions Bot added [Package] Premium Analytics [Status] In Progress labels Jun 29, 2026

github-actions Bot added the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jun 29, 2026

This comment has been minimized.

Sign in to view

dognose24 added [Status] Needs Team Review Obsolete. Use Needs Review instead. and removed [Status] In Progress labels Jun 29, 2026

dognose24 marked this pull request as ready for review June 29, 2026 15:57

dognose24 requested a review from a team June 29, 2026 15:57

dognose24 requested a review from a team as a code owner June 29, 2026 15:57

dognose24 self-assigned this Jun 29, 2026

dognose24 removed the [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. label Jun 29, 2026

github-actions Bot added [Status] In Progress [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jun 29, 2026

dognose24 changed the title ~~Premium Analytics: port Jetpack Stats file-downloads module~~ Premium Analytics: port Stats File Downloads widget Jun 29, 2026

chihsuan reviewed Jun 30, 2026

View reviewed changes

Comment thread ...ackages/premium-analytics/packages/widgets-toolkit/src/stories/mocks/register-stats-mocks.ts Outdated

Comment thread projects/packages/premium-analytics/widgets/file-downloads/render.tsx Outdated

Comment thread projects/packages/premium-analytics/widgets/file-downloads/render.tsx

Premium Analytics: Align file downloads widget stories

3e46cae

kangzj previously approved these changes Jul 1, 2026

View reviewed changes

Add File Downloads to default dashboard

a8a63eb

dognose24 dismissed kangzj’s stale review via a8a63eb July 1, 2026 03:21

dognose24 added 4 commits July 1, 2026 11:29

Handle File Downloads Jetpack site errors

c37fab0

Detect File Downloads unavailable errors

23b1e97

Wrap File Downloads states with content padding

73c66d4

Center File Downloads placeholder states

5ab6c80

dognose24 added 3 commits July 1, 2026 12:59

Merge remote-tracking branch 'origin/trunk' into add/wooa7s-1498-port…

3c7f562

…-stats-module-file-downloads # Conflicts: # projects/packages/premium-analytics/packages/widgets-toolkit/src/stories/mocks/register-stats-mocks.ts

Premium Analytics: test file downloads dashboard layout

b2ccd7e

Premium Analytics: fix stats mock lint

7bf4a5b

dognose24 requested review from chihsuan and kangzj July 1, 2026 14:01

dognose24 added 6 commits July 2, 2026 00:22

Keep File Downloads header across states

b44b98f

Hide File Downloads title in close-up stories

cd03921

Use leaderboard empty state for unsupported file downloads

403e9eb

Keep File Downloads errors on custom surface

143d6ec

Add icon to File Downloads widget header

d4187fd

Merge remote-tracking branch 'origin/trunk' into add/wooa7s-1498-port…

27a6e67

…-stats-module-file-downloads # Conflicts: # projects/packages/premium-analytics/src/dashboard-layout.php

chihsuan reviewed Jul 2, 2026

View reviewed changes

dognose24 added 2 commits July 2, 2026 12:31

Guard File Downloads comparison rows

b2ff78d

chihsuan previously approved these changes Jul 2, 2026

View reviewed changes

Fix File Downloads comparison formatting

d9f6bc6

dognose24 dismissed chihsuan’s stale review via d9f6bc6 July 2, 2026 04:55

dognose24 merged commit 1504c9a into trunk Jul 2, 2026
75 checks passed

dognose24 deleted the add/wooa7s-1498-port-stats-module-file-downloads branch July 2, 2026 05:13

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

Conversation

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

Uh oh!

Proposed changes

Related product discussion/links

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

Testing instructions

Uh oh!

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

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

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

Uh oh!

Code Coverage Summary

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

dognose24 commented Jun 29, 2026

🤖 Review-cycle summary — d9e9c18 → 18b56ca

Uh oh!

chihsuan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kangzj left a comment

Choose a reason for hiding this comment

Uh oh!

chihsuan commented Jul 1, 2026

Uh oh!

dognose24 commented Jul 1, 2026

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!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dognose24 commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 29, 2026 •

edited

Loading

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

edited

Loading

🤖 Review-cycle summary — `d9e9c18` → `18b56ca`