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

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

Why

Port the Jetpack Stats Search Terms module into Premium Analytics as a standalone widget (`jpa/search-terms`), closing WOOA7S-1496.

The data layer (`useStatsSearchTerms`, `sanitizeStatsSearchTermsResponse`, fixtures, tests) was already complete on trunk. This PR adds only the widget UI layer.

What

`widgets/search-terms/` — new widget folder following the standard contract:
- `widget.json` / `widget.ts` — static + live metadata, `jpa/search-terms` name, `search` icon
- `render.tsx` — `WidgetRoot` + `LeaderboardChart` with `itemLabel` wrapper (mirrors top-platforms pattern for correct bar height), three states (loading / error / empty)
- `use-search-term-views.ts` — maps `StatsSearchTermsItem[]` → `SearchTermView[]`
- `style.module.css` — WPDS tokens, container queries
- `stories/search-terms-widget.stories.tsx` — Default, WithComparison, WidgetDashboardWithWidget
`src/dashboard-layout.php` — adds `jpa/search-terms` to the default layout at 1×2, order 2

Notes

Search terms data requires organic search traffic from indexed sites. On sites with no search traffic for the selected period, the widget correctly shows an empty state. Selecting a longer date range (e.g. last year) will surface terms if the site has historical search data.

Test plan

Build: `jetpack build packages/premium-analytics`
Widget appears in the dashboard widget picker
With a site that has search terms data: rows render with correct bar proportions
Empty state shows when no data for the selected period
Storybook: `Default`, `WithComparison`, `WidgetDashboardWithWidget` stories render

🤖 Generated with Claude Code

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 🤖

🔴 Action required: Please include detailed testing steps, explaining how to test your change, like so:

## Testing instructions:

* Go to '..'
*

🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so:

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

My PR adds *x* and *y*.

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

No summary data is available for parent commit aedf21b, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for aedf21b is available.

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.

chihsuan · 2026-06-29T03:56:54Z

+ * @param root0     - Render props.
+ * @param root0.max - Maximum number of rows to display.


nit:

Suggested change

* @param root0 - Render props.

* @param root0.max - Maximum number of rows to display.

* @param props - Render props.

* @param props.max - Maximum number of rows to display.

Done, applied your suggestion.

chihsuan · 2026-06-29T03:57:11Z

+ * @param root0            - Render props.
+ * @param root0.attributes - Widget attributes (max, reportParams).


nit

Suggested change

* @param root0 - Render props.

* @param root0.attributes - Widget attributes (max, reportParams).

* @param props - Render props.

* @param props.attributes - Widget attributes (max, reportParams).

Done, applied your suggestion.

chihsuan · 2026-06-29T04:01:01Z

+
+	const report = primary.data as StatsNormalizedReport< StatsSearchTermsItem > | undefined;
+	const rawItems = report?.data?.[ 0 ]?.items ?? [];
+	const items = rawItems.map( toSearchTermView ).slice( 0, max > 0 ? max : undefined );


Just to confirm: does the API support a max parameter so we don’t need to handle this on the client side?

The Stats search-terms endpoint doesn't expose a max or num param for limiting items per period — it returns all terms up to a backend cap. Client-side slicing is the correct approach here.

chihsuan · 2026-06-29T04:02:49Z

+			currentShare: maxValue > 0 ? ( term.views / maxValue ) * 100 : 0,
+			previousShare: 0,
+			delta: 0,
+		} ) ) as LeaderboardChartData;


Is it possible to extract this builder as a function or use useMemo< LeaderboardChartData > so we don't need to use as here?

Done — switched to useMemo<LeaderboardChartData>() so the generic types the return value and the as cast is no longer needed.

chihsuan · 2026-06-29T04:04:46Z

+}
+
+/* Constrain the picker preview tile to a 4:3 aspect ratio. */
+:global([inert]:not([inert="true"])) .root {


I'm curious why this is needed? And do you think if any potential upstream improvements can avoid this?

This targets the widget picker's preview tile. The dashboard sets inert (without inert="true") on the preview container to disable pointer events during the "pick a widget" flow. The selector constrains the widget to a 4:3 aspect ratio so it fits cleanly in the tile rather than overflowing to full height. The same pattern is used in the other widgets (devices, top-platforms). Upstream improvement would be a CSS class the host applies to the preview container instead — happy to file a follow-up ticket if that's useful.

chihsuan · 2026-06-29T04:05:43Z

+.widgetHeader {
+	padding: var(--wpds-dimension-padding-md) var(--wpds-dimension-padding-lg);
+	min-height: 32px;
+	font-size: 13px;


Suggested change

font-size: 13px;

font-size: var(--wpds-typography-font-size-md);

Done, applied your suggestion.

chihsuan · 2026-06-29T04:06:35Z

+
+.widgetHeader {
+	padding: var(--wpds-dimension-padding-md) var(--wpds-dimension-padding-lg);
+	min-height: 32px;


Suggested change

min-height: 32px;

min-height: var(--wpds-dimension-size-md);

Done, applied your suggestion.

chihsuan · 2026-06-29T04:09:40Z

+			currentValue: term.views,
+			previousValue: 0,
+			currentShare: maxValue > 0 ? ( term.views / maxValue ) * 100 : 0,
+			previousShare: 0,


Why do we hardcode previousValue/previousShare/delta: 0 here?

The Stats search-terms API only returns current-period data — there's no comparison endpoint for search terms, so previous-period values aren't available. Hardcoding them to 0 is intentional; LeaderboardChart uses delta only to show the trend arrow/sparkline, which stays hidden when delta is 0. If comparison support is added to the API in future, we can wire it up here.

Thanks for the explanation.

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.

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>

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 dismissed chihsuan’s stale review via 0199035 June 29, 2026 08:52

dognose24 and others added 11 commits June 29, 2026 16:53

Premium Analytics: add jpa/search-terms widget

4db1d30

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

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

52660cf

…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

1124ecd

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

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

0ed8832

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

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

688379a

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

dognose24 force-pushed the add/wooa7s-1496-port-stats-module-search-terms branch from 0199035 to ccd14e8 Compare June 29, 2026 08:57

search-terms widget: pass withComparison to LeaderboardChart

7711b8d

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>

dognose24 requested a review from chihsuan June 29, 2026 09:24

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 29, 2026

github-actions Bot added [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 29, 2026

search-terms widget: truncate label text instead of wrapping

b96c46e

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>

		* @param root0 - Render props.
		* @param root0.max - Maximum number of rows to display.

		* @param root0 - Render props.
		* @param root0.attributes - Widget attributes (max, reportParams).

	font-size: 13px;
	font-size: var(--wpds-typography-font-size-md);

Uh oh!

Conversation

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

Uh oh!

Why

What

Notes

Test plan

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!

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!

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!

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