Premium Analytics: share Stats widget error descriptions

[chihsuan]

Fixes WOOA7S-1649

Proposed changes

Stats widgets currently build their error-state descriptors independently, which duplicates policy and has allowed details such as missing actions to drift. Now that WOOA7S-1770 preserves the HTTP status on failed Stats requests, this PR centralizes the UI decision in the widgets toolkit.

• Add a shared describeError mapper and unit tests.
• Show neutral, non-retryable copy for 403 responses and retryable copy for all other failures, including 404. The proxy's no_connection 403 stays retryable — a broken Jetpack connection can heal, unlike a permission gate.
• Widgets pass the retryable copy as a full sentence instead of a noun fragment interpolated into a shared frame, so translators see the whole sentence and languages with case/gender agreement can decline it correctly.
• Migrate Devices, Top Platforms, UTM Insights, and Search Terms to the shared mapper while retaining their existing partial-data guards; the view hooks now gate error with the same predicate as isError so the two fields can't disagree.
• Document the shared policy and add a patch changelog entry.

Related product discussion/links

• WOOA7S-1649
• Depends on Premium Analytics: keep HTTP status on failed API requests #50727 (WOOA7S-1770)

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

No.

Testing instructions

• Build Premium Analytics with its dependencies (pnpm jetpack build plugins/premium-analytics --deps) and open the Premium Analytics dashboard in wp-admin.
• To force the Devices / Top Platforms report requests to fail, drop this mu-plugin into wp-content/mu-plugins/. It reads a fake_err flag off the dashboard URL (via the request referer), so you can switch modes per page load without touching stored site state:

mu-plugin: force stats/devices/* errors

<?php
/**
 * Force Premium Analytics stats/devices/* requests to fail, driven by a
 * `fake_err` param on the wp-admin dashboard URL (read back off the referer).
 * Modes: 403 | 403nc (no_connection) | 500. Remove the param for normal data.
 */
add_filter(
	'rest_pre_dispatch',
	function ( $result, $server, $request ) {
		if ( ! preg_match( '#^/jetpack-premium-analytics/v1/proxy/v[0-9.]+/stats/devices/#', $request->get_route() ) ) {
			return $result;
		}

		$query = wp_parse_url( $_SERVER['HTTP_REFERER'] ?? '', PHP_URL_QUERY );
		parse_str( (string) $query, $args );

		switch ( $args['fake_err'] ?? '' ) {
			case '403':
				return new WP_Error( 'rest_forbidden', 'Simulated permission failure.', array( 'status' => 403 ) );
			case '403nc':
				return new WP_Error( 'no_connection', 'Simulated broken Jetpack connection.', array( 'status' => 403 ) );
			case '500':
				return new WP_Error( 'server_error', 'Simulated server failure.', array( 'status' => 500 ) );
		}

		return $result;
	},
	10,
	3
);

• Open the dashboard with &fake_err=403 appended to the URL. Confirm Devices and Top Platforms show “You don't have access to this data.” with no Retry button. 403s are not auto-retried, so the error shows immediately.

• Open with &fake_err=403nc. Confirm the widgets show the retryable copy with a Retry button instead — the proxy's no_connection 403 stays retryable.
• Open with &fake_err=500. Confirm Devices shows “We couldn't load device data. Please try again in a moment.” with a Retry button (Top Platforms says “platform data”). Non-403 failures go through React Query's three auto-retries first, so expect ~8 seconds of skeleton before the error appears — and keep the window focused, since React Query pauses retries while the tab is hidden.

• With the error state showing, drop the flag without reloading — run history.replaceState(null, '', location.href.replace(/&fake_err=\w+/, '')) in the DevTools console — then click Retry. Confirm the request runs again, succeeds, and the widget recovers to its chart.

[github-actions]

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 (WordPress.com Site Helper), and enable the wooa7s-1649-describe-error-dependent branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-1649-describe-error-dependent

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]

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:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. 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]

Code Coverage Summary

No summary data is available for parent commit 5839cb6, 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 5839cb6 is available.

Full summary · PHP report · JS report

[layoutd]

LGTM! Manually tested the error states and retry recovery; everything works as expected, left one non-blocking comment about storybook.

[layoutd]

Non-blocking: The Storybook error mocks return a 403, so these stories no longer show Retry as their descriptions claim. Maybe update the descriptions and add a retryable 500/no_connection story?

[chihsuan]

Good catch — confirmed. Both mock helpers reject with a 403 whose code isn't no_connection, so those four stories were rendering the neutral no-access copy while their descriptions still promised a Retry.

Fixed in edc2563