@banou/media-player 0.8.2 → 0.8.4

package/src/lib/react/source-feature.ts

@@ -13,6 +13,13 @@ import { definePlayerFeature } from '@videojs/core/dom'
 export type TrackChoice = {
   id: string | number
   label: string
+  /**
+   * Offered but not selectable, so the menu shows it and refuses the click.
+   *
+   * Hiding it instead would be worse: a source that lists a dub it cannot currently serve is telling
+   * the viewer the dub exists, and a menu that silently omits it looks like the source has nothing.
+   */
+  disabled?: boolean
 }
 
 /**
@@ -47,14 +54,25 @@ export type SourceState = {
    */
   thumbnailAt?: (time: number) => ThumbnailImage | undefined
 
+  /**
+   * Both selectors may answer with a promise, and the menu waits on it.
+   *
+   * The engine switches a track by pointing the pipeline at another stream, which is immediate and
+   * cannot fail, so locally these return nothing. A source that owns its own player is the opposite
+   * case: the switch is a round trip through somebody else's UI and takes seconds, and it can lose.
+   * A menu that closed on the click would report a selection that has not happened, and a rejection
+   * with nothing awaiting it is an unhandled rejection rather than an error the viewer ever sees.
+   */
   subtitleTracks: TrackChoice[]
   /** undefined means subtitles are off. */
   selectedSubtitleTrack: string | number | undefined
-  selectSubtitleTrack: (id: string | number | undefined) => void
+  selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>
+  /** What the row that turns subtitles off is called, when the source would rather name it itself. */
+  subtitleOffLabel?: string
 
   audioTracks: TrackChoice[]
   selectedAudioTrack: string | number | undefined
-  selectAudioTrack: (id: string | number) => void
+  selectAudioTrack: (id: string | number) => void | Promise<void>
 
   /** Chrome auto-hide. True means the controls, title and cursor are hidden. */
   hideUI: boolean

package/src/lib/react/video-player.tsx

@@ -23,17 +23,51 @@ export type MediaPlayerSource =
 
 /** Shared by both arms: nothing here depends on who owns the media. */
 type CommonOptions = {
+  /**
+   * Drawn across the top of the picture, in a layer of its own.
+   *
+   * That layer cannot see an `overlay` item, so an app that also places something along the top has
+   * two elements competing for one band of screen: on a narrow viewport the title ellipsizes against
+   * the FULL width and then runs underneath whatever is painted over it. An app in that position
+   * should leave this unset and draw the title as part of its own overlay row, where the two can
+   * share a flex line and the filename can be the one that gives way.
+   */
   title?: string
   autoplay?: boolean
 
   /**
-   * The app's own readout, drawn at the right of the top bar beside `title`, for whatever it has to
-   * say over the video. It shares the title's gradient and fades with the rest of the chrome, so a
-   * running counter does not sit over the picture once the controls have hidden themselves.
+   * Draw the control bar. Defaults to true.
    *
-   * The slot itself takes no pointer events, so a click still reaches the video and toggles
-   * playback; content that needs a pointer (a tooltip anchor, a button) sets `pointer-events: auto`
-   * on itself. `children` land next to the media instead, below the chrome.
+   * False leaves the picture, the title and the overlay and takes away only the chrome, for a host
+   * that has to put its own interactive UI over the media for a while. A source whose sign-in form
+   * lives inside its own document is the case this exists for: the form is the thing the viewer has
+   * to reach, and a control bar for a media that has not loaded yet sits on top of it and eats the
+   * clicks. Hiding it from the host side is not an option, since `setHideUI` is installed by the
+   * store's `attach` and does nothing at all until a media arrives.
+   */
+  controls?: boolean
+
+  /**
+   * The app's own content over the video: a download readout, a badge, a logo, anything the player
+   * itself has no opinion about.
+   *
+   * Pass one node, or several, and EACH TOP-LEVEL ITEM gets its own layer covering the whole player.
+   * That layer is the coordinate space, so an item is placed with ordinary CSS against the picture:
+   *
+   * ```tsx
+   * <MediaPlayer overlay={[
+   *   <div key="stats" css={css`position: absolute; top: 0; right: 0;`}>82 peers</div>,
+   *   <div key="badge" css={css`position: absolute; inset: auto auto 0 0;`}>4K</div>,
+   * ]} />
+   * ```
+   *
+   * A fragment works the same way. Items never share a containing block, so one item's CSS cannot
+   * move another, and each keeps its own DOM as the list changes.
+   *
+   * Items fade with the rest of the chrome, so a running counter does not sit over the picture once
+   * the controls have hidden themselves. A layer takes no pointer events, so a click still reaches
+   * the video and toggles playback; content that needs a pointer (a tooltip anchor, a button) sets
+   * `pointer-events: auto` on itself. `children` land next to the media instead, below the chrome.
    */
   overlay?: ReactNode
 
@@ -92,7 +126,16 @@ export type MediaPlayerLocalOptions =
 export type MediaPlayerRemoteOptions =
   & CommonOptions
   & {
-    media: PlayerMedia
+    /**
+     * Null means the media has not been found yet: the chrome renders and attaches when it arrives.
+     *
+     * A source usually has to mount its own document before it can hand over an element, and that
+     * document is passed as `children`, so it can only exist once this component has rendered. The
+     * key is still REQUIRED even when the value is null, because its presence is what selects this
+     * arm: omitting it falls through to the local arm, which draws an idle `<video>` over whatever
+     * the children put there.
+     */
+    media: PlayerMedia | null
     read?: never
     size?: never
 
@@ -164,19 +207,23 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
   // the document, and it renders the result itself.
   const subtitles = remote?.subtitles?.selection
   const audio = remote?.audioTracks?.selection
+  // `select` is published as-is rather than wrapped, so its promise reaches the menu: the menu is the
+  // only place that can hold the popover open, keep the tick off an unfinished switch, and show a
+  // failure, and a promise nothing awaits is an unhandled rejection.
   useEffect(() => {
     if (!subtitles) return
     setSourceState({
-      subtitleTracks: subtitles.options.map(({ id, label }) => ({ id, label })),
+      subtitleTracks: subtitles.options.map(({ id, label, disabled }) => ({ id, label, disabled })),
       selectedSubtitleTrack: subtitles.selectedId ?? undefined,
       selectSubtitleTrack: (id) => subtitles.select(id == null ? null : String(id)),
+      subtitleOffLabel: subtitles.offLabel,
     })
   }, [setSourceState, subtitles])
 
   useEffect(() => {
     if (!audio) return
     setSourceState({
-      audioTracks: audio.options.map(({ id, label }) => ({ id, label })),
+      audioTracks: audio.options.map(({ id, label, disabled }) => ({ id, label, disabled })),
       selectedAudioTrack: audio.selectedId ?? undefined,
       selectAudioTrack: (id) => audio.select(String(id)),
     })
@@ -190,6 +237,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
       onVideoRef={remote ? undefined : setVideo}
       onCanvasRef={setCanvas}
       overlay={options.overlay}
+      controls={options.controls}
     >
       {children}
     </Chrome>