feat(site): add media element API reference pages#1342
feat(site): add media element API reference pages#1342
Conversation
Add generateMediaElementReferences() to the builder entry point so `pnpm api-docs` generates JSON for media elements (hls-video, dash-video, mux-video, mux-audio, native-hls-video, simple-hls-video). Register a new mediaReference content collection in Astro with a Zod schema matching the pipeline output. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
Create MediaReference.astro that loads generated media element JSON and renders Host Properties, Native Attributes, Events, CSS Custom Properties, and Slots sections. Add mediaReferenceModel.js for shared heading/id computation. Wire into remarkConditionalHeadings for table-of-contents injection. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
Create 7 MDX reference pages: hls-video, dash-video, native-hls-video, simple-hls-video, mux-video, mux-audio (auto-generated via MediaReference), and background-video (hand-authored tables). Add "Media Elements" sidebar section between Components and Hooks & Utilities. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
Add BasicUsage demos (HTML + React) for hls-video, dash-video, native-hls-video, simple-hls-video, mux-video, mux-audio, and background-video. Wire demos into each MDX page using FrameworkCase and StyleCase components. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
The React media components (`@videojs/react/media/*`) import from `@videojs/core/dom/media/*` which top-level imports dashjs/hls.js — libraries that access `window` at module load time. This crashes Astro's SSR prerender. Remove all demos until the underlying SSR issue is resolved. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
…lan-ClRzU # Conflicts: # .gitignore # site/scripts/api-docs-builder/src/index.ts # site/src/content.config.ts # site/src/utils/remarkConditionalHeadings.js
Add BasicUsage demos (HTML + React) for hls-video, dash-video, native-hls-video, simple-hls-video, mux-video, mux-audio, and background-video. Wire demos into each MDX page. Note: React demos currently break the SSR build due to #1343 (top-level hls.js/dashjs imports access `window`). This branch is parked until that issue is resolved. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
The React demos for HLS, DASH, Mux, NativeHLS, and SimpleHLS media elements import from @videojs/react/media/* which chains into top-level hls.js/dashjs imports that access `window` at module evaluation time, breaking Astro's SSR prerender. HTML demos and background-video React demo are unaffected. Refs #1343 https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
📦 Bundle Size Report🎨 @videojs/html — no changesPresets (7)
Media (8)
Players (3)
Skins (29)
UI Components (25)
Sizes are marginal over the root entry point. ⚛️ @videojs/react — no changesPresets (7)
Media (7)
Skins (26)
UI Components (20)
Sizes are marginal over the root entry point. 🧩 @videojs/core — no changesEntries (9)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (10)
📦 @videojs/spf — no changesEntries (3)
ℹ️ How to interpretAll sizes are standalone totals (minified + brotli).
Run |
|
@cursor review |
![cursor[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 1e05bd7. Configure here.
Move custom properties before regular properties per useSortedProperties rule. Add aspect-ratio: 16/9 to video demos to prevent flat layout before video loads. Mux-audio excluded (audio element). https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
Switch to the standard BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM playback ID used by all other demos. Update DASH URL per reviewer preference. Add predefined height to mux-audio demos to prevent layout shift. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
|
I found two docs-generation issues that look worth fixing before this lands:
I tried to leave these as inline review comments, but GitHub would not anchor them because this file is not currently part of the PR diff. |
Match the convention used in existing HTML demos (e.g. play-button) where each attribute is on its own line for readability. https://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
|
One docs-content suggestion for the media reference pages: the generated Native Attributes and Events chip lists may be less useful than a short explanation of the forwarding behavior. For attributes, the accurate statement is not quite “all native attributes are forwarded,” but rather that these elements accept common native media attributes and forward the supported set from
For events, the runtime behavior is more useful than the exhaustive list: native media events are re-dispatched from the internal media element, so consumers can listen on the custom element directly. Something like: el.addEventListener('play', onPlay);
el.addEventListener('timeupdate', onTimeUpdate);Then list the element-specific events separately, e.g. for HLS/native HLS:
That would probably read better than a large wall of event chips like |
2 participants
Summary
generateMediaElementReferences()into the api-docs builder sopnpm api-docsgenerates JSON for 6 media elements (hls-video, dash-video, mux-video, mux-audio, native-hls-video, simple-hls-video)MediaReference.astrorendering component with Host Properties table, Native Attributes, Events, CSS Custom Properties (reusesApiCSSVarsTable), and Slots sections<MediaReference>+ background-video (hand-authored)Closes #1253
Test plan
pnpm api-docsgenerates 6 JSON files ingenerated-media-reference/pnpm typecheckpassespnpm -F site test— 374 tests passpnpm check:workspace— 6/6 checks passpnpm devhttps://claude.ai/code/session_01GLtyequo6D3zqeddxsBjzQ
Note
Medium Risk
Medium risk because it changes the docs generation pipeline (
api-docs-builder) and TOC heading injection logic, which could break site builds or navigation if the generated JSON/schema or heading IDs drift.Overview
Adds first-class media element API reference support to the docs site.
The
api-docs-buildernow generates and schema-validates media element reference JSON into a newgenerated-media-reference/output, which is wired intoastro:contentvia a newmediaReferencecollection and ignored in.gitignore.Introduces a
MediaReference.astrorenderer (including aMediaHostPropsTable) plus amediaReferenceModeland updatesremarkConditionalHeadingsso<MediaReference media="..." />injects API Reference headings into the page TOC.Adds a new “Media Elements” sidebar section and new reference pages/demos for
background-video(hand-authored) and streaming elements (dash-video,hls-video,mux-audio,mux-video,native-hls-video,simple-hls-video), with React demos currently commented out on several pages due to SSR import issues.Reviewed by Cursor Bugbot for commit ef5aa9d. Bugbot is set up for automated code reviews on this repo. Configure here.