Premium Analytics: Show months with no subscriber data as a gap

[adamwoodnz]

Fixes WOOA7S-2181

Why

The Subscriber summary drew a zero for every month before a site launched or turned on subscriptions. A site launched in April, viewed over the last 12 months, showed zero bars or a flat zero line from October to March, as if it had been open to subscribers and gained none. Those months are now empty, and hovering one reads "No data".

Its chart dependencies are all merged: #52522 (CHARTS-281, the bar chart) and #52580 (CHARTS-284, the line chart) teach both charts to draw a null as a gap, and #52588 (CHARTS-283) keeps a small whole-number axis from repeating its labels.

Proposed changes

• The widget keeps the API's null. toPoints no longer turns a missing subscribers or subscribers_paid into 0, for bar and line mode alike. The headline figure still reads the latest point, falling back to 0.
• The toolkit's chart point accepts null. MetricTabDatum.value is now number | null. Nothing downstream needed changing: the chart series types already accept null.
• The toolkit tooltip reads a missing value as "No data". ChartTooltip typed its value as a number and handed it to MetricValue, and AbbreviatedValue formats null to an empty string, so the row printed no value at all. It now prints a translated "No data", as the charts package's own tooltip does. A genuine 0 still formats as 0.
• The value-first tooltip reads "No data for Subscribers". The comparative charts moved to Premium-analytics: read chart tooltip rows as value, metric, then date #52527's inline layout, which writes the value into the label, so the row lost its value column. ChartTooltip now hands getLabel a null for a missing reading, and formatTooltipPointLabel gives it its own translatable sentence: No data for %1$s · %2$s.

Screenshots

A site that launched in April, over the last 12 months. Both modes draw the count on the same 0 to 1 axis.

Bar mode: a month before launch reads "No data for Subscribers"

Bar mode: a month after launch keeps its value

Line mode: the line starts at April, and February reads "No data for Subscribers"

Line mode: a month after launch keeps its value

"1 Subscribers" is the value-first label's missing plural, tracked in UNI-813.

To do before ready

• Check line mode in wp-admin: the line starts at the launch month, and hovering an earlier month reads "No data".
• Tests: toPoints keeps a null and still reads a real 0, and TooltipRow prints "No data" for null and a formatted 0 for 0, and a null in a raw matrix row survives sanitizeStatsSubscribersResponse.
• Screenshots, of both modes.

Related product discussion/links

• WOOA7S-2181. Depends on CHARTS-281 (Charts: Let a bar chart show a period with no data #52522), CHARTS-284 (Charts: Let a line chart show a period with no data #52580) and CHARTS-283 (Charts: Tick a small whole-number value axis only on whole numbers #52588), all merged.
• UNI-813: count metrics in the value-first tooltip are not pluralized (1 Subscribers). Not changed here.

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

No.

Testing instructions

On a site that launched or turned on subscriptions inside the selected window (for example, in April):

• Open the Subscriber summary, choose Last 12 months, and switch to bar mode.
• The axis still runs the whole year, but there are no bars before the launch month.
• Hover a month before launch: the tooltip reads No data, not 0 or an empty row.
• A month with a real zero, if the site has one, still shows its zero bar.
• Switch to line mode: the line starts at the launch month, and hovering an earlier month reads No data.

Verified so far:

• PA typecheck: clean. ESLint: clean on every changed file.
• Tests for the subscriber chart, chart tooltip, metric tabs chart, the comparative bar and line charts, and the stats data processing: 42 suites, 356 tests passing. The new widget and tooltip tests fail with the fix reverted.
• Bar and line mode checked by hand in wp-admin, on a site launched in April, including the "No data" tooltip and a real value after launch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GZqouXJVXUJX4ywMC8krzp

[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!

---

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

• WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
• WoA releases happen weekly.
• Releases to self-hosted sites happen monthly:
  • Scheduled release: October 6, 2026

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

---

Wpcomsh plugin:

• Next scheduled release: Atomic deploys happen twice daily on weekdays (p9o2xV-2EN-p2)

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

---

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.

[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 (Jetpack or WordPress.com Site Helper), and enable the wooa7s-2181-premium-analytics-stop-turning-a-missing-subscriber-count branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack wooa7s-2181-premium-analytics-stop-turning-a-missing-subscriber-count

bin/jetpack-downloader test jetpack-mu-wpcom-plugin wooa7s-2181-premium-analytics-stop-turning-a-missing-subscriber-count

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

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/packages/widgets-toolkit/src/helpers/format-tooltip-point-label.ts	3/3 (100.00%)	0.00%	0 💚

Full summary · PHP report · JS report

[adamwoodnz]

@claude please review this PR. Get the change set with a single gh pr diff 52523, then read only the changed source files it touches. Skip changelog entries and lockfiles. Use at most about 20 tool calls, and post your review before you reach that, even if it is incomplete.

[claude]

Claude finished @adamwoodnz's task in 2m 28s —— View job

---

Review

• Get the change set (gh pr diff 52523)
• Read the changed source files (plus the data-layer types and the normalizer the null has to survive)
• Post review

The shape of the change is right, and the runtime half checks out: numericTimeSeriesRow in packages/data/src/processing/stats/time-series.ts:45-55 passes any value that is neither number nor string through untouched, so a null in a matrix row really does reach toPoints instead of being parsed to 0. Four things below, one of which I'd fix before merge.

---

1. The nullable contract lives in a cast, not in the type — use-subscribers-chart.ts:48-49

const subscribers = point.subscribers as number | null | undefined;
const paid = point.subscribers_paid as number | null | undefined;

Those casts exist because the data layer still says otherwise:

// packages/data/src/processing/stats/subscribers.ts:13-17
export type StatsSubscribersDataPoint = StatsNormalizedDataPoint & {
	value: number;
	subscribers?: number;
	subscribers_paid?: number;
};

Two costs. Every other consumer of StatsSubscribersDataPoint still believes those fields are numbers, so the next widget to read them repeats the discovery. And a cast isn't checked — if the field is later renamed or narrowed, the cast keeps compiling and the whole === null branch quietly becomes dead code, which is exactly the regression nobody would notice until a pre-launch month draws a zero bar again. Widen the two fields to number | null where they're declared and drop both casts; toPoints then reads as plain ?? logic with nothing asserted. Fix this →

2. A missing subscribers_paid key and an explicit null disagree — use-subscribers-chart.ts:56

paid === null ? null : Number( paid ?? 0 ) keeps an explicit null, but an absent key still becomes a real 0. So in the very window this PR is about, the Subscribers tab draws a gap while the Paid tab draws zero bars — if the endpoint omits the field rather than sending null for those buckets. If the endpoint always emits subscribers_paid alongside subscribers, this is moot and worth a word in the comment; otherwise ?? null makes the two shapes agree. (The subscribers line is different — its point.value fallback is pre-existing and serves responses that carry no subscribers field at all, so I'd leave it.)

3. The headline can still read a missing value as 0 — render.tsx:56

latest() now does accessor( last ) ?? 0. If the newest bucket is the missing one, the card reads 0 while the chart beside it draws a gap — the same contradiction the PR removes everywhere else, just relocated to the card. For a cumulative series the newest bucket is usually populated, so this is low-likelihood rather than wrong; but falling back to the last non-null point would close it without touching MetricTab.value (still number at metric-tabs-chart.tsx:69). Your call whether it's in scope.

4. The tooltip README is now stale — components/chart-tooltip/README.md:60,86-89

The prop table still documents getValue as (datum) => number, and the "Default Extractors" snippet still shows the old defaultGetValue returning number. Cheap to update in the same PR, and this package's own guidance treats these READMEs as documentation rather than commentary.

---

Notes, not asks

On the Codex P2 and your reply — your reasoning holds. A window that was all-zero classified as empty before this change and a window that is all-null classifies as empty after it, via the same isEmptyChartData; a window with at least one real reading was never empty and still isn't. So the set of non-interactive charts is unchanged by this PR, and the empty-state interactivity question really is a separate design call.

One adjacent gap the PR creates but can't reach. comparative-bar-chart.tsx:276 guards the re-attached previous-period row with if ( paired?.value != null ), so a comparison bucket whose value is null is dropped from the tooltip entirely rather than reading "No data". The subscribers widget passes no previous series, so nothing here hits it — but once MetricTabDatum.value is nullable, the first widget with a nullable comparison series will get silence where this PR promises "No data". Worth a follow-up issue rather than a change here.

Tests. Your to-do list has the right two cases. Given finding #1, I'd add a third: a fixture-level assertion that a null in a raw matrix row survives sanitizeStatsSubscribersResponse — that's the boundary the cast currently papers over, and it's the one that would break silently.

Everything else reads well — the 0 ?? null case is handled correctly in defaultGetValue, hasPaid's ( point.paid ?? 0 ) > 0 is right, and the two new JSDoc lines earn their space.
· branch wooa7s-2181-premium-analytics-stop-turning-a-missing-subscriber-count