Skip to content

Widgets: normalize Premium Analytics widget file and style conventions - #50112

Merged
chihsuan merged 3 commits into
trunkfrom
wooa7s-1642-widgets-normalize-file-conventions
Jul 2, 2026
Merged

chihsuan merged 3 commits into
trunkfrom
wooa7s-1642-widgets-normalize-file-conventions

Conversation

@chihsuan

@chihsuan chihsuan commented Jul 1, 2026 •

Copy link
Copy Markdown
Member

Fixes WOOA7S-1642

Proposed changes

Part of the Premium Analytics widget consistency cleanup (WOOA7S-1640). Normalizes cosmetic/file conventions across projects/packages/premium-analytics/widgets/. No behavior or output change.

  • CSS-module naming → every widget's CSS module is now style.module.css (matching the widgets.md rule example). Renamed via git mv, history preserved: emails, subscribers-chart, subscribers-list, top-posts (<slug>.module.css → style.module.css), with their import styles from … lines updated. (hello-world, locations, react-query-dev-tool were already style.module.css.)
  • SCSS → CSS: payment-status/payment-status-widget.module.scss → payment-status/style.module.css (file was already plain-CSS syntax; rename + extension only). Import updated in payment-status-widget.tsx.
  • Import header: hello-world/render.tsx now uses the External/Internal dependencies grouping the other widgets use; dropped the lone : React.ReactNode annotation.
  • Deps: hello-world/package.json — moved @wordpress/widget-primitives to dependencies (only one imported by shipped code), bumped @wordpress/element 6.46.0 → 8.0.1 to match siblings. @wordpress/widget-dashboard stays in devDependencies (story-only); no react added (not imported).

Related product discussion/links

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

No. File naming, imports, and dependency metadata only; no data collection or runtime behavior change.

Testing instructions

  • From the repo root, tsgo --noEmit typecheck and eslint (pre-commit) both pass clean.
  • Confirm every widget CSS module is named style.module.css, no .scss remains under widgets/, and there are no lingering references to old CSS filenames.
  • In Storybook, confirm Emails, Hello World, Locations, Payment status, React Query Devtools, Subscribers, Latest Subscribers, and Top posts render identically to before.

@github-actions

github-actions Bot commented Jul 1, 2026 •

Copy link
Copy Markdown
Contributor

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!

@github-actions 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 Jul 1, 2026
@jp-launch-control

jp-launch-control Bot commented Jul 1, 2026 •

Copy link
Copy Markdown

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR standardizes file naming and styling conventions across the Premium Analytics widget packages under projects/packages/premium-analytics/widgets/, aiming to reduce drift and make widgets more consistent to read and reuse.

Changes:

  • Renames CSS module files to the common <widget-slug>.module.css convention and updates corresponding imports.
  • Converts the Payment Status widget’s stylesheet from .module.scss to .module.css (extension/name normalization) and updates its import.
  • Normalizes the Hello World widget’s import header style and adjusts its dependency placement/versions; adds a Premium Analytics changelog entry.

Reviewed changes

Copilot reviewed 6 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
projects/packages/premium-analytics/widgets/react-query-dev-tool/render.tsx Updates CSS-module import to the normalized filename.
projects/packages/premium-analytics/widgets/react-query-dev-tool/react-query-dev-tool.module.css Adds/renames the widget’s CSS module under the normalized naming convention.
projects/packages/premium-analytics/widgets/payment-status/payment-status.module.css Adds/renames the Payment Status widget CSS module (normalized extension/name).
projects/packages/premium-analytics/widgets/payment-status/payment-status-widget.tsx Updates stylesheet import to the new .module.css file.
projects/packages/premium-analytics/widgets/locations/render.tsx Updates CSS-module import to the normalized filename.
projects/packages/premium-analytics/widgets/locations/locations.module.css Adds/renames the widget’s CSS module under the normalized naming convention.
projects/packages/premium-analytics/widgets/hello-world/render.tsx Aligns import grouping convention and removes the explicit React.ReactNode return annotation.
projects/packages/premium-analytics/widgets/hello-world/package.json Adjusts dependency placement and bumps @wordpress/element to align with sibling widgets.
projects/packages/premium-analytics/widgets/hello-world/hello-world.module.css Adds/renames the widget’s CSS module under the normalized naming convention.
projects/packages/premium-analytics/changelog/wooa7s-1642-widget-file-conventions Documents the convention normalization in the package changelog.

@chihsuan
chihsuan force-pushed the wooa7s-1642-widgets-normalize-file-conventions branch from 231c883 to 0da9eb8 Compare July 1, 2026 09:12
@chihsuan
chihsuan marked this pull request as ready for review July 1, 2026 09:19
@chihsuan
chihsuan requested a review from a team July 1, 2026 09:19
@chihsuan
chihsuan requested a review from a team as a code owner July 1, 2026 09:19
kangzj
kangzj previously approved these changes Jul 2, 2026
@chihsuan
chihsuan force-pushed the wooa7s-1642-widgets-normalize-file-conventions branch from f5eb64d to 06b623e Compare July 2, 2026 03:38
@github-actions github-actions Bot added the Docs label Jul 2, 2026
@chihsuan
chihsuan merged commit 438e23a into trunk Jul 2, 2026
73 checks passed
@chihsuan
chihsuan deleted the wooa7s-1642-widgets-normalize-file-conventions branch July 2, 2026 03:49
@github-actions github-actions Bot 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 Jul 2, 2026
kangzj added a commit that referenced this pull request Jul 2, 2026
Rename latest-post.module.css to style.module.css (post-#50112 convention)
and correct the normalizer docblock to reference the public WPCOM posts
endpoint rather than the proxy, since this widget fetches it directly.
kangzj added a commit that referenced this pull request Jul 3, 2026
…ts mock

Rename the widget CSS module to the post-#50112 style.module.css convention and
update the import. Replace the story-scoped apiFetch middleware with a central
stats/insights handler in routeStatsReport() backed by a data/insights.ts
fixture, matching the search-terms reference. Drop the now-unused api-fetch
devDependency.
kangzj added a commit that referenced this pull request Jul 3, 2026
* WOOA7S-1506: Port Stats Annual highlights widget

Add the Annual highlights Premium Analytics widget: a grid of metric tiles
showing the most recent year's totals (posts, words, likes, comments, images),
sourced from the useStatsInsights hook. The insights module is not
period-scoped and has no comparison period, so tiles render bare counts.

Includes the three-story Storybook template with a story-scoped apiFetch
middleware mocking the stats/insights endpoint (not covered by the shared
report mocks).

* Annual highlights: use style.module.css convention and central insights mock

Rename the widget CSS module to the post-#50112 style.module.css convention and
update the import. Replace the story-scoped apiFetch middleware with a central
stats/insights handler in routeStatsReport() backed by a data/insights.ts
fixture, matching the search-terms reference. Drop the now-unused api-fetch
devDependency.

* Annual highlights: redesign as the "in review" hero widget

Rework the widget to match the annual insights design: a Recoleta serif
"{year} in review" title with a "View all annual insights" link and an
"Updates every 30 minutes" subtitle, prev/next arrows that step through the
years the insights payload covers, and framed metric tiles for posts, words,
likes, and comments with compact serif totals.

Switch the presentation to full-bleed so the widget owns its full header
instead of the host card chrome, and make the tile grid responsive: four
across on wide widths with the value stacked under the icon and label, and
single-column rows (icon and label left, value right) on narrow widths. The
body scrolls when the content is taller than the tile so nothing is clipped
at the default 1x1 size. Format counts with formatNumberCompact so integers
stay bare (128, 342) while scaled totals keep one decimal (86.4K).

* Annual highlights: fix year navigation clamping and inert insights label

Step the prev/next handlers from the clamped index rather than the raw stored
index, so navigation still advances by one visible year if the insights payload
ever returns fewer years than the currently selected position.

Render "View all annual insights" as plain text instead of a hrefless Link:
until an annual-insights destination exists it should not present a
non-focusable, non-activatable link affordance.

* Annual highlights: remove the "View all annual insights" label for now

The dashboard has no annual-insights destination to link to yet, so drop the
label rather than ship inert action-oriented copy. Tracked in WOOA7S-1653 to
re-add it as a real link once a destination exists.

* Annual highlights: tokenize typography and drop the subtitle

Move the widget onto the design system so it matches the other dashboard
widgets and fits a 1x1 tile: render the title with Text variant="heading-md"
and the metric totals with the toolkit MetricWithComparison at a tokenized
fontSize, replacing the bespoke Recoleta @font-face and hard-coded 40/44px
display sizes. Spacing, border width, and radius now use --wpds-* tokens.

Remove the "Updates every 30 minutes" subtitle, and drop the now-unused
@automattic/number-formatters dependency (formatting goes through the toolkit
metric component).

* Annual highlights: add per-metric visibility settings and tune type scale

Add a checkbox setting per metric (Posts, Words, Likes, Comments) via
declarative boolean attributes, which the host renders as checkboxes in the
settings drawer; render.tsx reads them (defaulting to on) and hides the
matching tile, showing an empty-state message when none are selected. Story
gains matching controls to exercise the toggles.

Visual tuning: title moves to Text variant="heading-lg" to match the framed
widget titles (e.g. Top pages by views), the year arrows shrink from 24 to
18px, and the metric total nudges a little above the 2xl token for a stronger
hero read.

* Annual highlights: align metric checkboxes with render, shrink metric size

Give each metric-visibility field a getValue default of `?? true` so the
settings checkbox reflects the same "missing means enabled" default the render
uses. Without it, a metric absent from an instance's attributes showed as an
unchecked box while its tile still rendered, so toggling appeared to have no
effect.

Drop the metric total back to the 2xl token (removing the widget-local size
override), and let the dashboard story carry the real attribute schema so the
settings drawer exercises the checkboxes.

* Annual highlights: fall back the metric size token and shrink arrows

MetricValue emits the 2xl font-size token with no fallback and the dashboard
runtime does not always inject --wpds-typography-font-size-2xl, so the metric
total lost its size there. Pin it in the widget CSS with explicit fallbacks
(32px / 40px line-height). Also drop the year-arrow icons from 18 to 16px.

* Annual highlights: use the xl token for the metric total

* Annual highlights: align changelog with the shipped four metrics

* Annual highlights: drop image fields from insights mock, harden arrow disabled styles
kangzj added a commit that referenced this pull request Jul 6, 2026
Rename latest-post.module.css to style.module.css (post-#50112 convention)
and correct the normalizer docblock to reference the public WPCOM posts
endpoint rather than the proxy, since this widget fetches it directly.
kangzj added a commit that referenced this pull request Jul 6, 2026
…from stats/post (#50189)

* WOOA7S-1510: Port Stats Latest post widget

Add the "Latest post" Premium Analytics widget showing the site's most
recently published post with its all-time views, likes, and comments.

- Data: a `useStatsLatestPost` hook that fetches the public WPCOM posts
  endpoint directly (plain fetch, no proxy and no blog token), resolving the
  blog ID from the dashboard's client-side site data, then composes the
  post's all-time views from the existing proxied `useStatsPost` query. Adds
  the latest-post normalizer + fixtures/tests and the direct-fetch query.
- Widget: `widgets/latest-post/` renders the post title (external link),
  publish date, and Views / Likes / Comments metric tiles, with a
  three-story Storybook file (public posts endpoint stubbed via window.fetch).

* Address review: rename CSS module to style.module.css convention

Rename latest-post.module.css to style.module.css (post-#50112 convention)
and correct the normalizer docblock to reference the public WPCOM posts
endpoint rather than the proxy, since this widget fetches it directly.

* Latest post widget: local content + views/likes/comments from stats/post

Read the latest post's content from the local core /wp/v2/posts endpoint
instead of the unauthenticated WPCOM posts endpoint, so it resolves on
private/unlaunched sites. Source views, likes, and comment count from the
single stats/post call (comment_count rides its raw post payload; like_count
is the new field). A stats/post failure no longer blanks the widget — content
still renders with metrics zeroed.

* Latest post widget: featured image + token-based redesign

Fetch the post's featured image via core /wp/v2/posts _embed and render a
two-column card (content left, full-bleed featured image right) using DS
typography tokens (heading-2xl title, 2xl metric values) and a 'Published
<date>' line. Falls back cleanly when the post has no featured image.

* Latest post widget: match target layout with full-bleed featured image

Two-column card (content left, featured image bleeding to the card's right and
bottom edges), driven by container queries so it stacks to an image banner on
narrow tiles. Uses DS typography tokens (heading-2xl title, 2xl metric values),
a plain title link without the external-tab icon, and divs for the responsive
containers so layout is controlled entirely in CSS.

* Address Copilot review: decode title entities, tidy changelog

Decode HTML entities in the latest post's core title.rendered (via
@wordpress/html-entities) so encoded characters render correctly, add a test
for it, and reword the changelog in imperative mood.

* Move latest-post composition hook into the widget

The two-endpoint composition (local core content + Stats post metrics) is
specific to the Latest post widget, so it belongs with the widget rather than
the shared data layer. Move it to widgets/latest-post/use-latest-post.ts
(useLatestPost), and expose the single-endpoint primitives it composes from
(statsLatestPostQuery, useStatsQuery) from the data package's public API.

* Rename latest-post data pieces to drop the misleading 'stats' naming

The latest-post query reads core /wp/v2/posts content, not stats, so drop the
'stats' prefix: statsLatestPostQuery -> latestPostQuery, and move the normalizer
out of processing/stats into its own processing/latest-post domain
(sanitizeLatestPostResponse, LatestPost, LatestPostResponse). No behavior change.

* Latest post widget: responsive metric typography

Render the lifetime metric values with MetricValue (value-only, no comparison)
and size them via a core typography token with a fallback. Scale the headline
and metric numbers down and tighten spacing on narrow tiles via container
queries so content fits small grid cells without overflowing. Expose MetricValue
from the widgets-toolkit barrel.

* Latest post widget: tighten narrow title line-height, add standard line-clamp

Pair the narrow headline's smaller font-size with a matching line-height token so
its line spacing isn't inherited from the 2xl heading scale, and add the standard
line-clamp property alongside the -webkit- prefixed one.

* Address Copilot review: lockfile, unused dep, new-tab title, changelog

- Reset pnpm-lock.yaml to trunk's registry-format (drop 2511 stray tarball URLs a
  custom registry had injected) and add only the @wordpress/html-entities importer
  entry, fixing the 'Lock files are up to date' check.
- Drop the now-unused @automattic/jetpack-script-data dependency from the data
  package (the removed blog-id lookup was its only consumer).
- Restore openInNewTab on the latest post title link, inline within the heading, to
  match Top posts and the PR's testing instructions.
- Reword the widget changelog to be user-facing.

* Latest post widget: fix featured image bleed on real dashboard

The widget's own .root declared container-type, creating a nested container:
.root's row layout responded to the outer WidgetRoot 'widget' container while
the .media bleed margins responded to the inner one. When only the outer crossed
the breakpoint (as in the live dashboard grid) the image rendered in the two-column
layout without bleeding, leaving gaps. Drop .root's container-type and point every
container query at the named 'widget' container so the layout switch and the
edge-bleed always apply together.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants