Stats v2: Add thumbnails to the video lists

[adamwoodnz]

Fixes https://linear.app/a8c/issue/STATS-513

Why

In classic Stats, each video row starts with its thumbnail, so site owners can spot a video at a glance. Stats v2 showed no thumbnail in the VideoPress widget, and an unlinked one in the Videos report. Both lists now show the video's poster as a square, as the Stats v2 prototype does, and clicking it opens the video's detail page, like the title does. The detail page marks its poster with a play icon, also from the prototype.

Proposed changes

Builds on #52909 (merged), which moved the widget to the VideoPress package.

• Top videos widget (packages/videopress): each row shows the video's poster as a 28 × 28px square before its title, inside the same link. A video with no poster, or whose poster fails to load, shows a bordered placeholder with the video icon, so titles stay aligned. The prototype's widget shows no thumbnails; we keep them on purpose.
• Videos report: 32 × 32px posters, as in the Posts & Pages report, linked to the video detail page. The report passes isItemClickable and renderItemLink, so DataViews links the poster and the title itself. Rows without a video ID are not clickable, and their title keeps the external page link.
• Video detail page: the 72 × 72px header poster gets the prototype's dark scrim and white video icon. A missing or broken poster still shows the plain video icon.
• ReportRecordsTable: a @wordpress/ui Link zeroes border-radius on hover, which squared the report's linked poster. The table restores DataViews' radius on media links, for every report that uses renderItemLink.
• Shared getVideoPosterUrl helper (widgets-toolkit): checks the URL with safeHttpUrl and asks Photon for the poster at twice its drawn size. The report uses it in place of its local copy, and the SDK exports it for the widget.
• VideoTitleLink gains a children slot, and the toolkit exports InternalLink (from Premium Analytics: add shared internal and external link components to the widgets toolkit #53043) for the report's row link. Video leaderboard rows (videoLink) now render their media inside that link; before this change they dropped it.
• Leaderboard thumbnail media accepts a fallbackIcon, drawn in place of the grey placeholder when there is no image or it fails to load. Thumbnails are held at 1:1, because the dashboard shell's img { height: auto } overrides a fixed height and would draw a landscape poster short.
• Storybook: the video-plays mock gains posters, including one null poster (a private video) and one that fails to load.

Private videos: the stats API returns poster: null for them (STATS-412), so they show the placeholder without a failed request.

Screenshots

Local site with two videos: "Osaka at night" has a poster; the other's poster does not load, so it shows the placeholder.

Top videos widget (VideoPress package)

Videos report

Video detail header

What a reviewer should check

• Rows without a valid video ID: the report poster is not a link, and the widget row keeps its external or plain fallback with the poster inside.
• Decisions made during the build that you may want to overrule:
  • Squares crop landscape posters to their centre. Nothing in the stats data says whether a video is landscape or portrait, so one shape serves both.
  • The scrim and icon on the detail poster use fixed colours (rgba(0, 0, 0, 0.28), white), not WPDS tokens: they sit on a photo, not a themed surface, and WPDS has no scrim token.
  • The widget placeholder's hairline uses --wpds-color-stroke-surface-neutral; DataViews' report placeholder hard-codes rgba(0, 0, 0, 0.1), a shade lighter.
  • The positive-integer video ID check is repeated in three places: the report's isVideoRowClickable, VideoTitleLink, and the widget row builder. Merging them is left for a follow-up.
  • Storybook mock posters load from picsum.photos. They are story-only and show placeholders when offline.

Verification

• Jest passes in Premium Analytics (all 3932 tests) and in VideoPress (widgets/top-videos). Typecheck, ESLint and stylelint pass, and both packages build.
• Local site on real Stats data, one video with a poster:
  • Videos report: the poster is 32 × 32px with a 4px radius, which now holds on hover and keyboard focus; the focus ring follows it. Clicking the poster opens /video/<id>.
  • Video detail page: the poster is 72 × 72px, and the scrim and icon cover it with the icon centred. Post detail pages keep their square header unchanged.
  • Dashboard widget: the poster draws 28 × 28px, requested from Photon at 56 × 56px, and the video without a poster shows the 28 × 28px placeholder.
• Not verified: a truly private video. The test site's "private" video is set to the site default, which is public, so its poster loads.

Related product discussion/links

• STATS-407 (classic Stats thumbnails), STATS-412 (poster on stats/video-plays)
• Follows Premium Analytics: Add video thumbnails and drop "report" from report headings #52908, which added the square report thumbnail

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

No.

Testing instructions

• On a site with VideoPress videos that have plays in the selected range, open Stats v2:
  • Dashboard › Top videos widget: square posters show before titles, and clicking one opens the video detail page. Titles stay aligned, and tabbing through the list stops once per row.
  • Videos report (/reports/videos): posters are 32 × 32px squares and keep their rounded corners on hover. Clicking a poster opens the detail page with the same date range as the title. The poster and the title are separate tab stops, and the poster link is named after the title.
  • Video detail page: the header poster shows the video icon over a dark scrim.
  • A private video shows the placeholder.
  • Posts & Pages report: thumbnails and placeholders are unchanged.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UZjr8dPvykFAD46sUK54zL

[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), and enable the stats-513-stats-v2-add-thumbnails-to-the-video-lists branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack stats-513-stats-v2-add-thumbnails-to-the-video-lists

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!

---

Jetpack 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.

---

Videopress 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.

---

Mu Wpcom plugin:

• Next scheduled release: WordPress.com Simple releases happen semi-continuously (PCYsg-Jjm-p2)

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.

[adamwoodnz]

Codex review

No correctness, security, accessibility, or contract issues were identified in the branch changes.

[adamwoodnz]

@claude please review this PR. Get the change set with a single gh pr diff 53011, 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 1m 13s —— View job

---

Review of PR #53011: video poster thumbnails

• Fetch the diff (gh pr diff 53011)
• Read the changed source files (changelog entries skipped)
• Post review

Verdict: I found no blocking issues. The change is small and well tested, and the poster markup is accessible. Below are a few things I checked and some optional nits.

What I checked

• URL safety: getVideoPosterUrl (packages/widgets-toolkit/src/helpers/video-plays.ts:43) runs safeHttpUrl before calling new URL(). A bad or non-string poster returns undefined and never throws. The tests cover javascript:, null, '' and numbers. An existing query string is kept.

• Report poster link (routes/reports/videos/config/fields.tsx:62): tabIndex={-1} together with aria-hidden is valid. Because the link can't take keyboard focus, it doesn't break axe's aria-hidden-focus rule. The Videos page sets no isItemClickable or renderItemLink, so DataViews won't wrap the media cell in a second link and you don't get a link inside a link. Passing getVideoDetailSearch as the search function matches how VideoTitle already does it, so the poster and the title carry the same date range.

• LeaderboardRow videoLink branch (leaderboard-row.tsx:127): all three fallbacks match the non-title-link path.

  • Internal links and external links both wrap LeaderboardLabel with decorativeMedia.
  • Plain rows use a styles.row span.

  The accessible name stays the title, because the image has alt="". The only other videoLink caller, the WithMediaAndLinks story, passes no media, so turning media on for videoLink changes nothing anywhere else.

• VideoDetailLink extraction: this is a clean refactor. VideoTitleLink's output is unchanged when no children are passed.

• Changelog entries: there are entries for the package, plugins/premium-analytics and plugins/jetpack (with the Premium Analytics: prefix). That fits the AGENTS.md rules, since Jetpack users see Stats v2.

Nits and suggestions (optional)

1. ReportThumbnail placeholder sizing (report-thumbnail.module.scss:4-7): inline-size: 100% and block-size: 100% only work because DataViews gives the media cell a definite size. Both current callers, Posts and Videos, render inside that cell, so this is fine today. The component README still describes it as a "records-table row thumbnail", so it may help to add a line saying it fills its media box.
2. README table (chart-leaderboard/README.md:215): the new thumbnail row is much wider than the others, so the column pipes no longer line up. Either move the 16:9 detail into a sentence under the table, or shorten the cell to something like 28 × 28px (16:9: 50 × 28px).
3. Photon resize on any host: getVideoPosterUrl adds ?resize= to whatever host the poster comes from. That's harmless: i0.wp.com and *.files.wordpress.com honour it, and other hosts ignore it. The JSDoc says "resized by Photon", though, so "resized via Photon-style resize param" would be more accurate if posters can come from elsewhere.
4. Positive-integer ID check now in three places: the report poster, VideoTitleLink and the widget row builder. You already flagged this as a follow-up. A small toVideoId( id ): number | undefined helper next to getVideoPosterUrl would be a natural home for it.
5. Thumbnail fit: .thumbnailWide uses object-fit: cover, so a non-16:9 poster (e.g. a vertical video) gets centre-cropped. That's reasonable at this size; I'm only mentioning it so it's a deliberate choice.

Not verified

• The repo's node_modules aren't installed in this checkout, so I couldn't confirm against the installed @wordpress/dataviews types that the table layout honours layout.aspectRatio. The PR description says it was checked in the browser (57 × 32 box), and page.test.tsx checks that the setting is passed through.
• I didn't run Jest or the linters. This was a read-only review kept to the requested tool budget.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 2 files.

File	Coverage	Δ%	Δ Uncovered
projects/packages/premium-analytics/packages/widgets-toolkit/src/components/chart-leaderboard/leaderboard-row.tsx	19/19 (100.00%)	0.00%	0 💚
projects/packages/premium-analytics/packages/widgets-toolkit/src/components/chart-leaderboard/leaderboard-label.tsx	16/16 (100.00%)	14.29%	-2 💚

1 file is newly checked for coverage.

File	Coverage
projects/packages/premium-analytics/packages/widgets-toolkit/src/helpers/video-poster-url.ts	6/6 (100.00%) 💚

Full summary · PHP report · JS report

[adamwoodnz]

Responses to Claude's nits:

1. ReportThumbnail placeholder: not changed. Its JSDoc ("A records-table row thumbnail, rendered by the view's mediaField") already ties it to the DataViews media cell, and both callers render there.
2. README table: fixed in e362438. The cell is now 28 × 28px (16:9: 50 × 28), and the sizing note sits in a sentence under the table.
3. Photon wording: not changed. Posters come from the WordPress.com video CDN or Photon, and both honour resize.
4. Duplicated video ID check: left for a follow-up, as the PR description notes.
5. object-fit: cover: deliberate. A poster in a non-16:9 shape is centre-cropped to fill the slot, so titles stay aligned.

[adamwoodnz]

Review cycle summary

• Round reviewer: Codex, 1 round. It found no issues, so the round phase ended early.
• Final reviewer: Claude, 1 round. No blocking issues and 5 optional nits:
  • Fixed: the README table alignment (e362438).
  • Answered with reasons: the other 4.
• CI: all checks passed on c565d2c. The README-only push e362438 started a new run.
• Inline review threads: none.
• Unaddressed human comments: none.

Status: clean. Ready for human review.

[Nikschavan]

I left a few observations inline. None of them block this.

What I checked: I loaded the VideoPress widget and the Videos report from this branch on a site with real VideoPress posters. In the widget, the posters render at 50×28 inside each row link and open the video detail page. In the report, the poster boxes are 57×32 and the poster link stays out of the tab order. In Storybook, the null poster and the broken poster both fall back to the placeholder, and each row stays 36px tall.

VideoPress widget	Videos report

[chihsuan]

Thanks for adding the posters! @adamwoodnz Left a few inline notes, mainly on the report poster click.