Add video captions validation check for core/video block

[huzaifaalmesbah]

What?

Closes #30

This PR adds a new WCAG-oriented validation check check_video_tracks for the core/video block in the Core block accessibility rules module.

Why?

Under WCAG 2.1 Success Criterion 1.2.2 (Captions - Prerecorded - Level A), prerecorded videos containing audio dialogue and relevant sounds must provide synchronized text captions or subtitles so that deaf or hard-of-hearing users can consume the media content.

Currently, the Core block accessibility rules module does not validate core/video blocks. Introducing an advisory warning check reminds content authors to provide caption tracks without blocking the post publishing flow.

How?

• PHP Registration: Registered check_video_tracks under core/video in includes/Modules/Features/Core_Block_Validation_Rules.php at level: warning.
• JS/TS Validation: Implemented src/editor/core-block-rules/video.ts and connected it in src/editor/core-block-rules/index.ts. It inspects attributes.tracks to ensure at least one track with kind === 'captions' or kind === 'subtitles' and a valid src is present.
• Graceful Unconfigured State: If an empty core/video block is inserted without an attached video source (src or id), the check passes cleanly to avoid premature false-positive warnings.
• Settings Integration: Automatically appears in the Validation admin table under Settings → Accessibility Lab → Validation, allowing site administrators to adjust severity (error, warning, or none).
• Documentation: Updated README.md, readme.txt, and docs/features/validation-api.md to document core/video support.

Testing Instructions

1. Open the block editor (Posts → Add New Post).
2. Insert a Video block (/video) and attach a video file or external URL.
3. Leave the text tracks empty.
4. Open the Validation sidebar panel.
   • Expected: The video block displays an amber/yellow warning outline (validation-api-block-warning), and the sidebar displays:

     Consider adding captions or subtitles to this video. (core/video)

5. In the block toolbar, click Text tracks and upload/select a WebVTT caption file (or configure a captions/subtitles track).
   • Expected: The yellow warning outline immediately clears and the sidebar reports all checks passed (0 errors, 0 warnings).

Testing Instructions for Keyboard

1. Navigate to the block editor using keyboard (Tab).
2. Insert a Video block using the slash command (/video).
3. Attach a video file and tab away without setting text tracks.
4. Use Tab / Shift+Tab to navigate to the editor header and activate the Validation sidebar button.
5. Verify the warning is announced and reachable via keyboard navigation.
6. Return focus to the Video block toolbar, trigger Text tracks, add captions, and verify the warning is dismissed.

Screenshots or screencast

Before (No caption track)	After (Caption track added)

Use of AI Tools

AI assistance: Yes
Tool(s): Google Antigravity
Used for: Architecture analysis, TypeScript/PHP implementation, local testing & validation in browser, and PR formatting. Reviewed and verified locally.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: huzaifaalmesbah <[email protected]>
Co-authored-by: troychaplin <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[troychaplin]

Thanks for the contribution, @huzaifaalmesbah, the implementation looks solid.

Unlike the table caption check, this one's citing an actual Level A success criterion (1.2.2), so a missing caption on a video with dialogue or relevant audio is a genuine conformance failure, not just a best-practice suggestion. That makes warning a reasonable floor here — I'd actually lean toward discussing whether this should default to error, given Level A is the baseline most sites are expected to meet.

One thing I'd want to confirm before merging: does the check have any way to distinguish videos with meaningful audio from silent/decorative video? Right now it looks like any core/video block without a captions/subtitles track will trigger the warning regardless of whether the video has audio worth captioning — which could produce false positives on silent or ambient-only video.

[huzaifaalmesbah]

Thanks @troychaplin! Good question. Block attributes don't tell us whether a video has audio, so the check can't reliably tell a video with dialogue from a silent one. That's why I kept the default at warning rather than error.

In d0a7d55 I added a heuristic for the clearest case: a video that autoplays, is muted, loops and has controls hidden is treated as a background/decorative clip and isn't flagged. I also count tracks saved without a kind, since <track> defaults to subtitles. Rebased on main as well.

If the team prefers error given that 1.2.2 is Level A, it's a one-line change.