Repository navigation
refactor(react,html)!: make every stable type importable from the framework packages - #3082
Conversation
- Name core's standalone state and props types (`PlayButtonState`, `PlayButtonProps` imported as `CorePlayButtonProps`, …) in React props interfaces, part namespaces, contexts, and HTML elements instead of `*Core.State` / `*Core.Props`, so no public signature names a `*Core` class. `Menu.Root` and the popover/tooltip elements spell out the `Omit<…, 'boundary'>` aliases core keeps private. - Parameterize `MediaButtonElement` and `MediaUIElement` by component state and media state instead of the core class; the core-typed `core` member stays protected. Button elements now extend `MediaButtonElement<PlayButtonState, MediaPlaybackState>` and so on. - Re-export core's `TimeSliderChapterState` from React rather than aliasing it. - Mark `MenuContextValue.core` and `TooltipOptions.group` `@internal`: both carry a core instance only framework parts supply or read. Type-only: no runtime behaviour changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
- Spell out `PlayerElementConstructor`'s constructor type instead of `Constructor` from `@videojs/utils/types`. - Merge feature configs in `UnionPlayerConfig` and `UnionPlayerHtmlConfig` with a local `MergedConfig` helper instead of `Simplify<UnionToIntersection<…>>`. - Move `EventType`, `EventListenerFor`, and `QueriedElement` from `@videojs/utils/dom` into the HTML media adapter, their only user, as local types. - Annotate the preset skins' `static styles` as `CSSStyleSheet | string` rather than inferring `ShadowStyle`. - Type `StatusIndicatorState.status` as `IndicatorStatus | null` instead of deriving it from `deriveStatus`, which resolves to the same type. Type-only: no runtime behaviour changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Each `@videojs/react/media/<name>` and `@videojs/html/media/<name>` entry now re-exports, type-only, the adapter types its media's props name: the adapter props, source and engine config types, and, for embeds whose event props type `currentTarget` as the adapter, the adapter class and its player API types. Mux entries re-export the Mux source and adapter props types for their engine flavor. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Re-export, type-only, the core and media types that stable components, elements, selectors, and predicates name, so each can be imported from `@videojs/react` or `@videojs/html`: - component state, props, option, and enum types from `@videojs/core` (`PlayButtonState`, `SliderState`, `PopoverSide`, `TransitionStatus`, …) and `TextParams`, `TranslationKey`, `TranslationOptions` from `@videojs/core/i18n`; - media state, capability, event, and track types from `@videojs/media` (`MediaPlaybackState`, `MediaVolumeCapability`, `MediaTextTrack`, `CommonMedia`, `MediaResolution`, …). `@videojs/html` exports the full set. `@videojs/react` leaves out the names its own components already use: the core `*Props` it extends under the same name (`PlayButtonProps`, `GestureProps`, `ThumbnailImageProps`, …), `SliderPreviewProps` (`Slider.PreviewProps`), the `Text` type (the `Text` component), and media's `Video` interface (the `Video` component of `@videojs/react/video`). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@videojs/cdn
@videojs/cli
@videojs/core
@videojs/element
@videojs/html
@videojs/media
@videojs/react
@videojs/spf
@videojs/store
@videojs/utils
@videojs/cloudflare-video
@videojs/dash-video
@videojs/hlsjs-video
@videojs/mux-audio
@videojs/mux-video
@videojs/native-hls-video
@videojs/shaka-video
@videojs/spotify-audio
@videojs/tiktok-video
@videojs/twitch-video
@videojs/vimeo-video
@videojs/wistia-video
@videojs/youtube-video
@videojs/google-cast
@videojs/mux-data
commit: |
📦 Bundle Size Report🎨 @videojs/html — 27 small size changes
Presets (7)
Media (18)
Players (5)
Skins (41)
UI Components (62)
⚛️ @videojs/react — no changesPresets (7)
Media (22)
Extensions (2)
Players (5)
Skins (26)
UI Components (39)
🧩 @videojs/core — no changesEntries (76)
🏷️ @videojs/element — no changesEntries (2)
📦 @videojs/store — no changesEntries (3)
🔧 @videojs/utils — no changesEntries (13)
📦 @videojs/cdn — no changes📦 @videojs/cloudflare-video — no changes📦 @videojs/dash-video — no changes📦 @videojs/google-cast — no changes📦 @videojs/hlsjs-video — no changes📦 @videojs/media — no changesEntries (3)
📦 @videojs/mux — no changes📦 @videojs/mux-audio — no changesEntries (2)
📦 @videojs/mux-data — no changes📦 @videojs/mux-video — no changesEntries (2)
📦 @videojs/native-hls-video — no changes📦 @videojs/shaka-video — no changes📦 @videojs/spf — no changesEntries (7)
📦 @videojs/spotify-audio — no changes📦 @videojs/tiktok-video — no changes📦 @videojs/twitch-video — no changes📦 @videojs/other — 1 small size change
Entries (3)
📦 @videojs/vimeo-video — no changes📦 @videojs/wistia-video — no changesEntries (2)
📦 @videojs/youtube-video — no changesℹ️ How to interpretEach entry is independently bundled, minified, and brotli-compressed. Initial size includes its static import graph; lazy dynamic chunks are reported separately. Entries are not additive because their dependency graphs overlap. Preset rows represent realistic combined bundles. Changes of 300 B or less across initial, lazy, and total size are collapsed, not discarded. Run |
…arthy-7ams8m-exports # Conflicts: # packages/core/src/core/ui/status-indicator/core.ts # packages/html/src/ui/status-indicator/element.ts # packages/react/src/index.ts # packages/react/src/ui/airplay-button/component.tsx # packages/react/src/ui/audio-track-radio-group/component.tsx # packages/react/src/ui/audio-track/use-audio-track-options.ts # packages/react/src/ui/buffering-indicator/component.tsx # packages/react/src/ui/captions-button/component.tsx # packages/react/src/ui/captions-radio-group/component.tsx # packages/react/src/ui/captions-radio-group/use-captions-options.ts # packages/react/src/ui/cast-button/component.tsx # packages/react/src/ui/controls/backdrop.tsx # packages/react/src/ui/controls/content.tsx # packages/react/src/ui/controls/group.tsx # packages/react/src/ui/controls/root.tsx # packages/react/src/ui/dialog/backdrop.tsx # packages/react/src/ui/dialog/close.tsx # packages/react/src/ui/dialog/context.tsx # packages/react/src/ui/dialog/description.tsx # packages/react/src/ui/dialog/popup.tsx # packages/react/src/ui/dialog/title.tsx # packages/react/src/ui/dialog/trigger.tsx # packages/react/src/ui/error-dialog/close.tsx # packages/react/src/ui/error-dialog/description.tsx # packages/react/src/ui/error-dialog/title.tsx # packages/react/src/ui/fullscreen-button/component.tsx # packages/react/src/ui/live-button/component.tsx # packages/react/src/ui/menu/root.tsx # packages/react/src/ui/mute-button/component.tsx # packages/react/src/ui/pip-button/component.tsx # packages/react/src/ui/play-button/component.tsx # packages/react/src/ui/playback-rate-button/component.tsx # packages/react/src/ui/playback-rate-radio-group/component.tsx # packages/react/src/ui/popover/context.tsx # packages/react/src/ui/poster/image.tsx # packages/react/src/ui/poster/root.tsx # packages/react/src/ui/quality-radio-group/component.tsx # packages/react/src/ui/quality/use-quality-options.ts # packages/react/src/ui/seek-button/component.tsx # packages/react/src/ui/seek-indicator/context.tsx # packages/react/src/ui/seek-indicator/root.tsx # packages/react/src/ui/seek-indicator/value.tsx # packages/react/src/ui/slider/root.tsx # packages/react/src/ui/slider/thumbnail/root.tsx # packages/react/src/ui/status-announcer/component.tsx # packages/react/src/ui/status-indicator/context.tsx # packages/react/src/ui/status-indicator/root.tsx # packages/react/src/ui/status-indicator/value.tsx # packages/react/src/ui/thumbnail/context.tsx # packages/react/src/ui/thumbnail/image.tsx # packages/react/src/ui/thumbnail/root.tsx # packages/react/src/ui/time-slider/root.tsx # packages/react/src/ui/time/value.tsx # packages/react/src/ui/tooltip/context.tsx # packages/react/src/ui/volume-indicator/context.tsx # packages/react/src/ui/volume-indicator/fill.tsx # packages/react/src/ui/volume-indicator/root.tsx # packages/react/src/ui/volume-indicator/value.tsx # packages/react/src/ui/volume-popover/context.tsx # packages/react/src/ui/volume-popover/root.tsx # packages/react/src/ui/volume-slider/root.tsx
… types MediaStreamType, MediaReadyStateValue, PlaybackType, and SourceType are now literal unions instead of lookups into the MediaStreamTypes, MediaReadyState, PlaybackTypes, and ContentTypes constants, so the framework packages no longer re-export those constants as types that can't be used as values. PlaybackType and SourceType keep accepting any string. BREAKING CHANGE: `ContentTypes`, `PlaybackTypes`, `MediaReadyState`, and `MediaStreamTypes` are no longer re-exported (type-only) from `@videojs/react`, `@videojs/html`, or their hlsjs-video media entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
…arthy-7ams8m-exports
…t types Every type a stable export reaches, including through mixin bases and local helpers, is now importable from @videojs/react or @videojs/html: the adapter classes and Mux adapter types from each /media/* entry, the media track and engine adapter contracts and WithMediaTracks from the roots, and SliderInput from @videojs/react. The #3064 status indicator types are re-exported from both roots. DialogElementBaseOptions.core and .stateAttrMap are @internal, and hls-background-video declares its lifecycle callbacks locally. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
…arthy-7ams8m-exports
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview for vjs-registry ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…arthy-7ams8m-exports
…arthy-7ams8m-exports
decepulis
left a comment
There was a problem hiding this comment.
Agent review (part of the stack review; see #3063 for method). pnpm typecheck passes at the top of the stack, every added root/entry export is export type, MergedConfig is structurally the same as Simplify<UnionToIntersection<…>>, the written-out unions match the constants they replaced, all nine MediaButtonElement subclasses pass matching <State, MediaState> args, 'use client' is present per module and absent from the barrels, and the @videojs/utils/dom removals have no remaining users.
One inline 🔴 (MediaError exported type-only although it's a class). Two things that follow from the #3063 heuristic comments rather than from this diff:
- The root re-exports of core's
ButtonOptions,DialogOptions,GestureOptions,HotkeyOptions,MenuOptions,PopoverOptions,TooltipOptions(andPopupGroup*,TransitionApi,TransitionElementthat they drag in) exist only because the checker's companion heuristic marked them stable. Once that's fixed on #3063 these should come back out and be tagged@internalin #3068, since rahim's answer 6 keeps thecreate*controllers internal. - 🟣 Decision for rahim: the adapters' undocumented
get engine()getters make the hand-written third-party typings stable and re-exported from the/media/*entries:YouTubePlayerApi,CloudflareStreamPlayerApi,SpotifyControllerApi/SpotifyPlaybackUpdateEvent. The media pages documentsource.engine.*options, not theenginegetter. Tagging the getter@internal(the checker honours member tags) would keep them out of the stable set; keeping them means committing to those typings.
Description nits (no code change): the "removed type-only re-exports of ContentTypes/PlaybackTypes/MediaReadyState/MediaStreamTypes" bullet doesn't match the diff (no re-export of those names is removed; only the alias bodies changed and the constants are still exported from their packages), and StatusIndicatorState.status: IndicatorStatus | null is pre-existing. The real breaking changes are the MediaButtonElement/MediaUIElement generics and the three @videojs/utils/dom removals. Optional: MuxSourceBase.playback/poster/storyboard are typed with MuxPlaybackParams/MuxPosterParams/MuxStoryboardParams, which no package exports, so users can't name them from a framework entry; rahim accepted private helper types (G), but these look like contracts people will want to spell.
Generated by Claude Code
…arthy-7ams8m-exports
|
Resolving the 🟣 item in my review above: the adapter Generated by Claude Code |
…arthy-7ams8m-exports
…arthy-7ams8m-exports
…arthy-7ams8m-exports
…arthy-7ams8m-exports
…arthy-7ams8m-exports
…arthy-7ams8m-exports # Conflicts: # packages/html/src/presets/audio/minimal-skin.ts # packages/html/src/presets/live-audio/minimal-skin.ts # packages/html/src/presets/live-video/minimal-skin.ts # packages/html/src/presets/video/minimal-skin.ts
…arthy-7ams8m-exports # Conflicts: # packages/react/src/ui/seek-indicator/root.tsx
…arthy-7ams8m-exports
…arthy-7ams8m-exports
…arthy-7ams8m-exports
Part 5 of the API stability stack: #3073 → #3063 → #3066 → #3067 → this PR → #3068 → #3083.
Summary
The checker in #3063 makes stability transitive: a type named in a stable export's public signature is stable too, including through protected members, local helpers and mixin
_baseconstants. It also requires every stable export to be importable from@videojs/react,@videojs/html,@videojs/storeor an extension package. Before this PR, 320 stable exports could only be imported from@videojs/core,@videojs/media,@videojs/utilsor an adapter package. After it, none are left.Maintainer decisions this follows:
*Coreclasses stay internal.Apart from exporting
MediaErroras a value, all changes are type-only.XState/XPropstypes instead ofXCore.State/XCore.Props.PlayButton.StateandPlayButton.Propsstill work. The React context values for dialog, menu, popover and tooltip keep acoremember; they aren't documented, and chore: tag undocumented public exports @internal and enforce it in CI #3068 tags them@internal. The thumbnail context isn't exported.corestays protected and is typed withMediaButtonComponent/MediaUIComponent, which@videojs/htmlnow re-exports as types along withUIComponent, so a subclass can name what it implements.Constructoris written out in place.SimplifyandUnionToIntersectionare replaced by a localMergedConfigtype.html-media-adapter.ts, their only user.static styles: CSSStyleSheet | stringinstead ofShadowStyle.hls-background-videodeclares its lifecycle callbacks locally instead of using utils'CustomElement.MediaStreamType,MediaReadyStateValue,PlaybackTypeandSourceTypeare literal unions instead of lookups into constants.PlaybackTypeandSourceTypestill accept any string. The constants themselves are still exported from their packages.@internal:MenuContextValue.core,TooltipOptions.group, andDialogElementBaseOptions.core/.stateAttrMapLiveButtonElement.core, andInputIndicatorElement'stransitionandcontainer: element internals whose types would otherwise become stable through protected members@videojs/{react,html}/media/*entry: YouTube, Cloudflare, Spotify, TikTok, Twitch, Vimeo, Wistia, DASH, Shaka, hls.js, native HLS and Mux. That includes the adapter classes the media elements extend (HlsJsAdapter,DashAdapter,MuxVideoAdapter, …) and the MuxMuxAdapterAPI,MuxContentDataandMuxPosterFitModetypes. The adapters'enginegetters stay stable, because the migration guides point toengineas the way to reach the playback engine; that makes the YouTube, Cloudflare and Spotify engine typings stable too.@videojs/htmland@videojs/reactroots:*State/*Props/option types, including the feat(core): add deriveCustomStatus to display custom actions #3064deriveCustomStatustypes (DeriveCustomStatus,StatusDetails,InputActionEvent,InputActionSource,MediaSnapshot,BuiltInIndicatorStatus)Texttypes@videojs/mediastate, capability, event and track types, includingEngineAdapter, the video-track and audio-rendition contracts, andWithMediaTracksSliderInput(React only, foruseSlider'scomputeState)*Propsit extends under the same name, i18nText, and media'sVideo. Those are importable from@videojs/html, which the maintainer agreed to.MediaErroris a value export of both roots, next to theisMedia*Capableguards, soinstanceof MediaErrorandnew MediaError()work.main: the'use client'directives fix(react): declare client boundaries per module #3079 added to each React module are kept, and the rootindex.tshas none.Checker result on this branch: 0 exports that can't be imported. Tag changes are applied in #3068.
Preview pages
I compared every guide and reference page in this PR's preview with #3067's. The only rendered change is the
playbackTypeandtypeprops now showing| (string & {}):Breaking changes
MediaButtonElementandMediaUIElement(@videojs/html) are now generic over state types rather than a Core class. The maintainer accepted this for RC.Third-party elements that extend
MediaButtonElementorMediaUIElementwith a Core type argument need the new parameters: the component's state type and the player state it reads. A subclass that omits them still compiles, but gets theButtonStateandobjectdefaults. Nothing changes at runtime.EventType,EventListenerForandQueriedElementare removed from@videojs/utils/dom. Utils is internal, and nothing in the repo used them outsidehtml-media-adapter.ts.Testing
pnpm build:packages,pnpm typecheck,pnpm lint,pnpm check:workspacepnpm -F site check:api-stability: 0 exports that can't be imported🤖 Generated with Claude Code
https://claude.ai/code/session_01WLkDiofiR86hzNgRopBotH
Note
Medium Risk
Wide type-surface and breaking generic changes on HTML base classes; runtime behavior is unchanged except
MediaErrorre-export, but consumers extendingMediaButtonElementmust update type parameters.Overview
Makes every stable type importable from
@videojs/reactand@videojs/html(plus media adapter entry points), satisfying the API stability checker from the earlier stack PRs. Apart from exportingMediaErroras a value, changes are type-only.The framework package roots gain large type-only re-exports of core component
*State/*Props/option types, i18n types, and@videojs/mediacontracts. Eachdefine/media/*and Reactmedia/*entry re-exports adapter types (e.g.HlsJsAdapter,YouTubeSource) from the underlying adapter packages.Component APIs stop referencing
*Coreclasses in public signatures. React and HTML elements use standalone types likePlayButtonStateandCorePlayButtonPropsinstead ofPlayButtonCore.State/PlayButtonCore.Props. HTMLMediaButtonElementandMediaUIElementare now generic over component state and media state (breaking for subclasses that passed a Core class). Several framework-only members are marked@internal.Supporting type refactors:
MergedConfigreplacesSimplify/UnionToIntersectionfor union player config;MediaStreamType,MediaReadyStateValue, and hls.jsPlaybackType/SourceTypebecome explicit literal unions (still allowing arbitrary strings where noted); DOM helper typesQueriedElement/EventType/EventListenerFormove intohtml-media-adapter.tsand are dropped from@videojs/utils/dom; skin elements annotatestatic stylesexplicitly.Reviewed by Cursor Bugbot for commit e65a3c7. Bugbot is set up for automated code reviews on this repo. Configure here.