WOOA7S-1502: Port Stats Shares widget

[chihsuan]

Fixes WOOA7S-1502

Proposed changes

Ports the Jetpack Stats Shares module into a registered Premium Analytics widget (jpa/shares).

Why. This is a re-do of #50148, which is being closed. That PR rendered Publicize follower counts (via useStatsPublicize) — the data behind the upstream stats-reach module — rather than the Shares module this issue is scoped to. The upstream source (stats-shares.tsx) is the "Number of Shares" card: how many times content was shared to each social network, not follower counts.

How. The share counts already live on the site summary (stats endpoint) as shares_<service> fields, so the widget reads them through the existing useStatsSite hook — no new data-package hook or query. A widget-local view hook (use-share-views.ts) scans the shares_<service> summary keys, labels known services, sorts by count, and trims to max. The summary is all-time with no comparison period, so the widget renders current counts with no period-over-period deltas.

Design note — data-driven service list (intentional divergence from upstream). Upstream stats-shares.tsx intersects the counts with useSharingButtonsQuery — the site's currently enabled sharing buttons. Because share counts are all-time historical, that approach hides historical shares for any network whose share button was later turned off (e.g. years of Facebook shares vanish the moment the Facebook button is disabled). This widget instead derives the service list from the summary's own shares_<service> keys, so historical counts stay visible regardless of the current button config, and a network Jetpack adds server-side shows up automatically — no extra sharing-buttons query. The single assumption, that every shares_<service> key is a per-network count, is pinned with a comment in the hook.

What.

• New widgets/shares/ workspace package: package.json, widget.json, widget.ts, use-share-views.ts, render.tsx, style.module.css, and a Storybook story.
• Follows the current Stats-widget contract: two-component structure, <WidgetRoot> seeded with host attributes, and <WidgetState> (not the legacy WidgetLoadingOverlay) for loading/error/empty. Empty state uses a neutral glyph and the upstream "Learn where your content has been shared the most." copy.
• Storybook mocks reuse the shared harness: the bare /stats summary is already routed by registerReportMocks(), so this only adds shares_* fields to the existing site-summary fixture — no story-scoped apiFetch middleware.
• Changelog entry added.

No changes to packages/data, packages/widgets-toolkit source, or @automattic/charts.

Follow-up. WOOA7S-1706 tracks unifying this widget-local service-label map with the data package's publicizeServices registry into one shared source (and giving Shares the service icons the Reach widget already renders), so the two social widgets stay visually consistent. Kept out of this PR to leave the data source untouched.

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

No. It surfaces existing Jetpack Stats share-count data through a new dashboard widget.

Testing instructions

• pnpm --dir projects/js-packages/storybook run storybook:dev → open Packages / Premium Analytics / Widgets / Shares and confirm the Default, WithComparison, and WidgetDashboardWithWidget stories render a populated leaderboard (Facebook / Twitter / LinkedIn / Tumblr). WithComparison shows the same counts with no deltas, as documented.
• Verified locally: /widget-audit shares clean, eslint clean, tsgo typecheck clean, and jetpack build --deps packages/premium-analytics succeeds (jpa/shares appears in the generated widget registry).
• Live-dashboard verification pending — handled centrally.

Screen.Recording.2026-07-13.at.3.55.44.PM.mov

[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

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/src/dashboard-layout.php	354/379 (93.40%)	0.18%	0 💚

Full summary · PHP report