@banou/media-player 0.8.3 → 0.8.5

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,9 +23,30 @@ 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
 
+  /**
+   * Draw the control bar. Defaults to true.
+   *
+   * 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.
@@ -105,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
 
@@ -177,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)),
     })
@@ -203,6 +237,7 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
       onVideoRef={remote ? undefined : setVideo}
       onCanvasRef={setCanvas}
       overlay={options.overlay}
+      controls={options.controls}
     >
       {children}
     </Chrome>
@@ -222,6 +257,45 @@ const rootStyle = css`
    */
   --mp-unit: 10px;
 
+  /**
+   * The chrome's own typeface, for exactly the reason the unit above exists.
+   *
+   * \`font-family\` inherits, and this library declared it nowhere, so every label drew in whatever the
+   * embedding document happened to set, and in the UA's serif where it set nothing. Not hypothetical:
+   * stub mounts the player in a second document, \`embed.html\`, which sets no font and loads no face,
+   * and the entire settings menu came out in Times New Roman.
+   *
+   * Named faces only, no bundled webfont. The chrome is a handful of short labels, so a font request
+   * on the critical path of a document whose job is to paint video buys a round trip and a flash of
+   * unstyled text for nothing.
+   *
+   * Read through \`var()\` so a host with a brand face sets \`--mp-font-family\` on any ancestor and it
+   * inherits in. A bare \`font-family\` on the host can no longer reach the chrome: this declaration is
+   * on the player element itself and beats anything inherited.
+   */
+  font-family: var(
+    --mp-font-family,
+    system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif,
+    'Apple Color Emoji', 'Segoe UI Emoji', 'Noto Color Emoji'
+  );
+
+  /**
+   * The chrome's default ink, same argument again.
+   *
+   * Most text here names its own colour, but the two time readouts do not: the elapsed/duration pair
+   * and the seekbar's hover time carry a font token and a black text-shadow and nothing else.
+   * Inherited from a host that declares none that resolves to \`canvastext\`, which is black text under
+   * a black halo on a dark gradient.
+   */
+  color: #fff;
+
+  /**
+   * The settings menu scrolls, and a UA that has not been told the surface is dark paints that
+   * scrollbar in its light theme: a white track down the side of a #1c1c1c menu. Declared here rather
+   * than asked of the host, so it reaches the menu and nothing outside the player.
+   */
+  color-scheme: dark;
+
   /**
    * The other half of owning the chrome's own scale.
    *