Premium Analytics: port Stats Search Terms widget by dognose24 · Pull Request #49985 · Automattic/jetpack

dognose24 · 2026-06-26T03:18:36Z

Fixes WOOA7S-1496

Proposed changes

Ports the Jetpack Stats Search Terms module into Premium Analytics as the jpa/search-terms widget.

Adds the widgets/search-terms/ widget contract (package.json, widget.json, widget.ts, render.tsx, style.module.css, and stories).
Renders search term stats with the shared LeaderboardChart UI.
Uses the existing useStatsSearchTerms data layer, including comparison-aware report params.
Supports previous-period comparison row deltas when comparison is enabled.
Keeps loading, error, and empty states aligned with the current widget guidelines.
Adds Search Terms to the default dashboard layout at 1x2.
Adds Default, WithComparison, and WidgetDashboardWithWidget Storybook stories.

Related product discussion/links

WOOA7S-1496

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

No. This reads existing Jetpack Stats search-term 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/SearchTerms.
Confirm Default, WithComparison, and WidgetDashboardWithWidget render correctly.
Confirm the stories do not show a duplicate inner title.
Confirm comparison deltas appear in WithComparison.

On a Jetpack-connected test site with search-term data:

Open Premium Analytics.
Confirm Search Terms appears in the dashboard widget picker.
Add the widget and confirm rows render with correct bar proportions.
Enable a comparison date range and confirm row deltas are shown.
Select a date range with no search-term data and confirm the empty state appears.

github-actions · 2026-06-26T03:19:47Z

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-26T03:21:43Z

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/src/dashboard-layout.php	0/84 (0.00%)	0.00%	13 💔

Full summary · PHP report

_{Coverage check overridden by

Covered by non-unit tests
Use to ignore the Code coverage requirement check when E2Es or other non-unit tests cover the code
.}

…erns (#49987) * Premium Analytics: document widget conventions and Stats porting patterns Consolidates conventions surfaced during code review of the Locations (#49513), Devices (#49928), and Search Terms (#49985) ports into shared agent guidance so future batch ports have a single source of truth. - `.agents/rules/widgets.md` — adds Two-component structure section (outer WidgetRoot / inner useWidgetRootContext, reportParams from context) - `AGENTS.md` — adds package-wide pitfalls (alias naming, English comments) and new Widget pitfalls (presentation source of truth, attribute type locality, button type, inline styles, toolkit helpers); new Stats widgets section covering data hooks, data access path, max=0 semantics, loading strategy, comparison placeholders, and visual conventions - `.agents/skills/widget-audit.md` — extends checklist with presentation consistency, ghost attributes, alias names, WidgetRenderProps<T> import, inline styles, button type, i18n scope, and English comments Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * changelog: add entry for widget conventions docs update Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> * Premium Analytics: clarify widget guidance * Premium Analytics: refine widget guidance --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

chihsuan

I ran the three stories in Storybook and none of them render the widget with data. We should feeding fixtures.

Also left a few suggestions/questions.

registerReportMocks() covers Woo analytics paths out of the box but not Stats proxy paths (/proxy/v1.1/stats/*). Stats widgets need their endpoint wired into routeStatsReport() in register-report-mocks.ts. Discovered via PR #49985 review feedback. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

chihsuan

Built it locally and all three stories render correctly. Thanks @dognose24 👍

One thing I noticed while reviewing the WidgetDashboardWithWidget story:

When rows exceed the tile height you get a scrollbar instead of the rows fitting the space. Not a regression here. It comes from the shared LeaderboardChart (__content { overflow: auto }), so Top Posts behaves the same. Worth a follow-up at the chart / widgets-toolkit layer so it fixes both widgets in one place. Not blocking.

chihsuan · 2026-06-30T07:58:36Z

I did also notice that widget setting button doesn't work. But I'm not sure if it's caused by storybook setting or there is a bug. Could you please take a look? Thanks!

Followed up on the "widget setting doesn't work" observation, it's not a problem with this widget.

Fixed separately in #50070

registerReportMocks() covers Woo analytics paths out of the box but not Stats proxy paths (/proxy/v1.1/stats/*). Stats widgets need their endpoint wired into routeStatsReport() in register-report-mocks.ts. Discovered via PR #49985 review feedback. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

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

Add itemLabel wrapper with padding (mirrors top-platforms pattern) so the overlay bar gets its height from the label element. Pass loading prop and use chart's built-in emptyStateText. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

- widget.ts: add `as const` to attributes type field so it narrows to literal 'integer' rather than string (fixes StoryWidgetMetadata mismatch) - use-search-term-views: cast reportParams to StatsReportParams (same pattern as use-location-views) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…is source of truth) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

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

…empty state Remove manual empty/loading early returns that bypassed the header. Use WidgetLoadingOverlay for initial load, and LeaderboardChart's built-in emptyStateText for no-data state (same pattern as top-platforms). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

…with devices) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Mirrors the top-platforms pattern to guarantee unique React keys. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

- Storybook: add Stats proxy mock handler so stories render real data. registerReportMocks() now intercepts /proxy/v1.1/stats/* in addition to the existing /proxy/v2/analytics/reports/* coverage; adds search-terms fixture data (primary + comparison). - render.tsx: fix JSDoc @param tags (root0 → props); use useMemo<LeaderboardChartData> generic instead of `as` cast. - style.module.css: replace hardcoded 32px/13px with WPDS tokens (--wpds-dimension-size-md / --wpds-typography-font-size-md). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

registerReportMocks() covers Woo analytics paths out of the box but not Stats proxy paths (/proxy/v1.1/stats/*). Stats widgets need their endpoint wired into routeStatsReport() in register-report-mocks.ts. Discovered via PR #49985 review feedback. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

useStatsSearchTerms already fetches both primary and comparison periods when compare_from/compare_to are present. useSearchTermViews now reads the comparison result, builds a label→views map, and pairs each primary term with its comparison view count. render.tsx uses previousViews for previousValue/previousShare/delta so LeaderboardChart shows trend arrows and sparklines in comparison mode. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

LeaderboardChart requires withComparison={true} to render delta arrows and previous-period bars. Wire hasComparison from useSearchTermViews. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Long search terms caused the bar height to grow when the widget was narrow. Add overflow/text-overflow to the label so it ellipsis-clips. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

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

github-actions Bot added [Package] Premium Analytics [Status] In Progress labels Jun 26, 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 26, 2026

dognose24 force-pushed the add/wooa7s-1496-port-stats-module-search-terms branch from ec5da44 to ea30566 Compare June 26, 2026 05:59

dognose24 changed the title ~~Premium Analytics: add jpa/search-terms widget~~ Premium Analytics: port Stats Search Terms widget Jun 26, 2026

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

dognose24 marked this pull request as ready for review June 26, 2026 06:28

dognose24 requested review from a team as code owners June 26, 2026 06:28

dognose24 added [Status] Needs Review This PR is ready for review. and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. [Status] In Progress labels Jun 26, 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. and removed [Status] Needs Review This PR is ready for review. labels Jun 26, 2026

dognose24 self-assigned this Jun 26, 2026

dognose24 mentioned this pull request Jun 26, 2026

Premium Analytics: document widget conventions and Stats porting patterns #49987

Merged

chihsuan reviewed Jun 29, 2026

View reviewed changes

chihsuan previously approved these changes Jun 29, 2026

View reviewed changes

dognose24 force-pushed the add/wooa7s-1496-port-stats-module-search-terms branch from accbc9e to fbc15af Compare June 30, 2026 08:47

dognose24 added [Status] Needs Review This PR is ready for review. and removed [Status] Needs Author Reply We need more details from you. This label will be auto-added until the PR meets all requirements. labels Jul 1, 2026

dognose24 and others added 17 commits July 1, 2026 09:48

Premium Analytics: add jpa/search-terms widget

4155030

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

search-terms widget: remove presentation from widget.ts (widget.json …

b3f9481

…is source of truth) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

search-terms widget: add padding to empty/error/loading states

cedb2ab

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

search-terms widget: fix dashboard placement order (was 2, conflicts …

b32144b

…with devices) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

search-terms widget: use index-label as leaderboard item id

f3f6bc8

Mirrors the top-platforms pattern to guarantee unique React keys. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

search-terms widget: pass withComparison to LeaderboardChart

b5e5e2d

LeaderboardChart requires withComparison={true} to render delta arrows and previous-period bars. Wire hasComparison from useSearchTermViews. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

search-terms widget: truncate label text instead of wrapping

731f830

Long search terms caused the bar height to grow when the widget was narrow. Add overflow/text-overflow to the label so it ellipsis-clips. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Premium Analytics: align search terms widget feedback

5ddd100

Premium Analytics: initialize search terms story attributes

c239a54

Premium Analytics: Align search terms widget stories

faf95bf

Fix Search Terms story formatting

31ca743

dognose24 force-pushed the add/wooa7s-1496-port-stats-module-search-terms branch from 399ca86 to 31ca743 Compare July 1, 2026 01:51

dognose24 added 4 commits July 1, 2026 21:49

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

7037b7f

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

Keep Search Terms header across states

73b5ee6

Align Search Terms dashboard story presentation

3e96027

Add icon to Search Terms widget header

25f1779

dognose24 merged commit b0aa5d0 into trunk Jul 2, 2026
73 checks passed

dognose24 deleted the add/wooa7s-1496-port-stats-module-search-terms branch July 2, 2026 03:47

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Premium Analytics: port Stats Search Terms widget#49985

Premium Analytics: port Stats Search Terms widget#49985
dognose24 merged 21 commits into
trunkfrom
add/wooa7s-1496-port-stats-module-search-terms

dognose24 commented Jun 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

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

edited

Loading

Uh oh!

chihsuan left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chihsuan left a comment

Uh oh!

chihsuan commented Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

dognose24 commented Jun 26, 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 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control Bot commented Jun 26, 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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chihsuan left a comment

Choose a reason for hiding this comment

Uh oh!

chihsuan commented Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dognose24 commented Jun 26, 2026 •

edited

Loading

github-actions Bot commented Jun 26, 2026 •

edited

Loading

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

edited

Loading